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

Читать 10

Запрос

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": "ФИО продавца",
            "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": ["тег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 Дата и время перехода сделки на текущий статус.
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 - Добавляем
  • true - Перезатираем

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

orders.addTagsToLeads.tags array Нет Добавление тегов к лиду, к которому привязана сделка.
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.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 в этой статье.

Ответ


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

{
    "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-запросы завершатся с ошибкой.

Похожие статьи
Недавно просмoтренные