Наверх

API-метод создания сделок

Запрос

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

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

  • Access-Token – API-ключ
  • SiteId – ID ЛК Calltouch

Тело запроса в формате JSON:

{
    "crm": "Название CRM",
    "orders": [

     // Сделка 1
    
        {
            "matching": [
                {
                    "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"
                }
            ],
        "orderNumber": "ID сделки 1 внутри CRM",
        "status": "Название статуса",
        "statusDate": "Дата и время установки текущего статуса сделки",
        "orderDate": "Дата и время создания сделки",
        "revenue": "100000.50",
        "manager": "ФИО продавца",
        "comment": {
            "text": "Комментарий ко сделки"
            },
        "addTags": [
            {"tag": "Тег 1"},
            {"tag": "Тег 2"},
            {"tag": "Тег N"}
            ],
        "addTagsToLead": {
                "tags": [
                    {
                        "tag": "Тег 1"
                    },
                    {
                        "tag": "Тег 2"
                    }
            ],
                "overwrite": true
            },
        "customFields": [
            {"field": "grossprofit", "value": "456.50"},
            {"field": "name", "value": "123"}
            ]
        }

     // Сделка N

        ...
    ]
}

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

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

Параметр Формат Обязательный Описание
crm string Да Одно на все сделки, оно будет отображаться в карточке сделки в ЛК. Любые символы, максимум 30.
orders array Да Массив сделок. Можно перечислить до 100 сделок за 1 запрос. Склейка происходит в режиме онлайн. Результат склеивания будет доступен сразу же в ответе. Обязательно.
orders.matching object Да

Здесь задается приоритет использования разных типов матчинга, по которым сделка будет пытаться склеиться с лидом. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинга завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 20 строк.
orders.matching.type string Обязательно нужно указать хотя бы 1 тип маппинга в приоритете. Тип матчинга. Возможные значения:
  • call – поиск звонка по ID
  • request – поиск заявки по ID
  • callContact – поиск звонка по номеру телефона / дате сделки
  • requestContact – поиск заявки по номеру телефона / почте / дате сделки
  • customSources – не осуществлять поиск лида, а присвоить сделке произвольный источник
  • withoutSource – создать сделку без привязки к какому-либо лиду или источнику.

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

orders.matching

.requestParams

 object Обязательно, если "type": "request" Параметры матчинга заявки по ID

orders.matching

.requestParams.requestId

 integer / string Обязательно, если "type": "request"

Возможные параметры:

  • requestId (integer)
  • requestNumber (string)

orders.matching

.requestParams.tags

 array Необязательно

Если указан список тегов, то найденная заявка перед склейкой будет дополнительно проверена на наличие указанных тегов. И только если у заявки будут эти теги, то сделка будет к ней прикреплена. Иначе сделка не прикрепляется к заявке, а матчинг переключается на следующий тип в приоритете.

Фильтрация по тегам может передаваться вместе с типами call, request, callContact и requestContact.

orders.matching

.requestParams.tagsLogic

 string Обязательно, если указан параметр tags и в нем передается более 1 тега Логические условие между тегами. Возможные значения: and (у заявки должны быть все перечисленные теги) или or (у заявки должен быть хотя бы один из перечисленных тегов).

orders.matching

.callParams

 object Обязательно, если "type": "call" Параметры матчинга звонка по ID

orders.matching

.callParams.callId

 integer / string Обязательно, если "type": "call"

Возможные параметры:

  • callId (integer)
  • callReferenceId (string)
  • sipCallId (string)

orders.matching

.callParams.tags

 array Необязательно Аналогично описанию из блока requestParams

orders.matching

.callParams.tagsLogic

 string Обязательно, если указан параметр tags и в нем передается более 1 тега Аналогично описанию из блока requestParams

orders.matching

.requestContactParams

 object Обязательно, если "type": "requestContact" Параметра матчинга заявки по номеру телефона / почте / дате сделки

orders.matching

.requestContactParams

.emails

 array Должен быть передан хотя бы один из параметров – emails или phones или оба. Можно перечислить несколько почт, формат x@x.x, любые символы. Должен быть передан хотя бы один из параметров – emails или phones или оба.

orders.matching

.requestContactParams

.phones

 array

Можно перечислить несколько номеров телефонов. Номера могут быть в любом формате, 71234567890, +71234567890, 8 (123) 456-78-90 и любом другом – мы должны автоматически конвертировать на бэке их в 11-значный формат.

Если переданы и phones и emails, то поиск заявки идет сначала по номерам, если не найдем, то по почтам.

orders.matching

.requestContactParams

.date

 

 string Обязательно, если "type": "requestContact"

Дата и время, относительно которой будет происходить поиск подходящего лида в прошлое на кол-во дней из параметра searchDepth.

orders.matching

.requestContactParams

.tags

 array Необязательно Аналогично описанию из блока requestParams

orders.matching

.requestContactParams

.tagsLogic

 string Обязательно, если указан параметр tags и в нем передается более 1 тега Аналогично описанию из блока requestParams

orders.matching

.requestContactParams

.requestTypeToMatch

 string Обязательно, если "type": "requestContact"

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

  • nearest
    Любая ближайшая заявка
  • nearestUniq
    Уникальная ближайшая заявка
  • nearestTarget
    Целевая ближайшая заявка
  • nearestUniqTarget
    Уникально-целевая ближайшая заявка

orders.matching

.requestContactParams

.searchDepth

 integer Обязательно, если "type": "requestContact" Глубина поиска подходящей заявки от даты лида date, указывается в мин. Возможные значения от 1 до 525600 мин (1 год).

orders.matching

.callContactParams

 object   Параметры матчинга звонка по номеру телефона / дате сделки

orders.matching

.callContactParams

.phones

 array Обязательно, если "type": "callContact" Аналогично описанию из блока requestContactParams

orders.matching

.callContactParams

.date

 

 string Обязательно, если "type": "callContact" Дата и время, относительно которой будет происходить поиск подходящего звонка в прошлое на кол-во дней из параметра searchDepth.

orders.matching

.callContactParams.tags

 array Необязательно Аналогично описанию из блока requestParams

orders.matching

.callContactParams

.tagsLogic

 string Обязательно, если указан параметр tags и в нем передается более 1 тега Аналогично описанию из блока requestParams

orders.matching

.callContactParams

.callTypeToMatch

 string Обязательно, если "type": "callContact" Аналогично описанию из блока requestContactParams

orders.matching

.callContactParams

.searchDepth

 integer Обязательно, если "type": "callContact" Аналогично описанию из блока requestContactParams

orders.matching

.customSourceParams

 object Обязательно, если "type": "customSources" Не осуществлять матчинг сделки, а присвоить сделки произвольный источник

orders.matching

.customSourceParams

.source

 string Обязательно, если "type": "customSources" Произвольный источник

orders.matching

.customSourceParams

.medium

 string Обязательно, если "type": "customSources" Произвольный канал

orders.matching

.customSourceParams

.campaign

 string Обязательно, если "type": "customSources" Произвольная кампания

orders.matching

.customSourceParams

.content

 string Нет Произвольное объявление

orders.matching

.customSourceParams

.term

 string Нет Произвольная ключевая фраза
orders.orderNumber string Да Уникальный ID сделки внутри CRM. Любые символы, максимум 100.
orders.status string Да Название статуса. Любые символы, максимум 100.
orders.statusDate string Да

Дата и время установки текущего статуса сделки.

Формат: dd-mm-yyyy hh:mm:ss.
orders.orderDate string Да

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

Дата и время создания сделки должно быть равно или предшествовать дате и времени установки текущего статуса.
orders.revenue string Нет Выручка со сделки. Только числа, дробная часть отделяется точками. Максимум 100 символов. Если не указано, то считаем выручку равной 0.
orders.manager string Нет ФИО продавца. Любые символы, максимум 100.
orders.comment.text object Нет

Комментарий ко сделке. Любые символы, максимум 1000.

Формат:

"comment": {
"text": "Комментарий ко сделке"
}
orders.addTags.tag array Нет

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

Формат:

"addTags": [
{"tag": "Тег 1"},
{"tag": "Тег 2"},
{"tag": "Тег N"}
]

orders.addTagsToLead

.tags

 array Нет

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

Формат:

"addTagsToLead": {
"tags": [
{
"tag": "Тег 1"
},
{
"tag": "Тег 2"
}
],
"overwrite": true
}

orders.addTagsToLead

.overwrite

 boolean Нет Перезаписывать ли существующие теги у лида или нет. Обязательно, если указывается addTagsToLead.
orders.customFields array Нет

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

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

Формат:

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

 

Ответ

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

{
    "meta": [],
    "data": {
        "orders": [
            {
                "orderNumber": "UdvPC9bBjjLnEJ9R",
                "calltouchOrderId": 2396375,
                "matchedType": "request",
                "created": true,
                "callInfo": null,
                "requestInfo": {
                    "requestId": 1257513,
                    "requestNumber": "1257513"
                },
                "customSources": null,
                "error": null
            }
        ]
    }
}

Если API-токен не указан, то матчинг не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "message": "Ошибка доступа"
    }
}

Если API-токен указан не верно, то матчинг не выполняется и выводится ошибка:

{
    "message": "Access token не найден"
}

 

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

Параметр Формат Описание
data.orders.orderNumber string Переданный ID сделки из внешний CRM в запросе на создание.
data.orders.calltouchOrderId string ID сделки в Calltouch. Может быть null, если created=false.
data.orders.matchedType string

Тип матчинга из параметра matching API-запроса на создание сделки, по которому сделка склеилась с лидом. Если сделка не склеилась со сделкой и тип withoutSource не был передан, то отображается значение null.
data.orders.created boolean

Флаг создания сделки. Возможные значения:

  • true
  • false

Создание и склеивание – разные процессы, т.к. сделка может быть создана и без связи с лидом.
data.orders.callInfo object

Если сделка склеилась со звонком, то блок callInfo не пустой.
data.orders.callInfo.callId string ID звонка в Calltouch
data.orders.callInfo.callReferenceId string ID звонка из API-метода импорта звонков, может быть null
data.orders.callInfo.sipCallId string ID звонка с АТС
data.orders.requestInfo object Если сделка склеилась с заявкой, то блок requestInfo не пустой
data.orders.requestInfo.requestId string ID заявки в Calltouch
data.orders.requestInfo.requestNumber string ID заявки, переданный из формы сайта
data.orders.customSources object

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

Если сделка не склеилась ни со звонком, ни с заявкой, и у нее не было указаны произвольный источники, то отображается null.
data.orders.customSources.source string Произвольный источник
data.orders.customSources.medium string Произвольный канал
data.orders.customSources.campaign string Произвольная кампания
data.orders.customSources.content string Произвольное объявление
data.orders.customSources.term string Произвольная ключевая фраза
data.orders.error string Отображется причина ошибки маппинга

 

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

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