Назначение API
API - это программный интерфейс для внешних программных продуктов. Рассматриваемый в данном разделе API интерфейс позволяет получить статистику о заявках, которая может быть проанализирована другими системами, и на основе которой клиенты сервиса могут сделать свои выводы и прогнозы, интегрировать данные в CRM, или другие сервисы.
API-метод для создания заявок
Запрос
Поддерживаемые методы отправки: GET и POST.
API-запрос:
Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
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 и будет отображаться в журнале заявок:
Параметр является необязательным, но если Вы не передаете номер телефона, то обязательно должны передать хотя бы почту или имя клиента, для его последующей идентификации в журнале заявок.
|
|
Почта клиента. Переданная почта отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете почту клиента, то обязательно должны передать хотя бы номер телефона или имя клиента, для его последующей идентификации в журнале заявок.
|
|
| comment |
Комментарий к заявке. Необязательный параметр. Произвольный текст, в качестве которого может быть передано любое необходимое значение. Переданный комментарий отображается в журнале заявок ЛК, оставленный от имени "API":
|
| tags |
Произвольные теги. Необязательный параметр. Можно передавать несколько тегов через запятую. С помощью тегов заявки можно будет фильтровать в отчетах Calltouch.
|
| requestUrl |
Адрес страницы, с которой отправляется заявка. При отправке формы с сайта можно использовать переменную браузера location.href, чтобы передать в requestUrl страницу отправки формы.
|
Если не указано ни одного входного параметра - заявка не будет создана и будет выведена ошибка "Не возможно создать заявку - не указано ни одного входного параметра". HTTP-код ответа ошибки: 200.
Пример GET-запроса на создание заявки
GET-запрос:
Создаст в ЛК Calltouch сайта с идентификатором 18990 следующую заявку:
Формат тела запроса при использовании метода POST
При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":
При использовании метода 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 |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
| requestId | Уникальный идентификатор заявки в Calltouch. |
| subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
| uniqTargetRequest | Уникально-целевая заявка. Может принимать следующие значения:
|
| uniqueRequest | Уникальная заявка. Может принимать следующие значения:
|
| client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
| orders | Здесь будет массив всех сделок, связанных с заявкой. На момент создания заявки пустой. |
| targetRequest | Целевая заявка. Может принимать следующие значения:
|
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
API-метод для выгрузки заявок
Посмотреть создавшиеся заявки можно не только в интерфейсе Calltouch, но и получить их выгрузку в формате JSON через API.
Запрос
Поддерживаемый метод отправки: GET.
API-запрос:
Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
Параметры запроса:
| Параметр | Описание |
| clientApiId |
Обязательный параметр. В отличие от API-запроса на создание сделки, в API-запросе на их выгрузку требуется указывать токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
| dateFrom | Обязательный параметр. Начальная дата создания заявок, с которой они будут выгружены. Формат mm/dd/yyyy. |
| dateTo | Обязательный параметр. Конечная дата создания заявок, до которой они будут выгружены. Формат mm/dd/yyyy. |
| timeFrom | Время начала периода выгрузки в формате hh:mm:ss. Необязательный параметр. |
| timeTo | Время конца периода выгрузки в формате hh:mm:ss. Необязательный параметр. |
| subject | Необязательный параметр. В качестве его значения можно указать название формы, для выгрузки только тех заявок, которые были сделаны с этой формы. Поиск среди заявок происходит по названию формы, которое "начинается с" указанного значения в параметре subject. |
| keywords | Необязательный параметр. В качестве его значения можно указать ключевой запрос, по которому пользователь совершил переход на отслеживаемый сайт и оставил заявку - в этом случае Поиск среди заявок происходит по ключевому запросу, который "содержит" указанное значение в параметре keywords. |
| city | Необязательный параметр. В качестве его значения можно указать название города, для выгрузки только тех заявок, которые были сделаны пользователем из этого города. Поиск среди заявок происходит по названию города, которое "полностью совпадает" с указанным значением в параметре city. Название городов указываются в формате базы данных Sypex Geo. |
| source | Необязательный параметр. В качестве его значения можно указать название источника, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого источника. Поиск среди заявок происходит по названию источника, которое "полностью совпадает" с указанным значением в параметре source. |
| medium | Необязательный параметр. В качестве его значения можно указать название канала, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого канала. Поиск среди заявок происходит по названию канала, которое "полностью совпадает" с указанным значением в параметре medium. |
| bindTo |
Необязательный параметр. Флаг выгрузки заявок с привязкой к разным метрикам. Возможные значения:
|
| ani.value |
Необязательный параметр. В качестве его значения можно указать телефонный номер, для выгрузки только тех заявок, в которых был указан этот телефонный номер. |
| ani.filterMode |
Режим фильтрации предыдущего параметра по номеру телефона, оставленного в заявке. Описание режимов смотри ниже. |
| email.value |
Необязательный параметр. В качестве его значения можно указать электронную почту, для выгрузки только тех заявок, в которых была указана эта электронная почта. |
| email.filterMode |
Режим фильтрации предыдущего параметра по электронной почте, оставленной в заявке. Описание режимов смотри ниже. |
| withMapVisits |
Флаг истории посещений посетителя, оставившего заявку. Формат: withMapVisits=true - включить в ответ историю посещений, withMapVisits=false или отсутствие параметра - не включать. |
| withRequestTags |
Флаг выгрузки тегов, которые были присвоены заявкам. Формат: withRequestTags=true - включить в ответ теги заявок, withRequestTags=false или отсутствие параметра - не включать. |
| withYandexDirect |
Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Яндекс.Директ. Если входной параметр withYandexDirect = true, то в выгрузке присутствует выходной параметр yandexDirect, если withYandexDirect = false или не указан, то выходной параметр yandexDirect отсутствует. |
| withGoogleAdwords | Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Google AdWords. Если входной параметр withGoogleAdwords = true, то в выгрузке присутствует выходной параметр googleAdWords, если withGoogleAdwords = false или не указан, то выходной параметр googleAdWords отсутствует. |
| withAttrs | Флаг выгрузки сторонних параметров, переданных заранее в статистику Calltouch. Возможные значения: 1. Флаг withAttrs=false или не указан, по умолчанию. Сторонние параметры не выгружаются, значение выходного параметра attrs=null. 2. Флаг withAttrs=true. Сторонние параметры выгружаются в выходной параметр attrs. Если их нет, то значение выходного параметра attrs=null. |
| manager | Необязательный параметр. В качестве его значения можно указать ФИО менеджера, для выгрузки только тех заявок, которым был присвоен этот менеджер с помощью API-метода присвоения менеджеров к лидам. |
Для выгрузки данных только по одной определенной заявки, используйте API-запрос:
Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {requestNumber} - внешний ID заявки. Указывается без фигурных скобок. Его можно получить в JSON-ответе на API-запрос создания заявки.
В качестве параметров, в нем необходимо указать только токен clientApiId (см. таблицу выше).
Режимы фильтрации
Выборку некоторых параметров выше, имя которых параметр.filterMode, можно дополнительно отфильтровать:
- startwith – начинается с
- contains – содержит
- exact – полное соответствие (по умолчанию если фильтр не задан)
Примеры GET-запросов на выгрузку заявок
- Выгрузка нескольких заявок
Запрос далее выгрузит заявки, созданные за период с 28 марта по 4 апреля 2019 года:
- Выгрузка одной заявки
Запрос далее выгрузит заявку с идентификатором 79825254:
Ответ
После успешной отправки API-запроса на выгрузку заявок, возвращается следующий JSON-ответ:
[
{
"date": 1554382259240,
"comments": [
{
"commentId": 7319,
"requestId": 145507,
"comment": "Колин комментарий",
"partyId": 19688,
"partyName": "API"
}
],
"requestType": "CLIENT_ORDER",
"dateStr": "04/04/2019 15:50:59",
"manager": "Вася",
"session": {
"keywords": "(not set)",
"city": "moscow",
"ip": "95.163.114.76/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"source": "(direct)",
"medium": "(none)",
"ref": "",
"url": "https://alftest.ru/calltouch/supertest/",
"utmSource": "<не указано>",
"utmMedium": "<не указано>",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"utmCampaign": "<не указано>",
"guaClientId": null,
"yaClientId": null,
"sessionId": 16441053,
"additionalTags": [],
"attribution": 1,
"attrs": null
},
"subject": "Заявка на звонок",
"uniqTargetRequest": true,
"mapVisits": [
{
"utmSource": "<не указано>",
"sessionDate": "03/04/2019 16:02:51",
"city": "moscow",
"ip": "95.163.114.76/32",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"sessionId": 15952760,
"source": "(direct)",
"medium": "(none)",
"utmCampaign": "<не указано>",
"url": "https://alftest.ru/calltouch/supertest/",
"ref": "",
"additionalTags": [],
"utmMedium": "<не указано>",
"guaClientId": null,
"keyword": "(not set)"
},
{
"utmSource": "<не указано>",
"sessionDate": "04/04/2019 15:50:34",
"city": "moscow",
"ip": "95.163.114.76/32",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"sessionId": 16441053,
"source": "(direct)",
"medium": "(none)",
"utmCampaign": "<не указано>",
"url": "https://alftest.ru/calltouch/supertest/",
"ref": "",
"additionalTags": [],
"utmMedium": "<не указано>",
"guaClientId": null,
"keyword": "(not set)"
}
],
"uniqueRequest": true,
"requestNumber": "145507",
"requestId": 145507,
"client": {
"fio": "Коля",
"clientId": 640236,
"phones": [
{
"phoneNumber": "79991234567",
"phoneType": "OTHER"
}
],
"contacts": [
{
"contactType": "EMAIL",
"contactValue": "kolya@yandex.ru"
}
]
},
"orders": [
{
"orderId": 119901,
"callId": null,
"dateCreated": 1554382620000,
"status": "PENDING",
"realSum": "2800.0000",
"offered": null,
"sent": "04.04.2019",
"sum": "2800.0000",
"isMarked": null,
"commentsCount": 0,
"currentAmount": 2800,
"orderNumber": "119901",
"orderSum": "2800.0000",
"orderStatus": "PENDING",
"orderComments": "",
"session": {
"keywords": "(not set)",
"city": "moscow",
"ip": "95.163.114.76/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"source": "(direct)",
"medium": "(none)",
"ref": "",
"url": "https://alftest.ru/calltouch/supertest/",
"utmSource": "<не указано>",
"utmMedium": "<не указано>",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"utmCampaign": "<не указано>",
"guaClientId": null,
"yaClientId": null,
"sessionId": 16441053,
"additionalTags": [],
"attribution": 1,
"attrs": null
}
}
],
"targetRequest": true,
"status": "NOT_SET",
"order": {
"orderId": 119901,
"callId": null,
"dateCreated": 1554382620000,
"status": "PENDING",
"realSum": "2800.0000",
"offered": null,
"sent": "04.04.2019",
"sum": "2800.0000",
"isMarked": null,
"commentsCount": 0,
"currentAmount": 2800,
"orderNumber": "119901",
"orderSum": "2800.0000",
"orderStatus": "PENDING",
"orderComments": "",
"session": {
"keywords": "(not set)",
"city": "moscow",
"ip": "95.163.114.76/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"source": "(direct)",
"medium": "(none)",
"ref": "",
"url": "https://alftest.ru/calltouch/supertest/",
"utmSource": "<не указано>",
"utmMedium": "<не указано>",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"utmCampaign": "<не указано>",
"guaClientId": null,
"yaClientId": null,
"sessionId": 16441053,
"additionalTags": [],
"attribution": 1,
"attrs": null
}
}
},
...
{
...
}
]JSON-объекты:
| Объект | Описание |
| date | Дата и время создания заявки в формате Unix Timestamp в миллисекундах. |
| comments |
Комментарии к заявкам. Возможные значения:
Где вложенные объекты элемента массива:
Обратите внимание, в конце комментария comment может присутствовать символ \n. Он означает перенос строки, не забудьте учесть это при парсинге параметров. |
| requestNumber | Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. далее). |
| dateStr | Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. |
| manager | ФИО менеджера, который был присвоен заявке с помощью API-метода присвоения менеджеров к лидам. Если у заявки нет менеджера, передается значение null. |
| session |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
| requestId | Уникальный идентификатор заявки в Calltouch. |
| subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
| uniqTargetRequest | Уникально-целевая заявка. Может принимать следующие значения:
|
| uniqueRequest | Уникальная заявка. Может принимать следующие значения:
|
| client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
| targetRequest |
Целевая заявка. Может принимать следующие значения:
|
| orders |
Массив всех сделок, связанных с заявкой. Для каждой сделки будет содержать вложенные объекты с описанием сделки, связанной с заявкой, если таковые были созданы (см. статью Управление сделками через API). Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, массив будет пустой. |
| mapVisits |
История посещений. Параметр присутствует в случае, если указан входной параметр истории посещений withMapVisits=true. Результат будет содержать все посещения пользователя оставившего заявку на сайте,
|
| yandexDirect |
Если источник звонка или заявки рекламная кампания Яндекс.Директ, между Calltouch и Яндекс.Директ включена интеграция, то в данном параметре выводится следующая информация:
"yandexDirect": { "campaignId": 32515134, "adGroupId": 325245212134, "adId": 2546356252, "criteriaId": 254251323 } Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): "yandexDirect": null |
| googleAdWords | Если источник звонка или заявки рекламная кампания Google AdWords, между Calltouch и Google AdWords включена интеграция, то в данном параметре выводится следующая информация:
"googleAdWords": { "campaignId": 35635656, "adGroupId": 134524245, "creativeId": 23134141, "criteriaId": 4324553542 } Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): "googleAdWords": null |
| attrs | Сторонние параметры, переданные заранее в статистику Calltouch. Выгружаются, если во входных параметрах был передан флаг withAttrs=true. Возможные значения:
attrs: {"param1":"value1","param2":"value2"}
|
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
Данные из Яндекс.Директ и Google AdWords подгружаются в Calltouch на следующий день после фиксирования звонка или заявки. Если данные обновляются на стороне Яндекс.Директ или Google AdWords (они могут обновиться 4 раза в месяц), то они будут изменены и в API-выгрузке.
Подключение к отслеживанию заявок с форм сайта
Суть подключения состоит в том, чтобы по событию отправки формы на Вашем сайте, выполнялся скрипт, который будет отправлять в Calltouch API-запрос на создание заявки. Реализовать подключение можно либо на клиентской стороне, либо на серверной. Оба способа описаны в статье Как подключить заявки с сайта к отслеживанию Calltouch.
Кол-во запросов в секунду к API Calltouch ограничено – не более 5 запросов (+5 запросов в очередь) в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, 5 поставятся в очередь, и 1 API-запрос завершится с ошибкой.
0 Комментарии