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

Читать 18

Возможности

В данной статье описан 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 и Webhooks / API.
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 Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, номер телефона в которых совпадает с указанным значением.
orderNumber Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, ID сделки в Calltouch которых совпадает с указанным значением. Если указывается этот параметр, то параметры dateFrom/dateTo/timeFrom/timeTo выше не указываются.
bindTo Необязательный параметр. Флаг выгрузки сделок с привязкой к разным метрикам. Возможные значения:
  • createddate — по дате создания самих сделок (по умолчанию)
  • offereddate — по дате завершения самих сделок
  • updateddate — по дате изменения сделок
  • session — выгрузка сделок по дате сессий звонков или заявок, за которыми они закреплены
manager Необязательный параметр. При указании менеджера в выгрузке должны оказаться только те сделки, которые привязаны к этому менеджеру.
service Необязательный параметр. Название сервиса, использующего наше API. Можно указать конкретный сервис и в выгрузке должны оказаться только те сделки, у которых указан этот сервис, например, retailCRM.
withOrdersTags Необязательный параметр. Флаг выгрузки тегов сделки. Если не указан или равен false, теги не выгружаются. Если указан и равен true, то теги выгружаются JSON-массивом. Если указан и равен true, но тегов нет, параметр равен null.

Возможные значения:

  • true — теги выгружаются.
  • false — теги не выгружаются (по умолчанию, если параметр не указан)
withAllOrderOrigins Необязательный параметр. Флаг выгрузки сделок, созданных любыми методами. Возможные значения:
  • true — в выгрузке будут присутствовать все сделки, которые есть в ЛК.
  • false — в выгрузке будут присутствовать только сделки, которые были созданы по API (по умолчанию, если параметр не указан)
withComments Необязательный параметр. Флаг выгрузки комментариев к сделке. Возможные значения:
  • true — в выгрузке будут присутствовать комментарии к сделкам.
  • false — не выгружать комментарии к сделкам (по умолчанию, если параметр не указан)
withAttrs Необязательный параметр. Флаг выгрузки сторонних параметров сессии. Возможные значения:
  • true — Сторонние параметры выгружаются в выходной параметр attrs. Если их нет, то значение выходного параметра attrs: null.
  • false — Сторонние параметры не выгружаются, значение выходного параметра attrs: null. (по умолчанию, если параметр не указан)
withYandexDirect Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Яндекс.Директ. Возможные значения:
  • true — в выгрузке присутствует выходной параметр yandexDirect.
  • false — выходной параметр yandexDirect: null (по умолчанию, если параметр не указан)
withGoogleAdwords Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Google AdWords. Возможные значения:
  • true — в выгрузке присутствует выходной параметр googleAdWords.
  • false — выходной параметр googleAdWords: null (по умолчанию, если параметр не указан)
withContacts Необязательный параметр. Флаг выгрузки контактов из сделки. Возможные значения:
  • true — выгружать контакты
  • false — не выгружать контакты (по умолчанию, если параметр не указан)
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.ru/",
           "ref": "",
           "hostName": "calltouch.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": "Название сделки",
        "orderContacts": {
           "mainContacts": {
              "fio": "Иван",
              "phoneNumber": "79000000000",
              "email": "test@test.ru"
           },
           "otherContacts": {
              "phoneNumber": ["79000000001","79000000002"],
              "email": ["test2@test.ru","test3@test.ru"]
           }
        }
    },
    {
        "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": "Название сделки",
        "orderContacts": null
        "products": [
            {
                "name": "USB-удлинитель",
                "brand": "Завод удлинителей",
                "category": "Элкабели, шнуры",
                "variant": "3 м",
                "price": 101.63,
                "quantity": 4,
                "revenue": 406.52,
                "externalId": "33333323",
                "margin": 100.25
            }
        ]
    },
    ...
    {
        ...
    }
]
}

Выходные параметры:

Параметр Формат Описание
page integer Номер текущей страницы выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
pageTotal integer Всего страниц выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
pageSize integer Размер страницы выгрузки. Равен значению, которое было указано во входном параметре limit. Присутствует, если включена пагинация (используются входные параметры page и limit).
recordsTotal integer Всего сделок на всех страницах выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
records array Содержит сами сделки и информацию по ним.
orderContacts object Объект с контактами из сделки
orderContacts.
mainContacts
 		object Объект с основными контактами сделки.
Описание вложенных полей:
  • fio — имя клиента
  • phoneNumber — номер в формате 7XXXXXXXXXX.
  • email — почта в формате x@x.x
orderContacts.
otherContacts
 		object Объект с дополнительными контактами сделки. 
Описание вложенных полей:
  • phoneNumbers — массив из дополнительных номеров в формате 7XXXXXXXXXX. Максимум 3 штуки.
  • emails — массив из почт клиента в формате x@x.x. Максимум 3 штуки.
client object

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

  • phones — номер клиента в формате 7XXXXXXXXXX.
  • fio — имя клиента
  • emails — почта клиента в формате x@x.x
isDeleted boolean Изначально isDeleted=false. При удалении сделки из интерфейса журнала продаж старого ЛК isDeleted=true
manager string Менеджер, отвечающий за сделку
orderDate string Дата создания сделки в формате dd/mm/yyyy hh:mm:ss (эта дата была передана в параметре orderDate в API-запросе на создание сделки).
createdDate string Дата создания сделки в формате dd/mm/yyyy hh:mm:ss.
statusDate string Дата, когда сделка получила текущий статус.
updatedDate string Дата обновления сделки.
comment string Комментарий к сделке.
orderNumber string Уникальный идентификатор сделки в Вашей CRM, который Вы отправили в параметре orderNumber API-запроса на создание новой сделки. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор сделки в Calltouch.
orderLink
string
Ссылка на сделку в CRM. Если не передан, то параметр принимает значение null.
orderName
string
Название сделки в CRM. Если не передан, то параметр принимает значение null.
orderOrigin string Каким методом была создана сделка
orderSource object

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

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

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

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

  • requestNumber — уникальный идентификатор заявки в Calltouch
  • type — тип обращения, за которым закреплена сделка, в данном случае значение REQUEST
funnel string Воронка сделки
orderStatus string Статус сделки
currency
 		string Валюта сделки
plannedAmount string Бюджет сделки
margin string Маржинальность сделки
service string Название сервиса, использующего наше API
tags string Теги сделки. Присутствуют в случае, если указан входной параметр withOrdersTags=true
visit object Объект будет содержать вложенные объекты с описанием источника звонка или заявки, за которой закреплена сделка. Если звонок или заявка, за которой закреплена сделка, не имеют источника, то объект будет равен значению null.
visit.keywords  string Ключевой запрос
visit.source  string Источник перехода
visit.medium  string Канал перехода
visit.utmSource  string Значение utm-метки utm_source
visit.utmMedium  string Значение utm-метки utm_medium
visit.utmTerm  string Значение utm-метки utm_term
visit.utmContent  string Значение utm-метки utm_content
visit.utmCampaign  string Значение utm-метки utm_campaign
visit.visitDate string Дата посещения в формате dd/mm/yyyy hh:mm:ss
visit.city string Город, определенный по ip сессии сделки
visit.url string URL перехода на сайт
visit.ref string Реферер перехода на сайт
visit.hostname string Отслеживаемый домен или поддомен ресурса, на который был осуществлен переход (например: yoursite.ru).
visit.sessionId string ID сессии Calltouch
visit.clientId
 		string Client ID из Google Analytics
visit.yaClientId string ID Яндекс.Метрики
visit.userAgent string User Agent
visit.ip
 		string IP адрес перехода на сайт
visit.ctClientId string ID посетителя Calltouch
visit.ctGlobalId string Глобальный ID посетителя Calltouch
visit.attrs
 		object Сторонние параметры сессии. В формате:
{"param1":"value1","param2":"value2"}
visit.yandexDirect object Данные по склейки сессии с кликом из Директа:
  • campaignId — ID кампании
  • adGroupId — ID группы
  • adId — ID объявления
  • criteriaId — ID фразы
Пример ответа, когда у сессии есть эти данные:
"yandexDirect":{
   "campaignId": 32515134,
   "adGroupId": 325245212134,
   "adId": 2546356252,
   "criteriaId": 254251323
}
Пример ответа, когда у сессии нет склейки с кликом:
"yandexDirect": null
visit.googleAdWords object Данные по склейки сессии с кликом из Google Ads:
  • campaignId — ID кампании
  • adGroupId — ID группы
  • creativeId — ID объявления
  • criteriaId — ID фразы
Пример ответа, когда у звонка или заявки есть эти данные: 
"googleAdWords": {
   "campaignId": 35635656,
   "adGroupId": 134524245,
   "creativeId": 23134141,
   "criteriaId": 4324553542
}
Пример ответа, когда у сессии нет склейки с кликом:
"googleAdWords":null
custom object

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

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

Если какое-то из полей пустое, оно не выгружается. Если пользовательских полей не было передано, параметр custom не выгружается.

products[n].name string Наименование товара.
products[n].brand string Бренд, торговая марка товара.
products[n].category string Категория товара.
products[n].variant string Разновидность товара.
products[n].price string Цена за единицу товара. 
products[n].quantity string Количество товаров.
Параметры, не описанные выше, но присутствующие в ответе — являются устаревшими, их следует игнорировать в ответе.

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

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

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

 

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