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

Читать 14

Назначение

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 личного кабинета.
API-токен для создания заявок не требуется.

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

Параметр Описание
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, см. раздел "Защита данных" в настройках статистики.
email

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


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

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

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


tags

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


requestUrl

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


customField[fieldName]

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

Пользовательские поля API. Для использования их необходимо заранее добавить в настройках API ЛК Calltouch.

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

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

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

Если не указано ни одного входного параметра — заявка не будет создана и будет выведена ошибка "Не возможно создать заявку - не указано ни одного входного параметра". 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 следующую заявку:


Формат тела запроса при использовании метода 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 (не целевая заявка)

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

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

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

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

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

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

Не нашли решение проблемы?
Заполните форму, и мы вам поможем.
х
Заполните форму
и мы поможем вам
Похожие статьи
Недавно просмoтренные