Выгрузка журнала сделок
Возможности
В данной статье описан API-метод, позволяющий выгружать список сделок за определенный временной интервал. Помимо этого, вы можете выгрузить определенную сделку по ее идентификатору или же выгрузить сделки по дате сессии / создания / обновления.
Запрос
С помощью данного API-метода Вы можете выгрузить список сделок за указанный временной интервал с детальной информацией по каждой.
Поддерживаемый метод отправки: GET.
API-запрос:
https://api.calltouch.ru/calls-service/RestAPI/{site_id}/orders-diary/orders
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Интеграции => API и Webhooks":

Параметры запроса:
Параметр | Описание |
clientApiId |
Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
dateFrom | Начальная дата создания сделок (параметр orderDate в API-запросах для создания сделок выше), с которой будут выгружены сделки. Формат dd/mm/yyyy. Обязательный параметр, dateFrom должна быть меньше dateTo. |
dateTo | Конечная дата создания сделок (параметр orderDate в API-запросах для создания сделок выше), до которой будут выгружены сделки. Формат dd/mm/yyyy. Обязательный параметр. Если диапазон между dateFrom и dateTo более 1 дня, то выгрузка возможна только с пагинацией страниц – для этого добавьте параметры page и limit (см. ниже). |
timeFrom | Время начала периода выгрузки в формате hh:mm:ss. Необязательный параметр. |
timeTo | Время конца периода выгрузки в формате hh:mm:ss. Необязательный параметр. |
page | Включает пагинацию в JSON-ответе. Используется для выборки статистики по сделкам более чем за один день – для этого в запрос, помимо обязательных входных параметров dateFrom и dateTo, добавьте параметр page, указав его значение равное номеру страницы. На одной странице при этом может быть выгружено не более 1000 сделок. Параметр обязателен, только если диапазон между dateFrom и dateTo более 1 дня. |
limit | Дополнительный необязательный параметр, в котором указывается максимальное количество сделок на странице, максимально возможное значение равно 1000. Если параметр не указан, по умолчанию выгружается 1000 сделок на 1 страницу. Используется только вместе с параметром page. |
orderSource |
Необязательный параметр. По умолчанию выгружаются сделки, созданные и по звонкам и по заявкам. Добавив параметр orderSource со значением:
|
phoneNumber.value | Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, номер телефона клиента в которых совпадает с указанным значением. Если указывается этот параметр, то параметры dateFrom/dateTo/timeFrom/timeTo выше не указываются. |
orderNumber | Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, ID сделки в Calltouch которых совпадает с указанным значением. Если указывается этот параметр, то параметры dateFrom/dateTo/timeFrom/timeTo выше не указываются. |
bindTo |
Необязательный параметр. Флаг выгрузки сделок с привязкой к разным метрикам. Возможные значения:
|
manager | Необязательный параметр. При указании менеджера в выгрузке должны оказаться только те сделки, которые привязаны к этому менеджеру. |
service | Необязательный параметр. Название сервиса, использующего наше API. Можно указать конкретный сервис и в выгрузке должны оказаться только те сделки, у которых указан этот сервис, например, retailCRM. |
withOrdersTags | Необязательный параметр. Флаг выгрузки тегов сделки. Если не указан или равен false, теги не выгружаются. Если указан и равен true, то теги выгружаются JSON-массивом. Если указан и равен true, но тегов нет, параметр равен null. |
withAllOrderOrigins | Необязательный параметр. Флаг выгрузки сделок, созданных любыми методами. Если указан и равен true, то в выгрузке будут присутствовать все сделки, которые есть в ЛК. Если указан и равен false или не указан, то в выгрузке будут присутствовать сделки из ЛК, которые были созданы по API. |
withComments | Необязательный параметр. Флаг выгрузки комментариев к сделке. Если указан и равен true, то в выгрузке будут присутствовать все сделки, у которых есть комментарий. Если указан и равен false или не указан, то в выгрузке будут присутствовать сделки без комментария. |
withAttrs |
Необязательный параметр. Флаг выгрузки сторонних параметров сессии. Возможные значения: false - Сторонние параметры не выгружаются, значение выходного параметра attrs: null. (по умолчанию, если параметр не указан) true - Сторонние параметры выгружаются в выходной параметр attrs. Если их нет, то значение выходного параметра attrs: null. |
withYandexDirect |
Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Яндекс.Директ. Возможные значения: false - выходной параметр yandexDirect: null (по умолчанию, если параметр не указан) true - в выгрузке присутствует выходной параметр yandexDirect. |
withGoogleAdwords |
Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Google AdWords. Возможные значения: false - выходной параметр googleAdWords: null (по умолчанию, если параметр не указан) true - в выгрузке присутствует выходной параметр googleAdWords. |
attribution |
Параметр управляет - согласно какой модели атрибуции надо получать сессию сделки (или сессию лида привязанного к сделке), и данные по этой сессии. Возможные значения: 0 - последнее взаимодействие 1 - последний непрямой (по умолчанию, если параметр не указан) |
Пример GET-запроса на выгрузку сделок
Запрос далее выгрузит сделки сайта с идентификатором 12345, созданные и по звонкам и по заявкам, дата создания (параметр orderDate в API-запросах на создание новых сделок) которых находится между 01/03/2018 и 27/03/2018. В выгрузке включена пагинация (используются параметры page и limit), а так же в ней будет присутствовать массив тегов по каждой сделке (указан флаг withOrdersTags=true).
https://api.calltouch.ru/calls-service/RestAPI/12345/orders-diary/orders?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&dateFrom=01/03/2018&dateTo=27/03/2018&page=1&limit=500&withOrdersTags=true
Ответ
API-запрос выше выгружает только первую страницу выгрузки. Для выгрузки остальных страниц выгрузки, отправьте тот же запрос, но в параметре page указав необходимую страницу выгрузки. После успешной отправки API-запроса на выгрузку списка сделок, возвращается следующий JSON-ответ (пример):
{
"page": 1,
"pageTotal": 4,
"pageSize": 500,
"recordsTotal": 2000,
"records": [ { "client": { "phones": "74953080100", "fio": null }, "completedAmount": null, "completedDate": "15/02/2018", "createdDate": "10/02/2018 08:34:00",
"isDeleted": false,
"manager": "Коля", "orderDate": "10/02/2018 10:00:00", "orderNumber": "HLlHwLqSms5r8e", "orderSource": { "callId": 32949495, "duration": 8, "phoneNumber": "74991121187", "type": "CALL", "ani": "74953080100", "dateCall": "27/03/2018 15:42:04" },
"orderStatus": "final", "plannedAmount": 6000,
"service": "AmoCRM",
"tags": [
"tag1",
"tag2",
], "visit": { "utmSource": "(direct)", "utmTerm": "(not set)", "utmContent": "<не указано>", "visitDate": "15/02/2018 13:05:58",
"utmMedium": "(none)", "source": "(direct)", "medium": "(none)", "keyword": "(not set)", "utmCampaign": "<не указано>", "city": "vladimir", "url": "https://calltouch-test.ru/", "ref": "", "hostName": "calltouch-test.ru", "sessionId": 458571822, "clientId": "1241916806.1678992739", "yaClientId": "1678992939222672376", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36", "ip": "95.66.146.1", "ctClientId": 1000000000304833700, "ctGlobalId": "6b8929ff-78fc-5419-afa8-da85c1f9186b", "attrs": null, "yandexDirect": null, "googleAdWords": null }, "funnel": "Название воронки", "currencyCode": "RUB", "margin": 3, "orderLink": "https://site.ru/HLlHwLqSms5r8e", "orderName": "Название сделки" }, { "client": { "phones": "79000000000", "fio": "Вася", "emails": "vasya@email.ru"
}, "completedAmount": null, "completedDate": null, "createdDate": "16/02/2018 17:50:00",
"isDeleted": false,
"manager": null, "orderDate": "16/02/2018 10:00:00", "orderNumber": "7813745", "orderSource": { "requestNumber": "5231705", "type": "REQUEST" },
"orderStatus": "start", "plannedAmount": 1000,
"service": null, "visit": { "utmSource": "(direct)", "utmTerm": "(not set)", "utmContent": "<не указано>", "visitDate": "15/02/2018 13:05:58",
"utmMedium": "(none)", "source": "(direct)", "medium": "(none)", "keyword": "(not set)", "utmCampaign": "<не указано>", "city": "vladimir", "url": "https://test.ru/", "ref": "https://google.ru/", "hostName": "test.ru", "sessionId": 458571828, "clientId": "1241916806.1678992934", "yaClientId": "1678992939228672376", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36", "ip": "95.66.146.1", "ctClientId": 1000000000304233300, "ctGlobalId": "6b8929ff-78fc-5489-afa8-da8551f9186b", "attrs": null, "yandexDirect": null, "googleAdWords": null }, "funnel": "Название воронки", "currencyCode": "RUB", "margin": 3, "orderLink": "https://site.ru/7813745", "orderName": "Название сделки", "products": [ { "name": "USB-удлинитель", "brand": "Завод удлинителей", "category": "Элкабели, шнуры", "variant": "3 м", "price": 101.63, "quantity": 4, "revenue": 406.52, "externalId": "33333323", "margin": 100.25 } ] }, ... { ... } ]
}
Объект | Описание |
page | Номер текущей страницы выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit). |
pageTotal | Всего страниц выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit). |
pageSize | Размер страницы выгрузки. Равен значению, которое было указано во входном параметре limit. Присутствует, если включена пагинация (используются входные параметры page и limit). |
recordsTotal | Всего сделок на всех страницах выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit). |
records | Содержит сами сделки и информацию по ним. |
client |
Объект будет содержать вложенные объекты с описанием клиента. Описание вложенных объектов:
|
isDeleted | Изначально isDeleted=false. При удалении сделки из интерфейса журнала продаж старого ЛК isDeleted=true |
manager | Менеджер, отвечающий за сделку |
orderDate | Дата создания сделки в формате dd/mm/yyyy hh:mm:ss (эта дата была передана в параметре orderDate в API-запросе на создание сделки). |
createdDate | Дата создания сделки в формате dd/mm/yyyy hh:mm:ss. |
statusDate | Дата, когда сделка получила текущий статус. |
updatedDate | Дата обновления сделки. |
comment | Комментарий к сделке. |
orderNumber | Уникальный идентификатор сделки в Вашей CRM, который Вы отправили в параметре orderNumber API-запроса на создание новой сделки. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор сделки в Calltouch. |
orderLink
|
Ссылка на сделку в CRM. Если не передан, то параметр принимает значение null. |
orderName
|
Название сделки в CRM. Если не передан, то параметр принимает значение null. |
orderOrigin | Каким методом была создана сделка |
orderSource |
Объект будет содержать вложенные объекты с описанием звонка или заявки, к которой закреплена сделка. Описание вложенных объектов, если сделка закреплена за звонком:
Описание вложенных объектов, если сделка закреплена за заявкой:
|
funnel | Воронка сделки |
orderStatus | Статус сделки |
currency |
Валюта сделки |
plannedAmount | Бюджет сделки |
margin | Маржинальность сделки |
service | Название сервиса, использующего наше API |
tags | Теги сделки. Присутствуют в случае, если указан входной параметр withOrdersTags=true |
visit | Объект будет содержать вложенные объекты с описанием источника звонка или заявки, за которой закреплена сделка. Если звонок или заявка, за которой закреплена сделка, не имеют источника, то объект будет равен значению null. |
visit.keywords |
Ключевой запрос |
visit.source |
Источник перехода |
visit.medium |
Канал перехода |
visit.utmSource |
Значение utm-метки utm_source |
visit.utmMedium |
Значение utm-метки utm_medium |
visit.utmTerm |
Значение utm-метки utm_term |
visit.utmContent |
Значение utm-метки utm_content |
visit.utmCampaign |
Значение utm-метки utm_campaign |
visit.visitDate |
Дата посещения в формате dd/mm/yyyy hh:mm:ss |
visit.city |
Город, определенный по ip сессии сделки |
visit.url |
URL перехода на сайт |
visit.ref |
Реферер перехода на сайт |
visit.hostname |
Отслеживаемый домен или поддомен ресурса, на который был осуществлен переход (например: yoursite.ru). |
visit.sessionId |
ID сессии Calltouch |
visit.clientId |
Client ID из Google Analytics |
visit.yaClientId |
ID Яндекс.Метрики |
visit.userAgent |
User Agent |
visit.ip |
IP адрес перехода на сайт |
visit.ctClientId |
ID посетителя Calltouch |
visit.ctGlobalId |
Глобальный ID посетителя Calltouch |
visit.attrs |
Сторонние параметры сессии. В формате: {"param1":"value1","param2":"value2"} Присутствуют в ответе только если в запросе был передан параметр withAttrs=true, иначе null |
visit.yandexDirect |
Данные по склейки сессии с кликом из Директа:
"yandexDirect":{ "campaignId": 32515134, "adGroupId": 325245212134, "adId": 2546356252, "criteriaId": 254251323 } Пример ответа, когда у сессии нет склейки с кликом: "yandexDirect": null |
visit.googleAdWords |
Данные по склейки сессии с кликом из Google Ads:
"googleAdWords": { "campaignId": 35635656, "adGroupId": 134524245, "creativeId": 23134141, "criteriaId": 4324553542 } Пример ответа, когда у сессии нет склейки с кликом: "googleAdWords":null |
custom |
Значения пользовательских полей (см. ранее), если они были переданы сделке. Пример:
"custom": { Если какое-то из полей пустое, оно не выгружается. Если пользовательских полей не было передано, параметр custom не выгружается. |
products[n].name | Наименование товара. |
products[n].brand | Бренд, торговая марка товара. |
products[n].category | Категория товара. |
products[n].variant | Разновидность товара. |
products[n].price | Цена за единицу товара. |
products[n].quantity | Количество товаров. |
- JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
Система баллов API Calltouch
Система баллов API - механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch
Количество запросов в секунду к API Calltouch ограничено – не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой.
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)