Создание сделок
Запрос
POST: https://api.calltouch.ru/lead-service/v1/api/client-order/create
HTTP-заголовки:
- Access-Token – API-ключ
- SiteId – ID ЛК Calltouch
Тело запроса в формате JSON:
{ "crm": "Название CRM", "orders": [ // Сделка 1 { "matching": [ { "type": "request", "requestParams": { "requestId": 1, "tags": ["тег1","тег2"], "tagsLogic": "and" } }, { "type": "call", "callParams": { "callId": 2 , "tags": ["тег1","тег2"], "tagsLogic": "and" } }, { "type": "leadContact", "leadContactParams": { "emails": ["name@server.com"], "phones": ["79157771122", "+7 (915) 888-11-22"], "date": "Дата и время лида", "tags": ["тег1","тег2"], "tagsLogic": "and", "leadTypeToMatch": "nearestUniq", "searchDepth": 262800 } }, { "type": "requestContact", "requestContactParams": { "emails": ["name@server.com"], "phones": ["79157771122", "+7 (915) 888-11-22"], "date": "Дата и время заявки", "tags": ["тег1","тег2"], "tagsLogic": "and", "requestTypeToMatch": "nearestUniq", "searchDepth": 262800 } }, { "type": "callContact", "callContactParams": { "phones": ["84953338877"], "date": "Дата и время звонка", "tags": ["тег1","тег2"], "tagsLogic": "and", "callTypeToMatch": "nearestUniq", "searchDepth": 262800 } }, { "type": "customSources", "customSourceParams": { "source": "Произвольный источник", "medium": "Произвольный канал", "campaign": "Произвольная кампания", "content": "Произвольное объявление", "term": "Произвольная ключевая фраза" } }, { "type": "withoutSource" } ], "orderNumber": "ID сделки 1 внутри CRM", "funnel": "Название воронки", "status": "Название статуса", "statusDate": "Дата и время установки текущего статуса сделки", "orderDate": "Дата и время создания сделки", "currency": "rub", "revenue": "100000.50", "margin": "100.50", "orderLink": "https://site.ru/crm/deal/123/", "orderName": "Название сделки", "manager": "ФИО продавца", "comment": { "text": "Комментарий к сделке" }, "addTags": [ {"tag": "Тег 1"}, {"tag": "Тег 2"}, {"tag": "Тег N"} ], "addTagsToLead": { "tags": [ {"tag": "Тег 1"}, {"tag": "Тег 2"} ], "overwrite": true }, "customFields": [ {"field": "grossprofit", "value": "456.50"}, {"field": "name", "value": "123"} ], "addCustomFieldsToLead": { "customFields": [ {"field": "test_field", "value": "test value"} ], "overwrite": false }, "products": [ { "name": "Табурет", "price": "500.25", "brand": "ikea", "category": "Столы, стулья", "variant": "Черный", "quantity": 10 }, { "name": "Стол", "price": "1500" } ], "orderContacts": { "mainContacts": { "fio": "Иван", "phoneNumber": "79000000000", "email": "test@test.ru" }, "otherContacts": { "phoneNumber": ["79000000001","79000000002"], "email": ["test2@test.ru","test3@test.ru"] } } } // Сделка N ... ] }
Параметры запроса
Параметр | Формат | Обязательный | Описание |
crm | string | Да | Одно на все сделки, оно будет отображаться в карточке сделки в ЛК. Любые символы, максимум 30. |
orders | array | Да | Массив сделок. Можно перечислить до 100 сделок за 1 запрос. Склейка происходит в режиме онлайн. Результат склеивания будет доступен сразу же в ответе. Обязательно. |
orders.matching | array | Да |
Здесь задается приоритет использования разных типов матчинга, по которым сделка будет пытаться склеиться с лидом. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинг завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 20 строк. |
orders.matching.type | string | Обязательно нужно указать хотя бы 1 тип матчинга в приоритете. |
Тип матчинга у сделки. Возможные значения:
Типы матчинга customSources и withoutSource являются конечными, т.е. нет смысла размещать под ними другие типы, т.к. типы customSources и withoutSource сработают 100%. Подробное описание полей в объекте matching в этой статье. |
orders.orderNumber | string | Да | Уникальный ID сделки внутри CRM. Любые символы, максимум 100. |
orders.funnel | string | Нет | Название воронки. Любые символы, максимум 200. Если не указано, то сделка помещается в служебную воронку "Без воронки". |
orders.status | string | Да | Название статуса. Любые символы, максимум 100. |
orders.statusDate | string | Да |
Дата и время установки текущего статуса сделки. Формат: dd-mm-yyyy hh:mm:ss. |
orders.orderDate | string | Да |
Дата и время создания сделки. Формат: dd-mm-yyyy hh:mm:ss. Дата и время создания сделки должно быть равно или предшествовать дате и времени установки текущего статуса. |
orders.currency | string | Нет |
Валюта сделки.
Возможные значения: "rub", "usd". Если не указано, то используем "rub". |
orders.revenue | string | Нет | Выручка со сделки. Только числа, дробная часть отделяется точками. Максимум 100 символов. Если не указано, то считаем выручку равной 0. |
orders.margin | string | Нет | Маржинальность сделки. Только числа, дробная часть отделяется точками. Максимум 14 символов. |
orders.manager | string | Нет | ФИО продавца. Любые символы, максимум 50. |
orders.orderLink | string | Нет | Ссылка на сделку в CRM. Любые символы, максимум 256. Значение данного поля проходит валидацию на соответствие стандарту URL (наличие протокола (http и https), наличие доменов первого, второго, третьего и т.д. уровней (или ip-адрес)). В отчетах личного кабинета ссылка помещается в атрибут href для внешнего идентификатора сделки. |
orders.orderName | string | Нет |
Название сделки в CRM. Любые символы, максимум 200. |
orders.comment.text | object | Нет |
Комментарий сделки. Любые символы, максимум 1000. Формат:
"comment": { |
orders.addTags | array | Нет |
Добавление тегов к сделке. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Любые символы, максимум 100 в каждом теги. Максимум 100 тегов. Формат:
"addTags": [ |
orders.addTagsToLead .tags |
array | Нет |
Добавление тегов к лиду, к которому приклеивается сделка. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Необязательно, максимум 100 тегов. Если сделка не склеивается ни с каким лидом, то теги соответственно не добавляем. Формат:
"addTagsToLead": { |
orders.addTagsToLead .overwrite |
boolean | Нет |
Перезаписываем ли существующие у лида теги, или добавляем новые теги к существующим. Возможные значения:
Если не указан, по умолчанию false. |
orders.customFields | array | Нет |
Пользовательские поля API. Для использования их необходимо заранее добавить в настройках API ЛК Calltouch. Поля в ЛК Calltouch могут быть или числовыми, или текстовыми. В числовые можно передавать только цифры, дробная часть отделяется точкой, максимум 100 символов. Если не указано, то считаем значение поля равной 0. В текстовые поля допустимо передавать любые символы, максимум 100. Формат:
"customFields": [ |
orders.addCustomFieldsToLead .customFields |
array | Нет |
Добавление пользовательских полей к лиду, с которым была склеена сделка. Если в рамках создания или обновления сделки она не была склеена с лидом - то содержимое addCustomFieldsToLead просто игнорируется. Пользовательское поле с переданным в API названием должно быть создано в ЛК заранее. Максимум 5 пользовательских полей. Формат:
"addCustomFieldsToLead": { |
orders.addCustomFieldsToLead .overwrite |
boolean | Нет |
Перезаписывать ли существующее значение пользовательского поля у лида или нет, при его наличии в лиде. Возможные значения:
|
orders.products | array | Нет |
Товары, связанные со сделкой. Необязательный параметр. |
orders.products.name | string | Да, если передан orders.products |
Наименование товара. Любые символы, максимум 200. |
orders.products.brand | string | Нет |
Бренд, торговая марка товара. Любые символы, максимум 200. |
orders.products.category | string | Нет |
Категория товара. Любые символы, максимум 200. |
orders.products.variant | string | Нет |
Разновидность товара. Любые символы, максимум 200. |
orders.products.price | string | Нет |
Цена за единицу товара. Только числа, дробная часть отделяется точками, указывается до сотых. Максимум 20 символов. |
orders.products.quantity | integer | Нет |
Количество товаров. Только цифры, максимум 10 символов. Не может быть равно нулю. |
orderContacts | object | Нет |
Объект с контактами из сделки |
orderContacts. mainContacts |
object | Нет | Объект с основными контактами из сделки |
orderContacts. mainContacts. fio |
string | Нет | ФИО из сделки |
orderContacts. mainContacts. phoneNumber |
string | Нет | Основной номер телефона из сделки, в формате 7XXXXXXXXXX |
orderContacts. mainContacts. |
string | Нет | Основной email из сделки |
orderContacts. otherContacts |
object | Нет | Объект с дополнительными контактами сделки |
orderContacts. otherContacts. phoneNumber |
array | Нет |
Дополнительные номера телефона из сделки. В формате 7XXXXXXXXXX. Массив, максимум 3 штуки. Нельзя передавать дополнительные телефоны, если не был передан основной телефон. |
orderContacts. otherContacts. |
array | Нет |
Дополнительные Email из сделки. Массив, максимум 3 штуки. Нельзя передавать дополнительные Email, если не был передан основной Email. |
Ответ
Процесс матчинга запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:
{ "meta": [], "data": { "orders": [ { "orderNumber": "UdvPC9bBjjLnEJ9R", "calltouchOrderId": 2396375, "matchedType": "request", "created": true, "callInfo": null, "requestInfo": { "requestId": 1257513, "requestNumber": "1257513" }, "customSources": null, "error": null } ] } }
Параметры ответа
Параметр | Формат | Описание |
data.orders.orderNumber | string | Переданный ID сделки из внешний CRM в запросе на создание. |
data.orders.calltouchOrderId | string | ID сделки в Calltouch. Может быть null, если created=false. |
data.orders.matchedType | string |
Тип матчинга из параметра matching API-запроса на создание сделки, по которому сделка склеилась с лидом. Если сделка не склеилась со сделкой и тип withoutSource не был передан, то отображается значение null. |
data.orders.created | boolean |
Флаг создания сделки. Возможные значения:
Создание и склеивание – разные процессы, т.к. сделка может быть создана и без связи с лидом. |
data.orders.callInfo | object |
Если сделка склеилась со звонком, то блок callInfo не пустой. |
data.orders.callInfo.callId | string | ID звонка в Calltouch |
data.orders.callInfo.callReferenceId | string | ID звонка из API-метода импорта звонков, может быть null |
data.orders.callInfo.sipCallId | string | ID звонка с АТС |
data.orders.requestInfo | object | Если сделка склеилась с заявкой, то блок requestInfo не пустой |
data.orders.requestInfo.requestId | string | ID заявки в Calltouch |
data.orders.requestInfo.requestNumber | string | ID заявки, переданный из формы сайта |
data.orders.customSources | object |
Если сделка не склеилась ни со звонком, ни с заявкой, но у нее были указаны произвольные источники, то в ответе отображаются они. Если сделка не склеилась ни со звонком, ни с заявкой, и у нее не было указаны произвольный источники, то отображается null. |
data.orders.customSources.source | string | Произвольный источник |
data.orders.customSources.medium | string | Произвольный канал |
data.orders.customSources.campaign | string | Произвольная кампания |
data.orders.customSources.content | string | Произвольное объявление |
data.orders.customSources.term | string | Произвольная ключевая фраза |
data.orders.error | string | Отображается причина ошибки матчинга |
Если в запросе обнаруживаются ошибки валидации, то матчинг не выполняется и выводится ошибка:
{ "meta": [], "data": { "type": "validationError", "apiErrorData": null, "validationErrorData": { "violations": [ { "fieldPath": "orders[0].statusDate", "message": "Значение даты и времени недопустимо." } ] } } }
Если в запросе указаны некорректные авторизационные данные - то выводится ошибка. Список типовых ответов при запросах с некорректными авторизационными данными, или некорректными данными в теле API запроса вы можете посмотреть в этой статье
Добавление пользовательских полей
В описанном выше методе вы можете использовать пользовательские поля для того, чтобы передать дополнительную информацию из вашей CRM-системы в личный кабинет Calltouch. Для того, чтобы создать такое поле в вашем личном кабинете, необходимо зайти в раздел «Интеграции –> API и Webhooks»:
- Название поля в ЛК. Это название будет отображаться в настройках пользовательских метрик. Любые символы, максимум 100.
- Название поля в API. Это поле будет доступно для использования в API-методах создания и обновления сделок. Только английские буквы и символы дефиса «-» или подчеркивания «_», максимум 100.
- Формат поля. Текстовый формат может быть использован в качестве фильтров сделок в пользовательских метриках. Числовые значения используются в качестве показателей.
Это делает возможным выгружать к нам из CRM любые показатели сделок, например, себестоимость, операционные доходы, чистую прибыль, размер скидки и любые другие характеристики. Все добавленные поля автоматически становятся доступными в:
- В API-методах создания/обновления/выгрузки сделок
- В пользовательских метриках Calltouch
Например, как в ЛК Calltouch увидеть валовую прибыль? Теперь очень просто. Добавьте поле "Себестоимость" в API и выгружайте в него данные из CRM. А чтобы посчитать валовую прибыль, просто создайте пользовательскую метрику, задав в ней формулу "Выручка со сделок - Себестоимость". Эта метрика станет доступной в любом отчете Calltouch.
Система баллов API Calltouch
Система баллов API - механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch
и мы поможем вам
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)