Выгрузка журнала сделок

Читать 16

Возможности

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

Запрос

С помощью данного API-метода Вы можете выгрузить список сделок за указанный временной интервал с детальной информацией по каждой.

Поддерживаемый метод отправки: GET.

API-запрос: 

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

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

Параметр Описание
clientApiId

Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:

api-token.png

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 со значением:

  • CALL - будут выгружены сделки, созданные только по звонкам
  • REQUEST - будут выгружены сделки, созданные только по заявкам
phoneNumber.value Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, номер телефона клиента в которых совпадает с указанным значением. Если указывается этот параметр, то параметры dateFrom/dateTo/timeFrom/timeTo выше не указываются.
orderNumber Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, ID сделки в Calltouch которых совпадает с указанным значением. Если указывается этот параметр, то параметры dateFrom/dateTo/timeFrom/timeTo выше не указываются.
bindTo

Необязательный параметр. Флаг выгрузки сделок с привязкой к разным метрикам. Возможные значения:

  • createddate – по дате создания самих сделок (по умолчанию)
  • offereddate – по дате завершения самих сделок
  • updateddate – по дате изменения сделок
  • session – выгрузка сделок по дате сессий звонков или заявок, за которыми они закреплены
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
            }
        ]
    },
    ...
    {
        ...
    }
]
}
JSON-объекты:
Объект Описание
page Номер текущей страницы выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
pageTotal Всего страниц выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
pageSize Размер страницы выгрузки. Равен значению, которое было указано во входном параметре limit. Присутствует, если включена пагинация (используются входные параметры page и limit).
recordsTotal Всего сделок на всех страницах выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
records Содержит сами сделки и информацию по ним.
client

Объект будет содержать вложенные объекты с описанием клиента. Описание вложенных объектов:

  • phones - номер клиента в формате 7XXXXXXXXXX.
  • fio - имя клиента
  • emails - почта клиента в формате x@x.x
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

Объект будет содержать вложенные объекты с описанием звонка или заявки, к которой закреплена сделка.

Описание вложенных объектов, если сделка закреплена за звонком:

  • callId - уникальный идентификатор звонка в Calltouch
  • duration - длительность звонка в секундах
  • phoneNumber - отслеживаемый номер, на который звонил клиент, в формате 7XXXXXXXXXX
  • type - тип обращения, за которым закреплена сделка, в данном случае значение CALL
  • ani - номер клиента в формате 7XXXXXXXXXX
  • dateCall - дата и время звонка в формате dd/mm/yyyy hh:mm:ss

Описание вложенных объектов, если сделка закреплена за заявкой:

  • requestNumber - уникальный идентификатор заявки в Calltouch
  • type - тип обращения, за которым закреплена сделка, в данном случае значение REQUEST
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 Данные по склейки сессии с кликом из Директа:
  • campaignId - ID кампании
  • adGroupId - ID группы
  • adId - ID объявления
  • criteriaId - ID фразы
Пример ответа, когда у сессии есть эти данные:
"yandexDirect":{
   "campaignId": 32515134,
   "adGroupId": 325245212134,
   "adId": 2546356252,
   "criteriaId": 254251323
}
Пример ответа, когда у сессии нет склейки с кликом:
"yandexDirect": null
visit.googleAdWords Данные по склейки сессии с кликом из Google Ads:
  • campaignId - ID кампании
  • adGroupId - ID группы
  • creativeId - ID объявления
  • criteriaId - ID фразы
Пример ответа, когда у звонка или заявки есть эти данные:
"googleAdWords": {
   "campaignId": 35635656,
   "adGroupId": 134524245,
   "creativeId": 23134141,
   "criteriaId": 4324553542
}
Пример ответа, когда у сессии нет склейки с кликом:
"googleAdWords":null
custom

Значения пользовательских полей (см. ранее), если они были переданы сделке. Пример:

"custom": {
"custom_field_1": "1000.00",
"custom_field_2": "1000000.00"
}

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

Похожие статьи
Недавно просмoтренные