Наверх

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",
            "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"}
                ],
            "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": "nearestUniq",
                        "searchDepth": 120
                    }
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"],
                        "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.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.

В 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": "Значение даты и времени недопустимо."
                }
            ]
        }
    }
}