Сделки
18 минут

Создание сделок

Запрос

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": 262800
                    }
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"],
                        "date": "Дата и время звонка",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "callTypeToMatch": "nearestUniq",
                        "searchDepth": 262800
                        }
                },
                {
                    "type": "call",
                    "callParams": {
                        "callId": 2,
                        "tags": ["тег"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "session",
                    "sessionParams": {
                        "sessionId": ["1234567"]
                    }                        
                },
                {
                    "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 – поиск заявки по номеру телефона / почте / дате сделки
  • session – поиск сессии по ID
  • 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 Логические условие между тегами. Возможные значения: 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
.sessionParams 		object Обязательно, если "type": "session" Параметры матчинга сессии по ID
orders.matching
.requestParams.sessionId 		string Обязательно, если "type": "session" Значение sessionID

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.

Поля в ЛК Calltouch могут быть или числовыми, или текстовыми. В числовые можно передавать только цифры, дробная часть отделяется точкой, максимум 100 символов. Если не указано, то считаем значение поля равной 0. В текстовые поля допустимо передавать любые символы, максимум 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 символов.

Не может быть равно нулю. 

Ответ

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

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

Добавление пользовательских полей

В описанном выше методе вы можете использовать пользовательские поля для того, чтобы передать дополнительную информацию из вашей CRM-системы в личный кабинет Calltouch. Для того, чтобы создать такое поле в вашем личном кабинете, необходимо зайти в раздел «Интеграции –> API и Webhooks»:

 


  • Название поля в ЛК. Это название будет отображаться в настройках  пользовательских метрик. Любые символы, максимум 100.
  • Название поля в API. Это поле будет доступно для использования в API-методах создания и обновления сделок. Только английские буквы и символы дефиса «-» или подчеркивания «_», максимум 100.
  • Формат поля. Текстовый формат может быть использован в качестве фильтров сделок в пользовательских метриках. Числовые значения используются в качестве показателей.


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

Например, как в ЛК Calltouch увидеть валовую прибыль? Теперь очень просто. Добавьте поле "Себестоимость" в API и выгружайте в него данные из CRM. А чтобы посчитать валовую прибыль, просто создайте пользовательскую метрику, задав в ней формулу "Выручка со сделок - Себестоимость". Эта метрика станет доступной в любом отчете Calltouch.

advice_ver2.png При удалении пользовательского поля, все данные, переданные в нем, будут так же удалены.


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