Отправка заявок с сайта по API

Читать 15

Назначение

API - это программный интерфейс для внешних программных продуктов. Рассматриваемый в данном разделе API интерфейс позволяет получить статистику о заявках, которая может быть проанализирована другими системами, и на основе которой клиенты сервиса могут сделать свои выводы и прогнозы, интегрировать данные в CRM, или другие сервисы.

 

API-метод для создания заявок

Запрос


Поддерживаемые методы отправки: GET и POST.

API-запрос:

https://api.calltouch.ru/calls-service/RestAPI/requests/{site_id}/register/   
Где:
  • {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Интеграции => API и WebhooksI =>  ID личного кабинета":

______________2019-06-13___12.45.45.png

advice_ver2.png API-токен для создания заявок не требуется.

Параметры запроса:

Параметр Описание
subject

Произвольное название формы на Вашем сайте, с которой отправляется заявка в Calltouch. В последствие переданное название формы отображается в одноименном столбце журнала заявок:

subject.png

В качестве названия формы может быть передано строковое значение до 256 символов.

requestNumber

Уникальный идентификатор заявки на Вашем сайте. В качестве идентификатора может быть передано строковое значение до 256 символов. Переданный идентификатор отображается в столбце "Номер заявки" журнала заявок над названием формы:

requestNumber.png

Параметр является необязательным, если его не передавать, то вместо него в журнале заявок будет отображаться уникальный идентификатор заявки в Calltouch.

requestDate

Дата и время отправки заявки в формате: dd.mm.yyyy%20hh:mm:ss. Дата и время заявки отображается в одноименном столбце "Журнала заявок":

requestDate.png

Параметр является необязательным, если его не передавать, то заявке будет автоматически присвоена текущая дата и время отправки API-запроса на создание заявки.

sessionId

Идентификатор сессии Calltouch. С помощью него Calltouch присвоит переданной заявке источник перехода на сайт посетителя, отправившего ее. Идентификатор сессии Calltouch присутствует в коде сайта, с которого отправляется заявка, если в этом коде установлен скрипт отслеживания Calltouch. Чтобы получить ID сессии скрипта Calltouch или проверить отработал ли он или нет, используйте JS-функцию calltracking_params., например:

window.ct('calltracking_params','mod_id').sessionId

Где вместо mod_id нужно указать идентификатор скрипта Calltouch.

Определившийся источник заявки (с помощью переданного значения сессии) будет отображен в журнале заявок:

source.png

Параметр sessionId является необязательным, но если его не передавать, источник заявки не удастся определить как показано на скриншоте выше.

fio

Произвольное имя пользователя, отправившего заявку. Переданное значение отображается в журнале заявок:

fio.png

Параметр является необязательным, но если Вы не передаете имя клиента, то обязательно должны передать хотя бы номер телефона или почту клиента, для его последующей идентификации в журнале заявок.

phoneNumber

Номер телефона. Можно передавать в любом формате, главное чтобы было 11 цифр. Переданный номер автоматически будет приведен к формату 7XXXXXXXXXX и будет отображаться в журнале заявок:

phoneNumber.png

Параметр является необязательным, но если Вы не передаете номер телефона, то обязательно должны передать хотя бы почту или имя клиента, для его последующей идентификации в журнале заявок.

advice_ver2.png Последние 4 цифры номера при необходимости могут быть скрыты сотрудникам Calltouch, см. раздел "Защита данных" в настройках статистики.

email

Почта клиента. Переданная почта отображается в журнале заявок:

email.png

Параметр является необязательным, но если Вы не передаете почту клиента, то обязательно должны передать хотя бы номер телефона или имя клиента, для его последующей идентификации в журнале заявок.

advice_ver2.png Часть почты после знака @ при необходимости могут быть скрыты сотрудникам Calltouch, см. раздел "Защита данных" в настройках статистики.

comment

Комментарий к заявке. Необязательный параметр. Произвольный текст, в качестве которого может быть передано любое необходимое значение. Переданный комментарий отображается в журнале заявок ЛК, оставленный от имени "API":

Screenshot_2018-08-02_at_15.55.56.png

tags

Произвольные теги. Необязательный параметр. Можно передавать несколько тегов через запятую. С помощью тегов заявки можно будет фильтровать в отчетах Calltouch.

Screenshot_2020-06-10_at_12.43.29.png

requestUrl

Адрес страницы, с которой отправляется заявка. При отправке формы с сайта можно использовать переменную браузера location.href, чтобы передать в requestUrl страницу отправки формы.

Screenshot_2020-06-10_at_12.43.40.png

customField[fieldName]

Данные по пользовательским полям в заявке.

Формат: customField[fieldName]=fieldValue
где:
fieldName - название пользовательского поля в API
fieldValue - значение пользовательского поля.

Важно: Данные в API-запросе должны передаваться в кодировке utf-8.

advice_ver2.png Если не указано ни одного входного параметра - заявка не будет создана и будет выведена ошибка "Не возможно создать заявку - не указано ни одного входного параметра". HTTP-код ответа ошибки: 200.

Пример GET-запроса на создание заявки

GET-запрос:

https://api.calltouch.ru/calls-service/RestAPI/requests/18990/register/?subject=Моя форма&requestNumber=zi0D8c0c&requestUrl=http://test.ru&sessionId=1845461367&fio=Вася&email=vasya@mail.ru&phoneNumber=79205550055
   
Создаст в ЛК Calltouch сайта с идентификатором 18990 следующую заявку:

requests_journal.png

Формат тела запроса при использовании метода POST

При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":

параметр1=значение1&параметр2=значение2&...   
При использовании метода POST, одним API-запросом можно создать только одну заявку.

 

Ответ


После успешной отправки API-запроса на создание заявки, возвращается следующий JSON-ответ:

{
    "date": 1522047600000,
    "requestType": "CLIENT_ORDER",
    "dateStr": "26/03/2018 10:00:00",
    "session": {
        "keywords": "",
        "city": "vladimir",
        "ip": "95.66.182.68",
        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
        "source": "yandex",
        "medium": "cpc",
        "ref": "",
        "url": "http://filipok.io/calltouch/?utm_source=yandex&utm_medium=cpc&attrs={\"attrh\":1,\"ver\":171110,\"r7k12_si\":1156810694}",
        "utmSource": "yandex",
        "utmMedium": "cpc",
        "utmTerm": "",
        "utmContent": "",
        "utmCampaign": "",
        "guaClientId": null,
"yaClientId": null, "sessionId": 1845461367, "additionalTags": [], "attribution": 1,
"attrs": null }, "subject": "Моя форма",
"uniqTargetRequest": false,
"uniqueRequest": false,
  "yandexDirect": null,
"googleAdWords": null,
"requestNumber": "zi0D8c0c",
"requestId": 5222102, "client": { "fio": "Вася", "clientId": 37633316, "phones": [ { "phoneNumber": "79205550055", "phoneType": "OTHER" } ], "contacts": [ { "contactType": "EMAIL", "contactValue": "vasya@mail.ru" } ] },
"orders": [],
"targetRequest": false,
"status": "NOT_SET", "order": null }

JSON-объекты:

Объект Описание
date Дата и время создания заявки в формате Unix Timestamp в миллисекундах.
requestNumber Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте requestId далее).
dateStr Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss.
session

Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:

  • keywords - ключевой запрос
  • city - город посетителя (определяется по его IP-адресу)
  • ip - IP-адрес
  • browser - Браузер
  • source - Источник перехода
  • medium - Канал перехода
  • ref - адрес страницы, с которой был совершен реферальный переход на Ваш отслеживаемый сайт (присутствует только если переход посетителя был реферальным)
  • url - адрес входа на сайт (может отличаться от страницы, с которой в итоге был совершен звонок)
  • utmSource - значение utm-метки utm_source
  • utmMedium - значение utm-метки utm_medium
  • utmTerm - значение utm-метки utm_term
  • utmContent - значение utm-метки utm_content
  • utmCampaign - значение utm-метки utm_campaign
  • guaClientId - идентификатор Google Client ID (присутствует, если настроена интеграция с Google Analytics)
  • yaClientId - идентификатор Yandex Client ID (присутствует, если настроена интеграция с Яндекс.Метрика)
  • sessionId - идентификатор сессии Calltouch, который Вы отправили в запросе ранее
  • attribution - текущая модель атрибуции, согласно которой определился источник заявки (модель атрибуции может быть изменена в системных настройках ЛК, после этого источники будут "на лету" переопределены у всех звонков и заявок ранее)
  • attrs - Сторонние параметры, переданные заранее в статистику Calltouch.

Если Вы не отправляли идентификатор сессии или произвольные источники в запросе на регистрацию заявки, то объект будет равен значению null.

requestId Уникальный идентификатор заявки в Calltouch.
subject Название формы на Вашем сайте, которое Вы отправили в запросе.
uniqTargetRequest Уникально-целевая заявка. Может принимать следующие значения:
  • true (уникально-целевая заявка)
  • false (не уникально-целевая заявка)
uniqueRequest Уникальная заявка. Может принимать следующие значения:
  • true (уникальная заявка)
  • false (повторная заявка)
client

Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:

  • fio - имя клиента
  • clientId - идентификатор клиента внутри Calltouch
  • phones - содержит массив, внутри которого в объекте phoneNumber содержится номер телефона клиента
  • contacts - содержит массив, внутри которого в объекте contactValue содержится почта клиента
orders Здесь будет массив всех сделок, связанных с заявкой. На момент создания заявки пустой.
targetRequest Целевая заявка. Может принимать следующие значения:
  • true (целевая заявка)
  • false (не целевая заявка)

 

advice_ver2.pngJSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.

Подключение к отслеживанию заявок с форм сайта

Суть подключения состоит в том, чтобы по событию отправки формы на Вашем сайте, выполнялся скрипт, который будет отправлять в Calltouch API-запрос на создание заявки. Реализовать подключение можно либо на клиентской стороне, либо на серверной. Оба способа описаны в статье Как подключить заявки с сайта к отслеживанию Calltouch.

Система баллов API Calltouch

Система баллов API - механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch

Количество запросов в секунду к API Calltouch ограничено – не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой.