Отправка заявок с сайта по API
Назначение
API — это программный интерфейс для внешних программных продуктов. Рассматриваемый в данном разделе API интерфейс позволяет получить статистику о заявках, которая может быть проанализирована другими системами, и на основе которой клиенты сервиса могут сделать свои выводы и прогнозы, интегрировать данные в CRM, или другие сервисы.
API-метод для создания заявок
Запрос
Поддерживаемые методы отправки: GET и POST.
API-запрос:
https://api.calltouch.ru/calls-service/RestAPI/requests/{site_id}/register/
Где:
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе: Интеграции / Отправка данных во внешние системы / API и Webhooks / ID личного кабинета.
Параметры запроса:
Параметр | Описание |
subject |
Произвольное название формы на Вашем сайте, с которой отправляется заявка в Calltouch. В последствие переданное название формы отображается в одноименном столбце журнала заявок:
В качестве названия формы может быть передано строковое значение до 256 символов. |
requestNumber |
Уникальный идентификатор заявки на Вашем сайте. В качестве идентификатора может быть передано строковое значение до 256 символов. Переданный идентификатор отображается в столбце "Номер заявки" журнала заявок над названием формы:
Параметр является необязательным, если его не передавать, то вместо него в журнале заявок будет отображаться уникальный идентификатор заявки в Calltouch. |
requestDate |
Дата и время отправки заявки в формате: dd.mm.yyyy%20hh:mm:ss. Дата и время заявки отображается в одноименном столбце "Журнала заявок":
Параметр является необязательным, если его не передавать, то заявке будет автоматически присвоена текущая дата и время отправки API-запроса на создание заявки. |
sessionId |
Идентификатор сессии Calltouch. С помощью него Calltouch присвоит переданной заявке источник перехода на сайт посетителя, отправившего ее. Идентификатор сессии Calltouch присутствует в коде сайта, с которого отправляется заявка, если в этом коде установлен скрипт отслеживания Calltouch. Чтобы получить ID сессии скрипта Calltouch или проверить отработал ли он или нет, используйте JS-функцию calltracking_params., например:
window.ct('calltracking_params','mod_id').sessionId
Где вместо mod_id нужно указать идентификатор скрипта Calltouch. Определившийся источник заявки (с помощью переданного значения сессии) будет отображен в журнале заявок:
Параметр sessionId является необязательным, но если его не передавать, источник заявки не удастся определить как показано на скриншоте выше. |
fio |
Произвольное имя пользователя, отправившего заявку. Переданное значение отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете имя клиента, то обязательно должны передать хотя бы номер телефона или почту клиента, для его последующей идентификации в журнале заявок. |
phoneNumber |
Номер телефона. Можно передавать в любом формате, главное чтобы было 11 цифр. Переданный номер автоматически будет приведен к формату 7XXXXXXXXXX и будет отображаться в журнале заявок:
Параметр является необязательным, но если Вы не передаете номер телефона, то обязательно должны передать хотя бы почту или имя клиента, для его последующей идентификации в журнале заявок.
Последние 4 цифры номера при необходимости могут быть скрыты сотрудникам Calltouch, см. раздел "Защита данных" в настройках статистики.
|
Почта клиента. Переданная почта отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете почту клиента, то обязательно должны передать хотя бы номер телефона или имя клиента, для его последующей идентификации в журнале заявок.
Часть почты после знака @ при необходимости могут быть скрыты сотрудникам Calltouch, см. раздел "Защита данных" в настройках статистики.
|
|
comment |
Комментарий к заявке. Необязательный параметр. Произвольный текст, в качестве которого может быть передано любое необходимое значение. Переданный комментарий отображается в журнале заявок ЛК, оставленный от имени "API":
|
tags |
Произвольные теги. Необязательный параметр. Можно передавать несколько тегов через запятую. С помощью тегов заявки можно будет фильтровать в отчетах Calltouch.
|
requestUrl |
Адрес страницы, с которой отправляется заявка. При отправке формы с сайта можно использовать переменную браузера location.href, чтобы передать в requestUrl страницу отправки формы.
|
customField[fieldName] |
Данные по пользовательским полям в заявке. Пользовательские поля API. Для использования их необходимо заранее добавить в настройках API ЛК Calltouch. Поля в ЛК Calltouch могут быть или числовыми, или текстовыми. В числовые можно передавать только цифры, дробная часть отделяется точкой, максимум 100 символов. В текстовые поля допустимо передавать любые символы, максимум 100.
Формат: customField[fieldName]=fieldValue |
Данные в API-запросе должны передаваться в кодировке utf-8.
Пример 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 следующую заявку:
Формат тела запроса при использовании метода 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 |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии или произвольные источники в запросе на регистрацию заявки, то объект будет равен значению null. |
requestId | Уникальный идентификатор заявки в Calltouch. |
subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
uniqTargetRequest |
Уникально-целевая заявка. Может принимать следующие значения:
|
uniqueRequest |
Уникальная заявка. Может принимать следующие значения:
|
client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
orders | Здесь будет массив всех сделок, связанных с заявкой. На момент создания заявки пустой. |
targetRequest |
Целевая заявка. Может принимать следующие значения:
|
Подключение к отслеживанию заявок с форм сайта
Суть подключения состоит в том, чтобы по событию отправки формы на Вашем сайте, выполнялся скрипт, который будет отправлять в Calltouch API-запрос на создание заявки. Реализовать подключение можно либо на клиентской стороне, либо на серверной. Оба способа описаны в статье Как подключить заявки с сайта к отслеживанию Calltouch.
Система баллов API Calltouch
Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch
Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)