Наверх
Подписаться

Управление сделками через 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-метод для создания новых сделок

Запрос с указанием ID звонка или заявки

Если Вам заранее известен внутренний ID Calltouch звонка (callId) или заявки (requestId) или внешний ID заявки (requestNumber), то Вы можете создать сделку по звонку или заявке, используя API-запрос ниже. Заранее получить внутренние ID звонков можно с помощью вебхуков или API-метода для выгрузки звонков, заранее получить внутренние ID заявок можно с помощью API-метода для выгрузки заявок. Внешние ID заявок можно передавать в Calltouch на этапе создания заявок через API.

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

API-запрос:

https://api-nodeX.calltouch.ru/calls-service/RestAPI/orders/register/

Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.

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

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

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

api-token.png

callId или requestId или requestNumber

Сделку можно создать либо по звонку, либо по заявке. Соответственно при отправке запроса необходимо использовать параметр:

  • callId
    Если сделка создается по звонку, необходимо передавать идентификатор звонка.
  • requestId
    Если сделка создается по заявке и известен ID заявки внутри Calltouch, необходимо передавать этот идентификатор заявки.
  • requestNumber
    Если сделка создается по заявке и ID заявки внутри Calltouch неизвестен, но известен внешний ID заявки с сайта (он был ранее одновременно передан с сайта в Calltouch и в вашу систему, см. параметр requestNumber в API-методе создания заявок) необходимо передавать этот идентификатор заявки.

Нельзя создать сделку одновременно по звонку и заявке. Либо только по звонку, либо только по заявке. Сделка не может быть привязана одновременно ко звонку и к заявке. Если Вы вовсе не отправите ни callId ни requestId ни requestNumber, то сделка будет создана в статистике Calltouch, но во всех отчетах будет отображаться без источника, т.к. источником сделки является источник звонка или заявки, за которым она закреплена.

orderNumber

Уникальный ID сделки на стороне Вашей CRM (не на стороне Calltouch). Параметр является необязательным. Рекомендуем использовать минимум 8-значные буквенно-цифровые идентификаторы (см. пример в запросе далее). Если параметр не указан, то по умолчанию он будет равен orderId (ID сделки в Calltouch), который Calltouch вернет в ответе на запрос (см. JSON-ответ далее).

Обратите внимание! Если Вы отправляете какое-либо значение orderNumber, то для каждой новой сделки это значение обязательно должно быть уникальным.

orderSum Бюджет сделки в рублях. Обязательный параметр.
orderStatus

Статус сделки. Обязательный параметр. Вы можете передавать в Calltouch любой статус сделок. Он будет отображаться в отчетах через пользовательские столбцы, настроить которые вы можете в одноименном разделе настроек: Screenshot_2019-04-05_at_12.44.17.png

orderDate Дата создания сделки. Обязательный параметр. Формат dd.mm.yyyy%20hh:mm:ss.
orderComment Комментарий к сделки.
manager Менеджер, отвечающий за сделку. Необязательный параметр.
service Название сервиса, использующего наше API. Обязательный параметр.
tags Теги сделки. Можно передавать более одного тега через запятую. Необязательный параметр.

 

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

  • Создание сделки по звонку

Запрос далее создаст сделку на сумму 1000 руб со статусом "start" по звонку с идентификатором 32496964. Менеджером будет назначен "Коля". Сервис, использующий наше API выставится "AmoCRM". Сделке будут присвоены теги: "mytag1, mytag2, mytag3":

https://api-node3.calltouch.ru/calls-service/RestAPI/orders/register/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&callId=32496964&orderNumber=K2TU/sm{7u4X3F&orderSum=1000&orderStatus=start&orderDate=26.03.2018%2010:00:00&manager=Коля&service=AmoCRM&tags=mytag1,mytag2,mytag3
  • Создание сделки по заявке

Запрос далее создаст сделку на сумму 1000 руб со статусом "new" по заявке с идентификатором 51213218. Менеджером будет назначен "Коля". Сервис, использующий наше API выставится "AmoCRM". Сделке будут присвоены теги: "mytag1, mytag2, mytag3":

https://api-node3.calltouch.ru/calls-service/RestAPI/orders/register/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&requestId=51213218&orderNumber=hzwe4iCHiwauun&orderSum=1000&orderStatus=new&orderDate=26.03.2018%2010:00:00&manager=Коля&service=AmoCRM&tags=mytag1,mytag2,mytag3

 

Запрос с указанием номера телефона клиента

В случае, если заранее получить ID звонка (с помощью вебхуков или API-метода для выгрузки звонков) не предоставляется возможным, то сделку можно склеить со звонком по номеру телефона (параметр phoneNumber далее), с которого звонил клиент, и дате создания сделки по этому звонку (параметр orderDate далее). Склейка по номеру телефона по умолчанию выключена - для ее включения Вам необходимо отправить заявку Вашему аккаунт-менеджеру Calltouch либо на почту info@calltouch.net. Данная опция доступна только для звонков, не для заявок. После включения, склейка звонка со сделкой по номеру телефона клиента и дате создания сделки по нему, будет производиться в течение 10 минут после отправки API-запроса.

advice_ver2.png Мы рекомендуем использовать более точный API-метод создания сделки с указанием ID звонка или заявки.

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

API-запрос:

https://api-nodeX.calltouch.ru/calls-service/RestAPI/orders/register/

Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.

Вы могли заметить, что данный API-запрос точно такой же, как и предыдущий на создание сделки с указанием ID звонка или заявки. Так и есть, однако в случае необходимости склеивания звонка со сделкой по номеру телефона и дате создания сделки по этому звонку, у данного запроса будут отличаться входные параметры, описанные далее:

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

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

api-token.png

orderNumber

Уникальный ID сделки на стороне Вашей CRM (не на стороне Calltouch). Параметр является необязательным. Рекомендуем использовать минимум 8-значные буквенно-цифровые идентификаторы (см. пример в запросе далее). Если параметр не указан, то по умолчанию он будет равен orderId (ID сделки в Calltouch), который Calltouch вернет в ответе на запрос (см. JSON-ответ далее).

Обратите внимание! Если Вы отправляете какое-либо значение orderNumber, то для каждой новой сделки это значение обязательно должно быть уникальным.

phoneNumber Номер телефон, с которого звонил клиент, в формате 7XXXXXXXXXX. По этому номеру будет выполняться поиск звонка, в пределах даты, указанной в параметре orderDate и погрешности поиска, указанной в параметре linkTimeThreshold.
linkTimeThreshold

Погрешность в секундах для поиска ближайшего звонка, связанного со сделкой по дате и времени ее создания (параметр orderDate). Если не указывать параметр, по умолчанию погрешность будет равна 7200 сек (2 часа). Алгоритм связывания звонка со сделкой будет следующим:

Дата и время звонка <= Дата и время создания сделки <= Дата и время звонка + Длительность звонка + linkTimeThreshold

Например, звонок, длительностью в 5 мин, был совершен (в статистике Calltouch отображается и учитывается время начала звонка) в 17:00:00, сделка по которому была создана в CRM в 17:10. Чтобы связать такой звонок со сделкой, должны выполнится условия:

Дата и время звонка 17:00:00 <= Дата и время создания сделки 17:10:00 <= Дата и время звонка 17:00 + 5 мин + linkTimeThreshold=600 сек (10 мин)

Здесь linkTimeThreshold мог быть указан и меньше, либо вовсе не указан (тогда бы было 2 часа). Главное, чтобы время поиска ближайшего звонка для связи со сделкой в 17:10 захватывало время этого звонка в 17:00.

orderSum Бюджет сделки в рублях. Обязательный параметр.
orderStatus

Статус сделки. Обязательный параметр. Вы можете передавать в Calltouch любой статус сделок. Он будет отображаться в отчетах через пользовательские столбцы, настроить которые вы можете в одноименном разделе настроек: Screenshot_2019-04-05_at_12.44.17.png

orderDate Дата создания сделки. Обязательный параметр. Формат dd.mm.yyyy%20hh:mm:ss.
orderComment Комментарий к сделки.
manager Менеджер, отвечающий за сделку. Необязательный параметр.
service Название сервиса, использующего наше API. Обязательный параметр.
tags Теги сделки. Можно передавать более одного тега через запятую. Необязательный параметр.

 

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

  • Создание сделки по звонку

Запрос далее создаст сделку на сумму 1000 руб со статусом "status" по звонку с номера 79205550055, сделка по которому создана 25.03.2018 11:00:00. Поиск звонка для склейки со сделкой будет произведен в пределах 600 сек (10 мин) от даты создания сделки. Менеджером будет назначен "Коля". Сервис, использующий наше API выставится "AmoCRM". Сделке будут присвоены теги: "mytag1, mytag2, mytag3"

https://api-node3.calltouch.ru/calls-service/RestAPI/orders/register/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&orderNumber=J2eTSacsKduifb&orderSum=1000&orderStatus=status&orderDate=25.03.2018%2011:00:00&phoneNumber=79205550055&linkTimeThreshold=600&manager=Коля&service=AmoCRM&tags=mytag1,mytag2,mytag3

 

Формат тела запроса при использовании метода POST

При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":

параметр1=значение1&параметр2=значение2&...

В случае использования формата "application/x-www-form-urlencoded" в параметре orderDate символ %20 передавать не нужно. При использовании метода POST, одним API-запросом можно создать только одну сделку.

 

Ответ

После успешной отправки API-запроса на создание сделки, возвращается следующий JSON-ответ (пример):

{
    "orderId": 7811141,
    "callId": 32940789,
    "dateCreated": 1522047600000,
    "status": "new",
    "realSum": null,
    "offered": null,
    "sent": "26.03.2018",
    "sum": "1000",
    "isMarked": null,
    "commentsCount": 0,
    "currentAmount": 1000,
    "orderNumber": "xX8H9MkFIzpLmT"
}

JSON-объекты:

Объект Описание
orderId Идентификатор созданной сделки внутри Calltouch.
callId

Если сделка создается по звонку, в данном объекте будет идентификатор этого звонка, который Вы отправили в запросе. Если сделка создается по заявке, requestId в JSON-ответе отсутствует.

dateCreated Дата и время создания сделки, отправленные Вами в параметре orderDate запроса.
status Статус сделки, отправленный Вами в параметре orderStatus запроса.
sum Бюджет сделки, отправленный Вами в параметре orderSum запроса.
orderNumber Уникальный идентификатор сделки в Вашей CRM, который Вы отправили в параметре orderNumber запроса. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор сделки в Calltouch (он же будет и в объекте orderId далее).

 

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

 

 

API-метод для обновления существующих сделок

Запрос

API-метод необходим для обновления статуса сделки и изменению ее бюджета.

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

API-запрос:

https://api-nodeX.calltouch.ru/calls-service/RestAPI/orders/update-by-id/

Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.

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

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

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

api-token.png

orderId
или
orderNumber

Идентификаторы сделки, информацию по которой требуется обновить.

Обновление информации по сделке происходит по одному из этих идентифкаторов по следующей логике:

  • Если в API-запросе обновления сделки указан параметр orderId и не указан orderNumber, то поиск сделки для обновления производится по значению из orderId.
  • Если в API-запросе обновления сделки указан параметр orderNumber и не указан orderId, то поиск сделки для обновления производится по значению из orderNumber.
  • Если в API-запросе обновления сделки одновременно указаны параметры orderNumber и orderId, то поиск сделки для обновления производится по значению из orderId. Если по значению из orderId сделка не была найдена, то поиск идет по значению в orderNumber.
  • Если в API-запросе обновления сделки не указан ни параметр orderNumber, ни параметр orderId, или указаны, но найти сделку по их значениям не удалось, возвращается ошибка 400 Bad Request.

Идентификаторы можно получить либо с помощью API-метода для выгрузки сделок далее, либо в JSON-ответе на запросы создания сделок (см. ответы выше).

orderSum Бюджет сделки в рублях. Укажите новый бюджет, если необходимо обновить его, или не передавайте параметр, если бюджет сделки не изменился.
comment Комментарий к сделки.
status

Укажите новый статус сделки. Если статус сделки не поменялся, параметр передавать не нужно.

manager Укажите нового менеджера, отвечающего за сделку. Если менеджер не поменялся, параметр передавать не нужно.
service Укажите новое название сервиса, использующего наше API. Если сервис не поменялся, параметр передавать не нужно.
tags Укажите новый список тегов сделки. Можно передавать более одного тега через запятую. При указании этого параметра предыдущие теги удалятся и заменятся текущим указанным списком тегов. Если теги не поменялись, параметр передавать не нужно

 

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

Запрос обновит сделку с идентификатором Calltouch orderId 3413448, при этом обновив ее статус на "selling", обновив ее бюджет до 100000 руб, обновив менеджера на "Алексей", обновив сервис, использующий наше API на "RetailCRM" и обновив теги сделки на "newtag1, newtag2":

https://api-node3.calltouch.ru/calls-service/RestAPI/orders/update-by-id/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&orderId=3413448&orderSum=100000&status=selling&manager=Алексей&service=RetailCRM&tags=newtag1,newtag2

 

Запрос обновит сделку с идентификатором из вашей CRM orderNumber ajhbkhbsd232dsc, при этом обновив ее статус на "work" и обновив ее бюджет до 100000 руб.

https://api-node3.calltouch.ru/calls-service/RestAPI/orders/update-by-id/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&orderNumber=ajhbkhbsd232dsc&orderSum=100000&status=work

 

Ответ

После успешной отправки API-запроса на обновление сделки, возвращается следующий JSON-ответ (пример):

    "order": {
        "orderId": 7812899,
        "callId": 32948652,
        "dateCreated": 1522047600000,
        "status": "end",
        "realSum": null,
        "offered": "27.03.2018",
        "sent": "26.03.2018",
        "sum": "6000.0000",
        "isMarked": null,
        "commentsCount": 0,
        "currentAmount": null,
        "orderNumber": "7812899"
    },
    "client": {
        "fio": null,
        "clientId": 37674333,
        "phones": [
            {
                "phoneNumber": "74953080100",
                "phoneType": "WORK"
            }
        ],
        "contacts": null
    },
    "orderComments": "",
    "session": {
        "keywords": "(not set)",
        "city": "vladimir",
        "ip": "95.66.182.68",
        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
        "source": "(direct)",
        "medium": "(none)",
        "ref": "",
        "url": "http://filipok.io/calltouch/?attrs={\"attrh\":1,\"ver\":171110,\"r7k12_si\":479775180}",
        "utmSource": "",
        "utmMedium": "",
        "utmTerm": "",
        "utmContent": "",
        "utmCampaign": "",
        "guaClientId": null,
"yaClientId": null, "sessionId": 1846408120, "additionalTags": [], "attribution": 1,
"attrs": null } }

JSON-объекты:

Объект Описание
order

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

  • orderId - идентификатор обновленной сделки внутри Calltouch.
  • callId - если сделка была привязана по звонку, в данном объекте будет идентификатор этого звонка. Если сделка привязана к заявке, requestId в JSON-ответе отсутствует.
  • dateCreated - дата и время создания сделки.
  • status - статус сделки.
  • sum - бюджет сделки.
  • orderNumber - уникальный идентификатор сделки в Вашей CRM, который Вы ранее отправляли в параметре orderNumber запроса на создание сделки. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор сделки в Calltouch (он же будет и в объекте orderId далее).
client

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

  • fio - имя клиента.
  • clientId - идентификатор клиента внутри Calltouch.
  • phones - содержит массив, внутри которого в объекте phoneNumber содержится номер телефона клиента.
  • contacts - содержит массив, внутри которого в объекте contactValue содержится почта клиента.
session

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

  • keywords - ключевой запрос
  • city - город посетителя (определяется по его IP-адресу)
  • ip - IP-адрес
  • browser - Браузер
  • source - Источник перехода
  • medium - Канал перехода
  • ref - адрес страницы, с которой был совершен реферальный переход на Ваш отслеживаемый сайт (присутствует только если переход посетителя был реферальным)
  • url - адрес входа на сайт (может отличаться от страницы, с которой в итоге был совершен звонок)
  • utmSource - значение utm-метки utm_source
  • utmMedium - значение utm-метки utm_medium
  • utmTerm - значение utm-метки utm_term
  • utmContent - значение utm-метки utm_content
  • utmCampaign - значение utm-метки utm_campaign
  • guaClientId - идентификатор Google Client ID (присутствует, если настроена интеграция с Google Analytics)
  • yaClientId - идентификатор Yandex Client ID (присутствует, если настроена интеграция с Яндекс.Метрика)
  • sessionId - идентификатор сессии Calltouch, который Вы отправили в запросе ранее
  • attribution - текущая модель атрибуции, согласно которой определился источник заявки (модель атрибуции может быть изменена в системных настройках ЛК, после этого источники будут "на лету" переопределены у всех звонков и заявок ранее)
  • attrs - Сторонние параметры, переданные заранее в статистику Calltouch.

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

 

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

 

 

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.

 

Пример 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.
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-запрос завершится с ошибкой.

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 2 из 2
Еще есть вопросы? Отправить запрос

0 Комментарии

Войдите в службу, чтобы оставить комментарий.