Данный метод предназначен только для модуля интеграции с 1С. Для создания, обновления, поиска и удаления сделок используйте новые API-методы версии 2.0.
Содержание
- API-метод для создания новых сделок
- API-метод для обновления существующих сделок
- API-метод для удаления существующих сделок
API-метод для создания новых сделок
Запрос с указанием ID звонка или заявки
Если Вам заранее известен внутренний ID Calltouch звонка (callId) или заявки (requestId) или внешний ID заявки (requestNumber), то Вы можете создать сделку по звонку или заявке, используя API-запрос ниже. Заранее получить внутренние ID звонков можно с помощью вебхуков или API-метода для выгрузки звонков, заранее получить внутренние ID заявок можно с помощью API-метода для выгрузки заявок. Внешние ID заявок можно передавать в Calltouch на этапе создания заявок через API.
Поддерживаемые методы отправки: GET и POST.
API-запрос:
Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
Параметры запроса:
| Параметр | Описание |
| clientApiId |
Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
| callId или callReferenceId или requestId или requestNumber |
Сделку можно создать либо по звонку, либо по заявке. Соответственно при отправке запроса необходимо использовать параметр:
Нельзя создать сделку одновременно по звонку и заявке. Либо только по звонку, либо только по заявке. Сделка не может быть привязана одновременно ко звонку и к заявке. Если Вы вовсе не отправите ни callId ни requestId ни requestNumber, то сделка будет создана в статистике Calltouch, но во всех отчетах будет отображаться без источника, т.к. источником сделки является источник звонка или заявки, за которым она закреплена. В этом случае вы можете передать параметры произвольного источника сделки (source, medium и т.д., см. далее) – тогда источник сделки будет определен по ним. |
| orderNumber |
Уникальный ID сделки на стороне Вашей CRM (не на стороне Calltouch). Параметр является необязательным. Рекомендуем использовать минимум 8-значные буквенно-цифровые идентификаторы (см. пример в запросе далее). Если параметр не указан, то по умолчанию он будет равен orderId (ID сделки в Calltouch), который Calltouch вернет в ответе на запрос (см. JSON-ответ далее). Обратите внимание! Если Вы отправляете какое-либо значение orderNumber, то для каждой новой сделки это значение обязательно должно быть уникальным. |
| orderSum | Бюджет сделки в рублях. Обязательный параметр. |
| orderStatus |
Статус сделки. Обязательный параметр. Вы можете передавать в Calltouch любой статус сделок. Он будет отображаться в отчетах через пользовательские столбцы, настроить которые вы можете в одноименном разделе настроек: |
| orderDate | Дата создания сделки. Обязательный параметр. Формат dd.mm.yyyy%20hh:mm:ss. |
| orderComment | Комментарий к сделки. |
| manager | Менеджер, отвечающий за сделку. Необязательный параметр. |
| service | Название сервиса, использующего наше API. Обязательный параметр. |
| tags | Теги сделки. Можно передавать более одного тега через запятую. Необязательный параметр. |
| source, medium, campaign, content, term |
Параметры произвольного источника сделки. Если по переданным ID не удалось найти звонок или заявку, то источник созданной сделки может быть определен по переданным параметрам.
Например, вы передали источник "пришел на ресепшн" и канал "оффлайн" у сделки, которая была совершена не по звонку:
После этого в ЛК будет создана сделка, а ее источник "пришел на ресепшн" и канал "оффлайн" будут отображаться во всех отчетах ЛК:
|
| 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":
- Создание сделки по заявке
Запрос далее создаст сделку на сумму 1000 руб со статусом "new" по заявке с идентификатором 51213218. Менеджером будет назначен "Коля". Сервис, использующий наше API выставится "AmoCRM". Сделке будут присвоены теги: "mytag1, mytag2, mytag3":
Запрос с указанием номера телефона клиента
В случае, если заранее получить ID звонка (с помощью вебхуков или API-метода для выгрузки звонков) не предоставляется возможным, то сделку можно склеить со звонком по номеру телефона (параметр phoneNumber далее), с которого звонил клиент, и дате создания сделки по этому звонку (параметр orderDate далее). Склейка по номеру телефона по умолчанию выключена - для её включения Вам необходимо отправить заявку Вашему аккаунт-менеджеру, либо перейти в раздел "Интеграции", "API и Webhooks", отметить соответствующий чекбокс и сохранить изменения. Данная опция доступна только для звонков, не для заявок. После включения, склейка звонка со сделкой по номеру телефона клиента и дате создания сделки по нему, будет производиться в течение 10 минут после отправки API-запроса.
После включения, склейка звонка со сделкой по номеру телефона клиента и дате создания сделки по нему, будет производиться в течение 10 минут после отправки API-запроса.
Мы рекомендуем использовать более точный API-метод создания сделки с указанием ID звонка или заявки.
Поддерживаемые методы отправки: GET и POST.
API-запрос:
Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
Вы могли заметить, что данный API-запрос точно такой же, как и предыдущий на создание сделки с указанием ID звонка или заявки. Так и есть, однако в случае необходимости склеивания звонка со сделкой по номеру телефона и дате создания сделки по этому звонку, у данного запроса будут отличаться входные параметры, описанные далее:
| Параметр | Описание |
| clientApiId |
Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
| 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 любой статус сделок. Он будет отображаться в отчетах через пользовательские столбцы, настроить которые вы можете в одноименном разделе настроек: |
| orderDate | Дата создания сделки. Обязательный параметр. Формат dd.mm.yyyy%20hh:mm:ss. |
| orderComment | Комментарий к сделки. |
| manager | Менеджер, отвечающий за сделку. Необязательный параметр. |
| service | Название сервиса, использующего наше API. Обязательный параметр. |
| tags | Теги сделки. Можно передавать более одного тега через запятую. Необязательный параметр. |
| source, medium, campaign, content, term |
Параметры произвольного источника сделки. Если по переданному номеру телефона не удалось найти звонок или заявку, то источник созданной сделки может быть определен по переданным параметрам.
Например, вы передали источник "пришел на ресепшн" и канал "оффлайн" у сделки, которая была совершена не по звонку:
После этого в ЛК будет создана сделка, а ее источник "пришел на ресепшн" и канал "оффлайн" будут отображаться во всех отчетах ЛК:
|
| 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"
Формат тела запроса при использовании метода POST
При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":
В случае использования формата "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-запрос:
Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
Параметры запроса:
| Параметр | Описание |
| clientApiId |
Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
|
orderId |
Идентификаторы сделки, информацию по которой требуется обновить.
Обновление информации по сделке происходит по одному из этих идентифкаторов по следующей логике:
Идентификаторы можно получить либо с помощью API-метода для выгрузки сделок далее, либо в JSON-ответе на запросы создания сделок (см. ответы выше). |
| orderSum | Бюджет сделки в рублях. Укажите новый бюджет, если необходимо обновить его, или не передавайте параметр, если бюджет сделки не изменился. |
| comment | Комментарий к сделки. |
| status |
Укажите новый статус сделки. Если статус сделки не поменялся, параметр передавать не нужно. |
| manager | Укажите нового менеджера, отвечающего за сделку. Если менеджер не поменялся, параметр передавать не нужно. |
| service | Укажите новое название сервиса, использующего наше API. Если сервис не поменялся, параметр передавать не нужно. |
| tags | Укажите новый список тегов сделки. Можно передавать более одного тега через запятую. При указании этого параметра предыдущие теги удалятся и заменятся текущим указанным списком тегов. Если теги не поменялись, параметр передавать не нужно |
| 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":
Запрос обновит сделку с идентификатором из вашей CRM orderNumber ajhbkhbsd232dsc, при этом обновив ее статус на "work" и обновив ее бюджет до 100000 руб.
Ответ
После успешной отправки 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 |
Объект будет содержать вложенные объекты с описанием сделки, данные по которой были обновлены. Описание вложенных объектов:
|
| client |
Объект будет содержать вложенные объекты с описанием клиента, который совершил звонок или заявку, к которой привязана сделка. Описание вложенных объектов:
|
| session |
Объект будет содержать вложенные объекты с описанием источника звонка или заявки, за которой закреплена сделка. Описание вложенных объектов:
Если звонок или заявка, за которой закреплена сделка, не имеют источника, то объект будет равен значению null. |
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
API-метод для удаления существующих сделок
Запрос
API-метод необходим для удаления сделки из всех отчетов Calltouch. Удаленных сделок так же не будет в API-методе выгрузки сделок.
Поддерживаемый метод отправки: GET.
API-запрос:
Параметры запроса:
| Параметр | Описание |
| clientApiId |
Токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
|
orderId |
Идентификатор сделки, которую требуется удалить.
Идентификаторы можно получить либо с помощью API-метода для выгрузки сделок далее, либо в JSON-ответе на запросы создания сделок (см. ответы выше). |
Пример GET-запроса на удаление сделки
Запрос удалит сделку с идентификатором Calltouch orderId=3413448:
Запрос удалит сделку с идентификатором из вашей CRM orderNumber=ajhbkhbsd232dsc.