Обновление сделок

Читать 14

Запрос

POST: https://api.calltouch.ru/lead-service/v1/api/client-order/update

HTTP-заголовки:

  • 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": "ФИО менеджера",
            "leadManager": {
                "manager": "Иван Иванов",
                "overwrite": false
            },
            "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"}
            ],
            "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"]
                }
            },
            "reMatching": [
                {
                    "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": "nearest",
                        "searchDepth": 262800
                    }
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "date": "Дата и время звонка",
                        "tags": ["тег1","тег2"],
                        "tagsLogic": "and",
                        "callTypeToMatch": "nearest",
                        "searchDepth": 262800
                    }
                },
                {
                    "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 Дата и время перехода сделки на текущий статус. Формат: dd-mm-yyyy hh:mm:ss.
orders.updateDate string Да

Дата и время обновления сделки. Формат: dd-mm-yyyy hh:mm:ss.

Дата обновления сделки будет не датой обработки API-запроса на обновление, а указанная в самом запросе дата.

Дата и время статуса сделки должно быть равно или предшествовать дате и времени обновления. Обратное условие, нежели в API-методе создания сделок, потому что статус не может появится раньше сделки, и не может быть обновлен позже, чем обновлена вся сделка.

orders.currency string Нет Актуальная валюта сделки.

Возможные значения: "rub", "usd". Если не указано, то оставляем текущее значение.

orders.revenue string Нет Актуальная выручка.
orders.margin string Нет Актуальная маржинальность сделки. Если не указано, оставляем текущее значение.
orders.manager string Нет Актуальное ФИО менеджера. Любые символы, максимум 50.
orders.leadManager
.manager 
string Нет

Добавление менеджера к лиду, к которому приклеивается сделка. Любые символы, максимум 50. Если сделка не склеивается ни с каким лидом, то менеджер не добавится.

Формат:

"leadManager": {
   "manager": "Иван Иванов", "overwrite": false
}
orders.leadManager
.overwrite
boolean Нет

Перезаписываем ли существующего менеджера у лида, если он уже есть в лиде. Возможные значения:

  • false — не перезаписывем;
  • true — перезаписываем.

Если не указан, по умолчанию false.

orders.orderLink string Нет Ссылка на сделку в CRM. Если не передано, то оставляем текущее значение.
orders.orderName string Нет

Название сделки в CRM. 

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

orders.addNewComment.text string Нет Обновление комментария. Если до этого существовал комментарий у сделки, он перезатрется.
orders.addtags.tags array Нет

Добавление тегов к сделке. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Любые символы, максимум 100 в каждом теги. Максимум 100 тегов.

Формат:

"addTags": [
   {"tag": "Тег 1"},
   {"tag": "Тег 2"},
   {"tag": "Тег N"}
]
orders.addtags.overwrite boolean Нет

Флаг перезатираем ли мы существующие у сделки теги или добавляем новые теги к существующим. Возможные значения:

  • false  Добавляем
  • true — Перезатираем

Если не указан, по умолчанию false.

orders.addTagsToLeads.tags array Нет

Добавление тегов к лиду, к которому приклеивается сделка. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Необязательно, максимум 100 тегов. Если сделка не склеивается ни с каким лидом, то теги соответственно не добавляем.

Формат:

"addTagsToLead": {
   "tags": [
      { "tag": "Тег 1" },
      { "tag": "Тег 2" }
   ],
   "overwrite": true
}
orders.addTagsToLeads.overwrite boolean Нет

Флаг перезатираем ли мы существующие у лида теги или добавляем новые теги к существующим. Возможные значения:

  • false  Добавляем
  • true  Перезатираем

Если не указан, по умолчанию false.

orders.customFields array Нет

Пользовательские поля API. Для использования их необходимо заранее добавить в настройках API ЛК Calltouch.

Поля в ЛК Calltouch могут быть или числовыми, или текстовыми. В числовые можно передавать только цифры, дробная часть отделяется точкой, максимум 100 символов. В текстовые поля допустимо передавать любые символы, максимум 100. Если при обновлении параметр не передан, то оставляем ранее переданное.

Формат:

"customFields": [
   {"field": "grossprofit", "value": "456.50"},
   {"field": "new", "value": "123"},
   {"field": "text", "value": "some string"}
]
orders.addCustomFieldsToLead.
customFields
array  Нет

Добавление пользовательских полей к лиду, с которым была склеена сделка. 

Если в рамках создания или обновления сделки она не была склеена с лидом - то содержимое addCustomFieldsToLead просто игнорируется.

Пользовательское поле с переданным в API названием должно быть создано в ЛК заранее. Максимум 5 пользовательских полей.

Формат:

"addCustomFieldsToLead": {
     "customFields": [  
        {"field": "test_field", "value": "test value"},
        {"field": "num", "value": 123.4}
   ],
   "overwrite": false
}
orders.addCustomFieldsToLead.
overwrite
boolean  Нет Перезаписывать ли существующее значение пользовательского поля у лида или нет, при его наличии в лиде. Возможные значения:

  • false — Не перезаписывать.
  • true — Перезаписывать.
Если параметр не указан - по умолчанию false.
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 Нет Перепривязка/отвязка сделки к/от лида. Вначале пытаемся подобрать тип матчинга, который сработает, и только если находим такой, то отвязываем сделку от текущего лида.
orders.reMatching.type string Обязательно, если указан reMatching, нужно указать хотя бы 1 тип матчинга в приоритете. Тип матчинга у сделки. Возможные значения:
  • leadContact — поиск лида (звонка или заявки) по номеру телефона / почте / дате
  • callContact — поиск звонка по номеру телефона / дате
  • requestContact – поиск заявки по номеру телефона / почте / дате
  • call — поиск звонка по ID
  • request — поиск заявки по ID
  • session — поиск сессии по ID
  • customSources — не осуществлять поиск лида, а присвоить сделке произвольный источник
  • withoutSource — создать сделку без привязки к какому-либо лиду или источнику.

Типы матчинга customSources и withoutSource являются конечными, т.е. нет смысла размещать под ними другие типы, т.к. типы customSources и withoutSource сработают 100%.

Подробное описание полей в объекте matching в этой статье.

orderContacts object Нет Объект с контактами из сделки
orderContacts.
mainContacts
object Нет Объект с основными контактами из сделки
orderContacts.
mainContacts.
fio
string Нет ФИО из сделки
orderContacts.
mainContacts.
phoneNumber
string Нет Основной номер телефона из сделки, в формате 7XXXXXXXXXX
orderContacts.
mainContacts.
email
string Нет Основной email из сделки
orderContacts.
mainContacts.
overwrite
boolean Нет

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

  • true — перезаписываем,
  • false — не перезаписываем.

Если не передан - по умолчанию true. Распространяется и на fio, и на phoneNumber, и на email.

orderContacts.
otherContacts
object Нет Объект с дополнительными контактами сделки
orderContacts.
otherContacts.
phoneNumber
array Нет Дополнительные номера телефона из сделки. В формате 7XXXXXXXXXX. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные телефоны, если не был передан основной телефон.
orderContacts.
otherContacts.
email
array Нет Дополнительные Email из сделки. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные Email, если не был передан основной Email.
orderContacts.
otherContacts.
overwrite
boolean Нет

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

  • true — перезаписываем,
  • false — не перезаписываем, добавляем переданные дополнительные контакты к существующим в сделке. Больше 3 телефонов или email-ов добавить нельзя, избыточные контакты добавлены не будут.

Если не передан - по умолчанию true. Распространяется и на phoneNumber, и на email.

Ответ

Процесс обновления запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:

{
    "meta": [],
    "data": {
        "orders": [
            {
                "orderNumber": "UdvPC9bBjjLnEJ9R",
                "updateStatus": "success",
                "error": null "matchedType":"call", "callInfo": { callId: 123456, callReferenceId: "abc123", sipCallId: "abc123-abc123" }, "requestInfo": null             }         ]     } }

Параметры ответа

Параметр Формат Описание
data.orders.orderNumber string Переданный ID сделки из внешний CRM в запросе на обновление.
data.orders.updateStatus string

Статус обновления. Возможные значения:

  • success
  • error
data.orders.matchedType string Тип лида с которым сматчена обновленная сделка, "request" для заявок, "call" для звонков
data.orders[n].callInfo object Если сделка склеилась со звонком, то блок callInfo не пустой, иначе null
data.orders[n].callInfo.callId string ID звонка в Calltouch
data.orders[n].callInfo.callReferenceId string Внешний ID звонка
data.orders[n].callInfo.sipCallId string ID звонка с АТС
data.orders[n].requestInfo object Если сделка склеилась с заявкой, то блок requestInfo не пустой, иначе null
data.orders[n].requestInfo.requestId string ID заявки в Calltouch
data.orders[n].requestInfo.requestNumber string Внешний ID заявки
data.orders.error string Отображается причина ошибки обновления

 

Если в запросе обнаруживаются ошибки валидации, то обновление не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "orders[0].statusDate",
                    "message": "Значение даты и времени недопустимо."
                }
            ]
        }
    }
}

Если в запросе указаны некорректные авторизационные данные — то выводится ошибка. Список типовых ответов при запросах с некорректными авторизационными данными, или некорректными данными в теле API запроса вы можете посмотреть в этой статье

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

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

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


Не нашли решение проблемы?
Заполните форму, и мы вам поможем.