Наверх

API-метод выгрузки журнала сделок

Содержание

 

 

Возможности

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

 

 

Отображение сделок в статистике

Созданные сделки отображаются в ЛК в виде метрик пользовательских столбцов в категории "Сделки из CRM":

custom_columns_completed_deals.jpg

С помощью пользовательских столбцов Вы можете любым необходимым Вам образом проанализировать статистику по сделкам, не только увидев их количество, как настроено на скриншоте выше, но и например просчитав возврат инвестиций ROI:

custom_columns_roi.jpg

Созданные пользовательские столбцы можно добавить в любой отчет для анализа сделок в нем. Пользовательские столбцы, в формуле которых используются метрики Яндекс.Директ или Google Adwords, можно добавлять только в соответствующие отчеты Директа и Adwords.

На скриншоте ниже изображен пример из отчета Яндекс.Директ с двумя пользовательским столбцами: "Кол-во завершенных сделок из API" и "ROI":

custom_columns_roi_in_report.jpg

advice_ver2.png Стандартная формула расчета ROI:

(доход - расход) / расход * 100%

Применяя ее к реалиям ЛК Calltouch, в пользовательских столбцах эта формула настраивается следующим образом:

  • По рекламе Google AdWords и произвольным сделкам:
    (Сделки из CRM: Сумма по произвольным сделкам - Google AdWords: Бюджет) / Google AdWords: Бюджет
  • По рекламе Яндекс.Директ и произвольным сделкам:
    (Сделки из CRM: Сумма по произвольным сделкам - Яндекс.Директ: Бюджет) / Яндекс.Директ: Бюджет

Умножение на 100% не нужно добавлять в формулу при настройке ее в пользовательском столбце - умножение на 100% будет автоматическое, если выбран формат "Процент".

 

Добавление пользовательских полей

По умолчанию API-метод создания сделок (см. далее) позволяет передавать следующие метрики сделок:

  • Кол-во сделок
  • Их статус
  • Менеджера
  • Теги

Но вы можете расширить этот список до бесконечности – в настройках API личного кабинета Calltouch есть возможность создать пользовательские поля API-метода создания/выгрузки сделок:

api_custom_fields.png

Это делает возможным выгружать к нам из CRM любые показатели сделок, например, себестоимость, операционные доходы, чистую прибыль, размер скидки и любые другие характеристики. Все добавленные поля автоматически становятся доступными в:

  • В API-методах создания/обновления/выгрузки сделок
  • В пользовательских столбцах Calltouch

custom_fields_in_custom_columns.png

Например, как в ЛК Calltouch увидеть валовую прибыль? Теперь очень просто. Добавьте поле "Себестоимость" в API и выгружайте в него данные из CRM. А чтобы посчитать валовую прибыль, просто создайте пользовательский столбец, задав в нем формулу:

gross_profit.png

В этом примере созданный пользовательский столбец будет отображать валовую прибыль сделок на этапе "Счет на предоплату" менеджера Васи с тегом "Акции". Настроив один раз пользовательский столбец, он станет доступным в любом отчете Calltouch:

custom_fields_in_reports.png

Вы можете передавать в пользовательское поле любое целое значение, в том числе отрицательное, максимальное кол-во знаков 38. Для текстовых предназначены теги. При удаление пользовательского поля, все данные, переданные в нем, будут так же удалены.

 

API-метод для выгрузки списка сделок

Запрос

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

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

API-запрос:

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

Где:

  • X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
  • {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
site_id.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 - по дате завершения самих сделок
  • session - выгрузка сделок по дате сессий звонков или заявок, за которыми они закреплены
manager Необязательный параметр. При указании менеджера в выгрузке должны оказаться только те сделки, которые привязаны к этому менеджеру.
service Необязательный параметр. Название сервиса, использующего наше API. Можно указать конкретный сервис и в выгрузке должны оказаться только те сделки, у которых указан этот сервис, например, retailCRM.
withOrdersTags Необязательный параметр. Флаг выгрузки тегов сделки. Если не указан или равен false, теги не выгружаются. Если указан и равен true, то теги выгружаются JSON-массивом. Если указан и равен true, но тегов нет, параметр равен null.
withAllOrderOrigins Необязательный параметр. Флаг выгрузки сделок, созданных любыми методами. Если указан и равен true, то в выгрузке будут присутствовать все сделки, которые есть в ЛК. Если указан и равен false или не указан, то в выгрузке будут присутствовать сделки из ЛК, которые были созданы по API.

 

Пример GET-запроса на выгрузку сделок

Запрос далее выгрузит сделки сайта с идентификатором 12345, созданные и по звонкам и по заявкам, дата создания (параметр orderDate в API-запросах на создание новых сделок) которых находится между 01/03/2018 и 27/03/2018. В выгрузке включена пагинация (используются параметры page и limit), а так же в ней будет присутствовать массив тегов по каждой сделке (указан флаг withOrdersTags=true).

https://api-node3.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",
"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": "", "additionalTags": [], "utmTerm": "", "utmContent": "", "visitDate": "27/03/2018 15:37:58", "utmMedium": "", "source": "(direct)", "medium": "(none)", "keyword": "(not set)", "utmCampaign": "" } }, { "client": { "phones": "79205550058", "fio": "Вася" }, "completedAmount": null, "completedDate": null, "createdDate": "16/02/2018",
"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, "additionalTags": [], "utmTerm": null, "utmContent": null, "visitDate": null, "utmMedium": null, "source": null, "medium": null, "keyword": null, "utmCampaign": null } }, ... { ... } ]
}

JSON-объекты:

Объект Описание
page Номер текущей страницы выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
pageTotal Всего страниц выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
pageSize Размер страницы выгрузки. Равен значению, которое было указано во входном параметре limit. Присутствует, если включена пагинация (используются входные параметры page и limit).
recordsTotal Всего сделок на всех страницах выгрузки. Присутствует, если включена пагинация (используются входные параметры page и limit).
records Содержит сами сделки и информацию по ним.
client

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

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

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

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

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

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

  • requestNumber - уникальный идентификатор заявки в Calltouch
  • type - тип обращения, за которым закреплена сделка, в данном случае значение REQUEST
orderStatus Статус сделки
plannedAmount Бюджет сделки
service Название сервиса, использующего наше API
tags Теги сделки. Присутствуют в случае, если указан входной параметр withOrdersTags=true
visit Объект будет содержать вложенные объекты с описанием источника звонка или заявки, за которой закреплена сделка. Описание вложенных объектов:
    • keywords - ключевой запрос
    • source - Источник перехода
    • medium - Канал перехода
    • utmSource - значение utm-метки utm_source
    • utmMedium - значение utm-метки utm_medium
    • utmTerm - значение utm-метки utm_term
    • utmContent - значение utm-метки utm_content
    • utmCampaign - значение utm-метки utm_campaign
    • visitDate - дата посещения в формате dd/mm/yyyy hh:mm:ss

Если звонок или заявка, за которой закреплена сделка, не имеют источника, то объект будет равен значению null.

custom

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

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

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

JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.

 

advice_ver2.png Кол-во запросов в секунду к API Calltouch ограничено – не более 5 запросов (+5 запросов в очередь) в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, 5 поставятся в очередь, и 1 API-запрос завершится с ошибкой.