Управление сделками через API (1.0 / 1С-устаревшее)

Читать 28

Устаревшая версия API, не используйте для настройки новых интеграций. Для создания, обновления, поиска и удаления сделок используйте новые API-методы версии 2.0.

API-метод для создания новых сделок

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

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

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

API-запрос: 

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

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

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

Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе:  Интеграции /  Отправка данных во внешние системы / API и Webhooks / API. 

callId
или
callReferenceId или
requestId
или requestNumber

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

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

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

orderNumber

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

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

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

Параметры произвольного источника сделки.

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

  • Источник
    из параметра source
  • Канал
    из параметра medium
  • Кампания
    из параметра campaign
  • Объявление
    из параметра content
  • Ключевое слово
    из параметра term

Например, вы передали источник "пришел на ресепшн" и канал "оффлайн" у сделки, которая была совершена не по звонку:

________________________________API.png

После этого в ЛК будет создана сделка, а ее источник "пришел на ресепшн" и канал "оффлайн" будут отображаться во всех отчетах ЛК:


custom[field]

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

custom[field1]=value1&custom[field2]=value2&custom[fieldN]=valueN

Где вместо field1, field2, fieldN указываются название кастомных полей, добавленных в настройках.

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

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

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

https://api.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.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 далее) или по почте клиента (параметр email далее) и дате создания сделки (параметр orderDate далее). Склейка по номеру телефона или почте по умолчанию выключена - для её включения вам необходимо отправить заявку Вашему аккаунт-менеджеру. После включения, склейка лида со сделкой по номеру телефона или почте клиента и дате создания сделки по нему, будет производиться в течение 10 минут после отправки API-запроса.

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

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

API-запрос: 

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

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

Параметр Описание
clientApiId Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе Интеграции /  Отправка данных во внешние системы / API и Webhooks / API. 
orderNumber Уникальный ID сделки на стороне Вашей CRM (не на стороне Calltouch). Параметр является необязательным. Рекомендуем использовать минимум 8-значные буквенно-цифровые идентификаторы (см. пример в запросе далее). Если параметр не указан, то по умолчанию он будет равен orderId (ID сделки в Calltouch), который Calltouch вернет в ответе на запрос.

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

phoneNumber Номер телефон клиента в формате 7XXXXXXXXXX. По этому номеру будет выполняться поиск звонка или заявки, в пределах даты, указанной в параметре orderDate и погрешности поиска, указанной в параметре linkTimeThreshold.
email Почта клиента. По переданной почте будет выполняться поиск заявки, в пределах даты, указанной в параметре 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.

Алгоритм связывания заявки со сделкой будет следующим:

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

bindTo
 		Выбор типа лидов, по которым осуществлять матчинг. Возможные значения:
  • calls — поиск только среди звонков;
  • requests — поиск только среди заявок.

Если параметр не передан, то поиск сначала среди звонков, потом среди заявок.

orderSum Бюджет сделки в рублях. Обязательный параметр.
orderStatus Статус сделки. Обязательный параметр. Вы можете передавать в Calltouch любой статус сделок. Он будет отображаться в отчетах через пользовательские метрики, настроить которые вы можете в одноименном разделе настроек.
orderDate Дата создания сделки. Обязательный параметр. Формат dd.mm.yyyy%20hh:mm:ss.
orderComment Комментарий к сделки.
manager Менеджер, отвечающий за сделку. Необязательный параметр.
service Название сервиса, использующего наше API. Обязательный параметр.
tags Теги сделки. Можно передавать более одного тега через запятую. Необязательный параметр.
source, medium, campaign, content, term  Параметры произвольного источника сделки.

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

  • Источник
    из параметра source
  • Канал
    из параметра medium
  • Кампания
    из параметра campaign
  • Объявление
    из параметра content
  • Ключевое слово
    из параметра term

Например, вы передали источник "пришел на ресепшн" и канал "оффлайн" у сделки, которая была совершена не по звонку:

________________________________API.png

После этого в ЛК будет создана сделка, а ее источник "пришел на ресепшн" и канал "оффлайн" будут отображаться во всех отчетах ЛК:



custom[field] Значения пользовательских полей (см. ранее), если они были добавлены в настройках API личного кабинета Calltouch.

custom[field1]=value1&custom[field2]=value2&custom[fieldN]=valueN

Где вместо field1, field2, fieldN указываются название кастомных полей, добавленных в настройках.

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


  • Создание сделки по номеру телефона

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

https://api.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 далее).
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.

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

Запрос

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

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

API-запрос: 

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

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

Параметр Описание
clientApiId Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе: Интеграции /  Отправка данных во внешние системы / API и Webhooks / API. 

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 Укажите новый список тегов сделки. Можно передавать более одного тега через запятую. При указании этого параметра предыдущие теги удалятся и заменятся текущим указанным списком тегов. Если теги не поменялись, параметр передавать не нужно
source, medium, campaign, content, term Если сделка не привязана ко звонку или заявке, то у нее может быть обновлен существующий или назначен новый произвольный источник:
  • Источник
    из параметра source
  • Канал
    из параметра medium
  • Кампания
    из параметра campaign
  • Объявление
    из параметра content
  • Ключевое слово
    из параметра term
 
custom[field] 

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

custom[field1]=value1&custom[field2]=value2&custom[fieldN]=valueN

Где вместо field1, field2, fieldN указываются название кастомных полей, добавленных в настройках.

Если в методе обновления сделки какой-либо из параметров выше передается с пустым значением, то текущее значение в статистике Calltouch будет перезаписано на пустоту. Поэтому если обновлять значение не требуется, то не передавайте параметр вовсе.

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


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

https://api.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.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.

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

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

Запрос

API-метод необходим для удаления сделки из всех отчетов Calltouch. Удаленных сделок так же не будет в API-методе выгрузки сделок.

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

API-запрос: 

https://api.calltouch.ru/calls-service/RestAPI/orders/delete-by-id/    
Параметры запроса:
Параметр Описание
clientApiId Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе: Интеграции /  Отправка данных во внешние системы / API и Webhooks / API. 

orderId
или
orderNumber

Идентификатор сделки, которую требуется удалить.

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

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


Запрос удалит сделку с идентификатором Calltouch orderId=3413448: 

https://api.calltouch.ru/calls-service/RestAPI/orders/delete-by-id/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&orderId=3413448

Запрос удалит сделку с идентификатором из вашей CRM orderNumber=ajhbkhbsd232dsc. 

https://api.calltouch.ru/calls-service/RestAPI/orders/delete-by-id/?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr&orderNumber=ajhbkhbsd232dsc

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

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

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

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