Наверх

API-метод обновления сделок

Запрос

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",
            "status": "Новая сделка",
            "statusDate": "Дата и время перехода сделки на текущий статус",
            "updateDate": "Дата и время обновления сделки",
            "revenue": "100000.50",
            "manager": "ФИО продавца",
            "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"}
                ],
            "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"],
                        "date": "Дата и время заявки",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "requestTypeToMatch": "nearestUniq",
                        "searchDepth": 120
                    }
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "date": "Дата и время звонка",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "callTypeToMatch": "nearestUniq",
                        "searchDepth": 120
                        }
                },
                {
                    "type": "call",
                    "callParams": {
                        "callId": 2,
                        "tags": ["тег"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "customSources",
                    "customSourceParams": {
                        "source": "Произвольный источник",
                        "medium": "Произвольный канал",
                        "campaign": "Произвольная кампания",
                        "content": "Произвольное объявление",
                        "term": "Произвольная ключевая фраза"
                    }
                },
                {
                    "type": "withoutSource"
                }
            ]
        },

        // Сделка N

        ...

    ]
}

Комментарии через // следует убрать из запроса перед его выполнением.

Параметры запроса

Параметр Формат Обязательно Описание
orders array Да Массив сделок. Можно перечислить до 100 сделок за 1 запрос. Обновление происходит в режиме онлайн.
orders.orderNumber string Да По этому ID мы будем находить у себя уже существующую сделку и обновлять ее. Если не найдем, то выводить ошибку напротив этой сделки в ответе. Обязательно.
orders.status string Нет Актуальный статус.
orders.statusDate string Обязательно, если указан status Дата и время перехода сделки на текущий статус.
orders.updateDate string Да

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

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

orders.revenue string Нет Актуальная выручка.
orders.manager string Нет Актуальное ФИО продавца.
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.

В field должно передаваться значение, добавленное в настройках API ЛК Calltouch. В value можно передаваться только цифры, дробная часть отделяется точкой, максимум 100 символов. Если не указано, то считаем значение поля равной 0.

Формат:

"customFields": [
{"field": "grossprofit", "value": "456.50"},
{"field": "new", "value": "123"}
]

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

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

  • success
  • error
data.orders.error string Отображется причина ошибки обновления

 

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

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