Создание сделок
Запрос
POST: https://api.calltouch.ru/lead-service/v1/api/client-order/create
- 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": ["тег"], "tagsLogic": "and" } }, { "type": "requestContact", "requestContactParams": { "emails": ["name@server.com"], "phones": ["79157771122", "+7 (915) 888-11-22"], "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"], "date": "Дата и время заявки", "tags": ["тег"], "tagsLogic": "and", "requestTypeToMatch": "nearestUniq", "searchDepth": 262800 } }, { "type": "callContact", "callContactParams": { "phones": ["84953338877"], "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"], "date": "Дата и время звонка", "tags": ["тег"], "tagsLogic": "and", "callTypeToMatch": "nearestUniq", "searchDepth": 262800 } }, { "type": "call", "callParams": { "callId": 2, "tags": ["тег"], "tagsLogic": "and" } }, { "type": "session", "sessionParams": { "sessionId": ["1234567"] } }, { "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"} ], "products": [ { "name": "Табурет", "price": "500.25", "brand": "ikea", "category": "Столы, стулья", "variant": "Черный", "quantity": 10 }, { "name": "Стол", "price": "1500" }] } // Сделка N ... ] }
Комментарии через // следует убрать из запроса перед его выполнением.
Параметры запроса
Параметр | Формат | Обязательный | Описание |
crm | string | Да | Одно на все сделки, оно будет отображаться в карточке сделки в ЛК. Любые символы, максимум 30. |
orders | array | Да | Массив сделок. Можно перечислить до 100 сделок за 1 запрос. Склейка происходит в режиме онлайн. Результат склеивания будет доступен сразу же в ответе. Обязательно. |
orders.matching | array | Да |
Здесь задается приоритет использования разных типов матчинга, по которым сделка будет пытаться склеиться с лидом. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинга завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 20 строк. |
orders.matching.type | string | Обязательно нужно указать хотя бы 1 тип маппинга в приоритете. |
Тип матчинга. Возможные значения:
Типы матчинга customSources и withoutSource являются конечными, т.е. нет смысла размещать под ними другие типы, т.к. типы customSources и withoutSource сработают 100%. |
orders.matching .requestParams |
object | Обязательно, если "type": "request" | Параметры матчинга заявки по ID |
orders.matching .requestParams.requestId |
integer / string | Обязательно, если "type": "request" |
Возможные параметры:
|
orders.matching .requestParams.tags |
array | Необязательно |
Если указан список тегов, то найденная заявка перед склейкой будет дополнительно проверена на наличие указанных тегов. И только если у заявки будут эти теги, то сделка будет к ней прикреплена. Иначе сделка не прикрепляется к заявке, а матчинг переключается на следующий тип в приоритете. Фильтрация по тегам может передаваться вместе с типами call, request, callContact и requestContact. |
orders.matching .requestParams.tagsLogic |
string | Обязательно, если указан параметр tags | Логические условие между тегами. Возможные значения: and (у заявки должны быть все перечисленные теги) или or (у заявки должен быть хотя бы один из перечисленных тегов). |
orders.matching .callParams |
object | Обязательно, если "type": "call" | Параметры матчинга звонка по ID |
orders.matching .callParams.callId |
integer / string | Обязательно, если "type": "call" |
Возможные параметры:
|
orders.matching .callParams.tags |
array | Необязательно | Аналогично описанию из блока requestParams |
orders.matching .callParams.tagsLogic |
string | Обязательно, если указан параметр tags и в нем передается более 1 тега | Аналогично описанию из блока requestParams |
orders.matching .requestContactParams |
object | Обязательно, если "type": "requestContact" | Параметра матчинга заявки по номеру телефона / почте / дате сделки |
orders.matching .requestContactParams .emails |
array |
Должен быть передан хотя бы один из параметров – phones, md5Phones или emails. Допустима передача сразу нескольких параметров, поиск будет идти по приоритету: поиск по phones. Если не нашли, то поиск по md5Phones. Если не нашли, то поиск по emails. |
Можно перечислить несколько почт (до 5 в одном параметре), формат x@x.x, любые символы. |
orders.matching .requestContactParams .phones |
array |
Можно перечислить несколько номеров телефонов (до 5 в одном параметре). Номера могут быть в любом формате, 71234567890, +71234567890, 8 (123) 456-78-90 и любом другом – мы должны автоматически конвертировать на бэке их в 11-значный формат.
|
|
orders.matching .requestContactParams .md5Phones
|
array |
Можно перечислить несколько md5-хэшей номеров телефонов. Хэши требуется передавать от номеров в формате +74953080100 (с плюсом вначале, далее номер в федеральном формате). При передаче хэшей от других форматов номеров телефонов заведомо не будет связи сделки с лидом. |
|
orders.matching .requestContactParams .date
|
string | Обязательно, если "type": "requestContact" |
Дата и время, относительно которой будет происходить поиск подходящей заявки в прошлое на кол-во минут из параметра searchDepth. Формат: dd-mm-yyyy hh:mm:ss. |
orders.matching .requestContactParams .tags |
array | Необязательно | Аналогично описанию из блока requestParams |
orders.matching .requestContactParams .tagsLogic |
string | Обязательно, если указан параметр tags и в нем передается более 1 тега | Аналогично описанию из блока requestParams |
orders.matching .requestContactParams .requestTypeToMatch |
string | Обязательно, если "type": "requestContact" |
Типы заявок, среди которых будет происходить поиск для склеивания со сделками. Возможные значения:
|
orders.matching .requestContactParams .searchDepth |
integer | Обязательно, если "type": "requestContact" | Глубина поиска подходящей заявки от даты лида date, указывается в мин. Возможные значения от 1 до 525600 мин (1 год). |
orders.matching .callContactParams |
object | Параметры матчинга звонка по номеру телефона / дате сделки | |
orders.matching .callContactParams .phones |
array | Обязательно, если "type": "callContact" | Аналогично описанию из блока requestContactParams |
orders.matching .callContactParams .date
|
string | Обязательно, если "type": "callContact" |
Дата и время, относительно которой будет происходить поиск подходящего звонка в прошлое на кол-во дней из параметра searchDepth. Формат: dd-mm-yyyy hh:mm:ss. |
orders.matching .callContactParams.tags |
array | Необязательно | Аналогично описанию из блока requestParams |
orders.matching .callContactParams .tagsLogic |
string | Обязательно, если указан параметр tags и в нем передается более 1 тега | Аналогично описанию из блока requestParams |
orders.matching .callContactParams .callTypeToMatch |
string | Обязательно, если "type": "callContact" | Аналогично описанию из блока requestContactParams |
orders.matching .callContactParams .searchDepth |
integer | Обязательно, если "type": "callContact" | Аналогично описанию из блока requestContactParams |
orders.matching .sessionParams |
object | Обязательно, если "type": "session" | Параметры матчинга сессии по ID |
orders.matching .requestParams.sessionId |
string | Обязательно, если "type": "session" | Значение sessionID |
orders.matching .customSourceParams |
object | Обязательно, если "type": "customSources" | Не осуществлять матчинг сделки, а присвоить сделки произвольный источник |
orders.matching .customSourceParams .source |
string | Обязательно, если "type": "customSources" | Произвольный источник, максимум 100 символов или меньше. |
orders.matching .customSourceParams .medium |
string | Обязательно, если "type": "customSources" | Произвольный канал, максимум 100 символов или меньше. |
orders.matching .customSourceParams .campaign |
string | Обязательно, если "type": "customSources" | Произвольная кампания, максимум 100 символов или меньше. |
orders.matching .customSourceParams .content |
string | Нет | Произвольное объявление, максимум 100 символов или меньше. |
orders.matching .customSourceParams .term |
string | Нет | Произвольная ключевая фраза, максимум 100 символов или меньше. |
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 | Нет | ФИО продавца. Любые символы, максимум 100. |
orders.orderLink | string | Нет | Ссылка на сделку в CRM. Любые символы, максимум 256. Значение данного поля проходит валидацию на соответствие стандарту URL (наличие протокола (http и https), наличие доменов первого, второго, третьего и т.д. уровней (или ip-адрес)). В отчетах личного кабинета ссылка помещается в атрибут href для внешнего идентификатора сделки. |
orders.orderName | string | Нет |
Название сделки в CRM. Любые символы, максимум 200. |
orders.comment.text | object | Нет |
Комментарий сделки. Любые символы, максимум 1000. Формат:
"comment": { |
orders.addTags.tag | array | Нет |
Добавление тегов к сделке. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Любые символы, максимум 100 в каждом теги. Максимум 100 тегов. Формат:
"addTags": [ |
orders.addTagsToLead .tags |
array | Нет |
Добавление тегов к лиду, к которому приклеивается сделка. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Необязательно, максимум 100 тегов. Если сделка не склеивается ни с каким лидом, то теги соответственно не добавляем. Формат:
"addTagsToLead": { |
orders.addTagsToLead .overwrite |
boolean | Нет | Перезаписывать ли существующие теги у лида или нет. Обязательно, если указывается addTagsToLead. |
orders.customFields | array | Нет |
Пользовательские поля API. Для использования их необходимо заранее добавить в настройках API ЛК Calltouch. Поля в ЛК Calltouch могут быть или числовыми, или текстовыми. В числовые можно передавать только цифры, дробная часть отделяется точкой, максимум 100 символов. Если не указано, то считаем значение поля равной 0. В текстовые поля допустимо передавать любые символы, максимум 100. Формат:
"customFields": [ |
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 символов. Не может быть равно нулю. |
Ответ
Процесс матчинга запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:
{
"meta": [],
"data": {
"orders": [
{
"orderNumber": "UdvPC9bBjjLnEJ9R",
"calltouchOrderId": 2396375,
"matchedType": "request",
"created": true,
"callInfo": null,
"requestInfo": {
"requestId": 1257513,
"requestNumber": "1257513"
},
"customSources": null,
"error": null
}
]
}
}
{
"meta": [],
"data": {
"message": "Ошибка доступа"
}
}
Если API-токен указан не верно, то матчинг не выполняется и выводится ошибка:
{
"message": "Access token не найден"
}
Параметры ответа
Параметр | Формат | Описание |
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": "Значение даты и времени недопустимо."
}
]
}
}
}
Добавление пользовательских полей
В описанном выше методе вы можете использовать пользовательские поля для того, чтобы передать дополнительную информацию из вашей CRM-системы в личный кабинет Calltouch. Для того, чтобы создать такое поле в вашем личном кабинете, необходимо зайти в раздел «Интеграции –> API и Webhooks»:
- Название поля в ЛК. Это название будет отображаться в настройках пользовательских метрик. Любые символы, максимум 100.
- Название поля в API. Это поле будет доступно для использования в API-методах создания и обновления сделок. Только английские буквы и символы дефиса «-» или подчеркивания «_», максимум 100.
- Формат поля. Текстовый формат может быть использован в качестве фильтров сделок в пользовательских метриках. Числовые значения используются в качестве показателей.
Это делает возможным выгружать к нам из CRM любые показатели сделок, например, себестоимость, операционные доходы, чистую прибыль, размер скидки и любые другие характеристики. Все добавленные поля автоматически становятся доступными в:
- В API-методах создания/обновления/выгрузки сделок
- В пользовательских метриках Calltouch
Например, как в ЛК Calltouch увидеть валовую прибыль? Теперь очень просто. Добавьте поле "Себестоимость" в API и выгружайте в него данные из CRM. А чтобы посчитать валовую прибыль, просто создайте пользовательскую метрику, задав в ней формулу "Выручка со сделок - Себестоимость". Эта метрика станет доступной в любом отчете Calltouch.
При удалении пользовательского поля, все данные, переданные в нем, будут так же удалены.