Читать 20

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

Возможности

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

Запрос

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

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

API-запрос:

https://api.calltouch.ru/calls-service/RestAPI/{site_id}/orders-diary/orders

Где:

{site_id} — ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе: Интеграции / Отправка данных во внешние системы / API и Webhooks.

Пример 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

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

Параметр	Описание
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	Необязательный параметр. Номер телефона, в формате 7XXXXXXXXXX. Если параметр указан - в ответе будут только те сделки, номер телефона в которых совпадает с указанным значением.
email.value	Необязательный параметр. Email, в формате x@x.x. Если параметр указан - в ответе будут только те сделки, электронная почта в которых совпадает с указанным значением.
orderNumber	Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, внешний ID сделки которых совпадает с указанным значением. Если указывается этот параметр, то параметры dateFrom/dateTo/timeFrom/timeTo выше не указываются.
orderId	Необязательный параметр. Параметр, с помощью которого можно выгрузить только те сделки, внутренний 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 — последний непрямой (по умолчанию, если параметр не указан)

Ответ

API-запрос выше выгружает только первую страницу выгрузки. Для выгрузки остальных страниц выгрузки, отправьте тот же запрос, но в параметре page указав необходимую страницу выгрузки. После успешной отправки API-запроса на выгрузку списка сделок, возвращается следующий JSON-ответ.

Пример ответа

{
 "page": 1,
 "pageTotal": 4,
 "pageSize": 500,
 "recordsTotal": 2000,
 "records": [
    {
        "client": {
            "phones": "74953080100",
            "fio": null,
            "emails": null,
            "waPhones": null,
            "tgIds": null,
            "tgUsernames": null,
            "vkIds": 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"
              "waPhone": "79000000000",
              "tgId": "115673"
              "tgUsername": "tguser123",
              "vkId": "1234567"
           },
           "otherContacts": {
              "phoneNumber": ["79000000001","79000000002"],
              "email": ["test2@test.ru","test3@test.ru"],
              "waPhones": ["79000000003","79000000004"],
              "tgIds": ["7654321"],
              "tgUsernames": ["tguser22"],
              "vkIds": ["7654321"]
           }
        },
        "orderId": 7282479
    },
    {
        "client": {
            "phones": "79000000000",
            "fio": "Вася",
            "emails": "vasya@email.ru",
            "waPhones": null,
            "tgIds": null,
            "tgUsernames": null,
            "vkIds": null 
        },
        "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,
        "orderId": 7414538,
        "products": [
            {
                "name": "USB-удлинитель",
                "brand": "Завод удлинителей",
                "category": "Элкабели, шнуры",
                "variant": "3 м",
                "price": 101.63,
                "quantity": 4,
                "revenue": 406.52,
                "externalId": "33333323",
                "margin": 100.25
            }
        ]
    },
    {
        "client": {
          "phones": "79991602026",
          "fio": "Иван",
          "emails": "test1@test.ru,
          "waPhones": "79000000000",
          "telegramIds": "1234567",
          "telegramUsernames": "username1",
          "vkIds": "1234567"
        },
        "tags": null,
        "completedAmount": 0,
        "completedDate": null,
        "createdDate": "16/01/2025 00:12:32",
        "isDeleted": false,
        "manager": null,
        "orderDate": "16/01/2025 00:12:32",
        "orderNumber": "181020711202911212",
        "orderOrigin": "api",
        "orderStatus": "Статус 1",
        "plannedAmount": 0,
        "service": "TEST CRM",
        "orderSource": {
          "chatId": "443311132",
          "duration": null,
          "type": "CHAT"
        },
        "visit": {
          "utmSource": "yandex",
          "utmTerm": "<не заполнено>",
          "utmContent": "<не заполнено>",
          "visitDate": "16/01/2025 00:23:16",
          "utmMedium": "cpc",
          "source": "yandex",
          "medium": "cpc",
          "keyword": "<не заполнено>",
          "utmCampaign": "<не заполнено>",
          "city": null,
          "url": null,
          "ref": null,
          "hostName": null,
          "sessionId": null,
          "clientId": null,
          "yaClientId": null,
          "userAgent": null,
          "ip": null,
          "ctClientId": null,
          "ctGlobalId": null,
          "attrs": null,
          "yandexDirect": null,
          "googleAdWords": null
        },
        "funnel": "Продажа",
        "currencyCode": "RUB",
        "margin": 0,
        "orderLink": null,
        "orderName": null,
        "custom": null,
        "products": [],
        "updatedDate": "16/01/2025 00:12:32",
        "statusDate": "16/01/2025 00:13:32",
        "comment": null,
        "orderContacts": {
             "mainContacts": {
                "fio": "Иван",
                "phoneNumber": "79000000000",
                "email": "test@test.ru",
                "waPhone": "79000000000",
                "tgId": "1234567",
                "tgUsername": "username1",
                "vkId": "1234567"
             },
             "otherContacts": {
                "phoneNumber": ["79000000001","79000000002"],
                "email": ["test2@test.ru","test3@test.ru"],
                "waPhone": ["79000000001","79000000002"],
                "tgId": ["7654321"],
                "tgUsername": ["username2"],
                "vkId": ["7654321"]
             }
          }
      },
    ...
    {
        ...
    }
]
}

Параметры ответа

Параметр	Формат	Описание
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 waPhone — номер телефона из Whatsapp в формате 7XXXXXXXXXX tgId — ID пользователя в Telegram tgUsername — username пользователя в Telegram vkId — ID пользователя в VK
orderContacts. otherContacts	object	Объект с дополнительными контактами сделки. Описание вложенных полей: phoneNumbers — массив из дополнительных номеров в формате 7XXXXXXXXXX. Максимум 3 штуки. emails — массив из почт клиента в формате x@x.x. Максимум 3 штуки. waPhones — массив из дополнительных номеров из Whatsapp в формате 7XXXXXXXXXX. Максимум 3 штуки. tgIds — массив из дополнительных ID пользователя в Telegram. Максимум 3 штуки. tgUsernames — массив из дополнительных username пользователя в Telegram. Максимум 3 штуки. vkIds — массив из дополнительных ID пользователя в VK. Максимум 3 штуки.
client	object	Объект будет содержать вложенные объекты с контактами клиента, к котрому приклеена сделка. Описание вложенных полей: phones — номер клиента в формате 7XXXXXXXXXX fio — имя клиента emails — почта клиента в формате x@x.x waPhones — номер клиента в Whatsapp в формате 7XXXXXXXXXX tgIds — ID клиента в Telegram tgUsernames — username клиента в Telegram vkIds — ID клиента в VK
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.
orderId	integer	Уникальный идентификатор сделки в 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 Описание вложенных объектов, если сделка закреплена за чатом: chatId — уникальный идентификатор чата в Calltouch type — тип обращения, за которым закреплена сделка, в данном случае значение CHAT
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).

Не нашли решение проблемы?

Заполните форму, и мы вам поможем.

Оцените статью

Общая информация

Элементы сценариев