Обновление сделок
Запрос
POST: https://api.calltouch.ru/lead-service/v1/api/client-order/update
- Access-Token – API-ключ
- SiteId – ID ЛК Calltouch
Тело запроса в формате JSON:
{ "orders": [ // Сделка 1 { "orderNumber": "ID сделки 1 во внешней CRM", "funnel": "Название воронки", "status": "Новая сделка", "statusDate": "Дата и время перехода сделки на текущий статус", "updateDate": "Дата и время обновления сделки", "currency": "rub", "revenue": "100000.50", "margin": "100.50", "manager": "ФИО продавца", "orderLink": "https://site.ru/crm/deal/123/", "orderName": "Название сделки", "addNewComment": { "text": "Комментарий к сделке" }, "addTags": { "overwrite": false, "tags": [ {"tag": "Тег 1"}, {"tag": "Тег 2"}, {"tag": "Тег N"} ] }, "addTagsToLeads": { "overwrite": false, "tags": [ {"tag": "Тег 1"}, {"tag": "Тег 2"}, {"tag": "Тег N"} ] }, "customFields": [ {"field": "grossprofit", "value": "456.50"}, {"field": "name", "value": "123"} ], "products": [ { "name": "Табурет", "price": "500.25", "brand": "ikea", "category": "Столы, стулья", "variant": "Черный", "quantity": 10 }, { "name": "Стол", "price": "1500" }], "reMatching": [ { "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": "nearest", "searchDepth": 262800 } }, { "type": "callContact", "callContactParams": { "phones": ["84953338877"], "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"], "date": "Дата и время звонка", "tags": ["тег"], "tagsLogic": "and", "callTypeToMatch": "nearest", "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" } ] }, // Сделка N ... ] }
Параметры запроса
Параметр | Формат | Обязательно | Описание |
orders | array | Да | Массив сделок. Можно перечислить до 100 сделок за 1 запрос. Обновление происходит в режиме онлайн. |
orders.orderNumber | string | Да | По этому ID мы будем находить у себя уже существующую сделку и обновлять ее. Если не найдем, то выводить ошибку напротив этой сделки в ответе. Обязательно. |
orders.funnel | string | Нет | Актуальная воронки. Если не указано, то сделка помещается в служебную воронку "Без воронки". Для обновления воронки требуется отправлять вместе с актуальным статусом. |
orders.status | string | Нет | Актуальный статус. |
orders.statusDate | string | Обязательно, если указан status | Дата и время перехода сделки на текущий статус. |
orders.updateDate | string | Да |
Дата и время обновления сделки. Дата обновления сделки будет не датой обработки API-запроса на обновление, а указанная в самом запросе дата. Дата и время статуса сделки должно быть равно или предшествовать дате и времени обновления. Обратное условие, нежели в API-методе создания сделок, потому что статус не может появится раньше сделки, и не может быть обновлен позже, чем обновлена вся сделка. |
orders.currency | string | Нет |
Актуальная валюта сделки.
Возможные значения: "rub", "usd". Если не указано, то оставляем текущее значение. |
orders.revenue | string | Нет | Актуальная выручка. |
orders.margin | string | Нет | Актуальная маржинальность сделки. Если не указано, оставляем текущее значение. |
orders.manager | string | Нет | Актуальное ФИО продавца. |
orders.orderLink | string | Нет | Ссылка на сделку в CRM. Если не передано, то оставляем текущее значение. |
orders.orderName | string | Нет |
Название сделки в CRM. Если не передано, то оставляем текущее значение. |
orders.addNewComment.text | string | Нет | Обновление комментария. Если до этого существовал комментарий у сделки, он перезатрется. |
orders.addtags.tags | array | Нет | Добавление тегов к сделке. |
orders.addtags.overwrite | boolean | Нет |
Флаг перезатираем ли мы существующие у сделки теги или добавляем новые теги к существующим. Возможные значения:
Если не указан, по умолчанию false. |
orders.addTagsToLeads.tags | array | Нет | Добавление тегов к лиду, к которому привязана сделка. |
orders.addTagsToLeads.overwrite | boolean | Нет |
Флаг перезатираем ли мы существующие у лида теги или добавляем новые теги к существующим. Возможные значения:
Если не указан, по умолчанию false. |
orders.customFields | array | Нет |
Пользовательские поля API. Для использования их необходимо заранее добавить в настройках API ЛК Calltouch. Поля в ЛК Calltouch могут быть или числовыми, или текстовыми. В числовые можно передавать только цифры, дробная часть отделяется точкой, максимум 100 символов. В текстовые поля допустимо передавать любые символы, максимум 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 символов. Не может быть равно нулю. Если не передано, то оставляем текущие данные. |
orders.reMatching | array | Нет | Перепривязка/отвязка сделки к/от лида. Вначале пытаемся подобрать тип матчинга, который сработает, и только если находим такой, то отвязываем сделку от текущего лида. Параметры и логика идентичны параметру matching API-метода создания сделок. |
Ответ
Процесс обновления запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:
{
"meta": [],
"data": {
"orders": [
{
"orderNumber": "UdvPC9bBjjLnEJ9R",
"updateStatus": "success",
"error": null
}
]
}
}
Если API-токен не указан, то обновление не выполняется и выводится ошибка:
{
"meta": [],
"data": {
"message": "Ошибка доступа"
}
}
Если API-токен указан не верно, то обновление не выполняется и выводится ошибка:
{
"message": "Access token не найден"
}
Параметры ответа
Параметр | Формат | Описание |
data.orders.orderNumber | string | Переданный ID сделки из внешний CRM в запросе на обновление. |
data.orders.updateStatus | string |
Статус обновления. Возможные значения:
|
data.orders.error | string | Отображется причина ошибки обновления |
Если в запросе обнаруживаются ошибки валидации, то обновление не выполняется и выводится ошибка:
{
"meta": [],
"data": {
"type": "validationError",
"apiErrorData": null,
"validationErrorData": {
"violations": [
{
"fieldPath": "orders[0].statusDate",
"message": "Значение даты и времени недопустимо."
}
]
}
}
}