Выгрузка журнала сделок
Возможности
В данной статье описан 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 или не указан, то в выгрузке будут присутствовать сделки без комментария. |
Пример 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": "",
"utmTerm": "",
"utmContent": "",
"visitDate": "27/03/2018 15:37:58",
"utmMedium": "",
"source": "(direct)",
"medium": "(none)",
"keyword": "(not set)",
"utmCampaign": ""
},
"funnel": "Название воронки",
"currencyCode": "RUB",
"margin": 3,
"orderLink": "https://site.ru/HLlHwLqSms5r8e",
"orderName": "Название сделки"
},
{
"client": {
"phones": "79205550058",
"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": null,
"utmTerm": null,
"utmContent": null,
"visitDate": null,
"utmMedium": null,
"source": null,
"medium": null,
"keyword": null,
"utmCampaign": 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. |
| custom |
Значения пользовательских полей (см. ранее), если они были переданы сделке. Пример:
"custom": { Если какое-то из полей пустое, оно не выгружается. Если пользовательских полей не было передано, параметр custom не выгружается. |
| products[n].name |
Наименование товара. |
| products[n].brand |
Бренд, торговая марка товара. |
| products[n].category |
Категория товара. |
| products[n].variant |
Разновидность товара. |
| products[n].price |
Цена за единицу товара. |
| products[n].quantity |
Количество товаров. |
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
Кол-во запросов в секунду к API Calltouch ограничено – не более 5 запросов (+5 запросов в очередь) в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, 5 поставятся в очередь, и 1 API-запрос завершится с ошибкой.