API-метод создания сделок – Calltouch - справочный центр

Запрос

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"],
                        "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"
                }
            ],
        "orderNumber": "ID сделки 1 внутри CRM",
        "funnel": "Название воронки",
        "status": "Название статуса",
        "statusDate": "Дата и время установки текущего статуса сделки",
        "orderDate": "Дата и время создания сделки",
        "currency": "rub",
        "revenue": "100000.50",
        "margin": "100.50",
        "orderLink": "https://site.ru/crm/deal/123/",
        "orderName": "Название сделки",
        "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"}
            ],
        "products": [
            {
                "name": "Табурет",
                "price": "500.25",
                "brand": "ikea",
                "category": "Столы, стулья",
                "variant": "Черный",
                "quantity": 10
            },
            {
                "name": "Стол",
                "price": "1500"
            }]
        }

// Сделка N

        ...
    ]
}

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

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

Параметр	Формат	Обязательный	Описание
crm	string	Да	Одно на все сделки, оно будет отображаться в карточке сделки в ЛК. Любые символы, максимум 30.
orders	array	Да	Массив сделок. Можно перечислить до 100 сделок за 1 запрос. Склейка происходит в режиме онлайн. Результат склеивания будет доступен сразу же в ответе. Обязательно.
orders.matching	array	Да	Здесь задается приоритет использования разных типов матчинга, по которым сделка будет пытаться склеиться с лидом. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинга завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 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	Должен быть передан хотя бы один из параметров – phones, md5Phones или emails. Допустима передача сразу нескольких параметров, поиск будет идти по приоритету: поиск по phones. Если не нашли, то поиск по md5Phones. Если не нашли, то поиск по emails.	Можно перечислить несколько почт (до 5 в одном параметре), формат x@x.x, любые символы.
orders.matching .requestContactParams .phones	array		Можно перечислить несколько номеров телефонов (до 5 в одном параметре). Номера могут быть в любом формате, 71234567890, +71234567890, 8 (123) 456-78-90 и любом другом – мы должны автоматически конвертировать на бэке их в 11-значный формат.
orders.matching .requestContactParams .md5Phones	array		Можно перечислить несколько md5-хэшей номеров телефонов. Хэши требуется передавать от номеров в формате +74953080100 (с плюсом вначале, далее номер в федеральном формате). При передаче хэшей от других форматов номеров телефонов заведомо не будет связи сделки с лидом.
orders.matching .requestContactParams .date	string	Обязательно, если "type": "requestContact"	Дата и время, относительно которой будет происходить поиск подходящей заявки в прошлое на кол-во минут из параметра searchDepth. Формат: dd-mm-yyyy hh:mm:ss.
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. Формат: dd-mm-yyyy hh:mm:ss.
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"	Произвольный источник, максимум 100 символов или меньше.
orders.matching .customSourceParams .medium	string	Обязательно, если "type": "customSources"	Произвольный канал, максимум 100 символов или меньше.
orders.matching .customSourceParams .campaign	string	Обязательно, если "type": "customSources"	Произвольная кампания, максимум 100 символов или меньше.
orders.matching .customSourceParams .content	string	Нет	Произвольное объявление, максимум 100 символов или меньше.
orders.matching .customSourceParams .term	string	Нет	Произвольная ключевая фраза, максимум 100 символов или меньше.
orders.orderNumber	string	Да	Уникальный ID сделки внутри CRM. Любые символы, максимум 100.
orders.funnel	string	Нет	Название воронки. Любые символы, максимум 200. Если не указано, то сделка помещается в служебную воронку "Без воронки".
orders.status	string	Да	Название статуса. Любые символы, максимум 100.
orders.statusDate	string	Да	Дата и время установки текущего статуса сделки. Формат: dd-mm-yyyy hh:mm:ss.
orders.orderDate	string	Да	Дата и время создания сделки. Формат: dd-mm-yyyy hh:mm:ss. Дата и время создания сделки должно быть равно или предшествовать дате и времени установки текущего статуса.
orders.currency	string	Нет	Валюта сделки. Возможные значения: "rub", "usd". Если не указано, то используем "rub".
orders.revenue	string	Нет	Выручка со сделки. Только числа, дробная часть отделяется точками. Максимум 100 символов. Если не указано, то считаем выручку равной 0.
orders.margin	string	Нет	Маржинальность сделки. Только числа, дробная часть отделяется точками. Максимум 14 символов.
orders.manager	string	Нет	ФИО продавца. Любые символы, максимум 100.
orders.orderLink	string	Нет	Ссылка на сделку в CRM. Любые символы, максимум 256. Значение данного поля проходит валидацию на соответствие стандарту URL (наличие протокола (http и https), наличие доменов первого, второго, третьего и т.д. уровней (или ip-адрес)). В отчетах личного кабинета ссылка помещается в атрибут href для внешнего идентификатора сделки.
orders.orderName	string	Нет	Название сделки в CRM. Любые символы, максимум 200.
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"} ]
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 символов. Не может быть равно нулю.

Ответ

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

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