Читать 17

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


Запрос



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": ["тег1","тег2"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "chat",
                    "chatParams": {
                         "chatId": 3,
                         "tags": ["тег1","тег2"],
                         "tagsLogic": "and"
                    }
                },
                {
                    "type": "leadContact",
                    "leadContactParams": {
                        "emails": ["name@server.com"],
                        "phones": ["79157771122", "+7 (915) 888-11-22"],
                        "date": "Дата и время лида",
                        "tags": ["тег1","тег2"],
                        "tagsLogic": "and",
                        "leadTypeToMatch": "nearestUniq",
                        "searchDepth": 262800,
                        "withChats": true
                    }
                },   
                {
                    "type": "requestContact",
                    "requestContactParams": {
                        "emails": ["name@server.com"],
                        "phones": ["79157771122", "+7 (915) 888-11-22"],
                        "date": "Дата и время заявки",
                        "tags": ["тег1","тег2"],
                        "tagsLogic": "and",
                        "requestTypeToMatch": "nearestUniq",
                        "searchDepth": 262800
                    }
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "date": "Дата и время звонка",
                        "tags": ["тег1","тег2"],
                        "tagsLogic": "and",
                        "callTypeToMatch": "nearestUniq",
                        "searchDepth": 262800
                     }
                },
                {
                    "type": "chatContact",
                    "chatContactParams": {
                         "emails": ["name@server.com"],
                         "phones": ["79157771122", "+7 (915) 888-11-22"],
                         "waPhones": ["79999999999", "+7 (911) 222-33-44"],
                         "tgIds": [123456],
                         "tgUsernames": ["@username", "username"],
                         "vkIds": [123456],
                         "date": "Дата и время чата",
                         "tags": ["тег1","тег2"],
                         "tagsLogic": "and",
                         "chatTypeToMatch": "nearestUniq",
                         "searchDepth": 262800
                    }
               },
                {
                    "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": "ФИО менеджера",
            "leadManager": {
                "manager": "Иван Иванов",
                "overwrite": false
            },
            "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"}
            ],
            "addCustomFieldsToLead": {
                "customFields": [  
                     {"field": "test_field", "value": "test value"}
                ],
                "overwrite": false
            },
            "products": [
                {
                    "name": "Табурет",
                    "price": "500.25",
                    "brand": "ikea",
                    "category": "Столы, стулья",
                    "variant": "Черный",
                    "quantity": 10
                },
                {
                    "name": "Стол",
                    "price": "1500"
                }
            ],
            "orderContacts": {
                "mainContacts": {
                    "fio": "Иван",
                    "phoneNumber": "79000000000",
                    "email": "test@test.ru",
                    "waPhone": "79000000000",
                    "tgId": "1234567",
                    "tgUsername": "tguser1",
                    "vkId": "1234567"
                },
                "otherContacts": {
                    "phoneNumber": ["79000000001","79000000002"],
                    "email": ["test2@test.ru","test3@test.ru"],
                    "waPhone": ["79000000001","79000000002"],
                    "tgId": ["7654321"],
                    "tgUsername": ["tguser2"],
                    "vkId": ["7654321"]
                }
            }
        }

     // Сделка N

        ...
    ]
}


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

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

Здесь задается приоритет использования разных типов матчинга, по которым сделка будет пытаться склеиться с лидом. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинг завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 20 строк.

orders.matching.type string Обязательно нужно указать хотя бы 1 тип матчинга в приоритете. Тип матчинга у сделки. Возможные значения:
  • leadContact — поиск лида (звонка или заявки) по номеру телефона / почте / дате;
  • callContact — поиск звонка по номеру телефона / дате;
  • requestContact — поиск заявки по номеру телефона / почте / дате;
  • chatContact — поиск чата по номеру телефона / почте / телефону Whatsapp / ID Телеграм / username Телеграм / ID VK / дате;
  • call — поиск звонка по ID;
  • request — поиск заявки по ID;
  • chat — поиск чата по ID;
  • session — поиск сессии по ID;
  • customSources — не осуществлять поиск лида, а присвоить сделке произвольный источник;
  • withoutSource — создать сделку без привязки к какому-либо лиду или источнику.

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

Подробное описание полей в объекте matching в этой статье.

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.orderLink string Нет Ссылка на сделку в CRM. Любые символы, максимум 256. Значение данного поля проходит валидацию на соответствие стандарту URL (наличие протокола (http и https), наличие доменов первого, второго, третьего и т.д. уровней (или ip-адрес)). В отчетах личного кабинета ссылка помещается в атрибут href для внешнего идентификатора сделки.
orders.orderName string Нет

Название сделки в CRM. Любые символы, максимум 200. 

orders.comment.text object Нет

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

Формат: 

"comment": {
   "text": "Комментарий к сделке"
}
orders.manager string Нет ФИО продавца. Любые символы, максимум 50.
orders.leadManager
.manager  		string Нет

Добавление менеджера к лиду, к которому приклеивается сделка. Любые символы, максимум 50. Если сделка не склеивается ни с каким лидом, то менеджер не добавится.

Формат: 

"leadManager": {
   "manager": "Иван Иванов",
   "overwrite": false
}
orders.leadManager
.overwrite
 boolean Нет

Перезаписываем ли существующего менеджера у лида, если он уже есть в лиде. Возможные значения:

  • false — не перезаписывем;
  • true — перезаписываем.

Если не указан, по умолчанию false.

orders.addTags 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 Нет

Перезаписываем ли существующие у лида теги, или добавляем новые теги к существующим. Возможные значения:

  • false — Добавляем;
  • true — Перезаписываем.

Если не указан, по умолчанию false.

orders.customFields array Нет

Пользовательские поля API в сделках.

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

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

Формат: 

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

Максимум 20 пользовательских полей.

orders.addCustomFieldsToLead
.customFields 		array Нет

Добавление пользовательских полей к лиду, с которым была склеена сделка. 

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

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

Если в рамках создания или обновления сделки она не была склеена с лидом - то содержимое addCustomFieldsToLead просто игнорируется.

Формат: 

"addCustomFieldsToLead": {
     "customFields": [  
        {"field": "test_field", "value": "test value"},
        {"field": "num", "value": 123.4}
   ],
   "overwrite": false
}

Максимум 20 пользовательских полей.

orders.addCustomFieldsToLead
.overwrite 		boolean Нет Перезаписывать ли существующее значение пользовательского поля у лида или нет, при его наличии в лиде. Возможные значения:
  • false — Не перезаписывать.
  • true — Перезаписывать.
Если параметр не указан - по умолчанию false.
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 символов.

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

orderContacts object Нет

Объект с контактами из сделки

orderContacts.
mainContacts 		object Нет Объект с основными контактами из сделки
orderContacts.
mainContacts.
fio 		string Да ФИО из сделки
orderContacts.
mainContacts.
phoneNumber 		string

Да, если передан .mainContacts

Обязательно передать хотябы 1 из контактов: phoneNumber, email, waPhone, tgId, tgUsername или vkId

Основной номер телефона из сделки, в формате 7XXXXXXXXXX
orderContacts.
mainContacts.
email 		string Основной email из сделки
orderContacts.
mainContacts.
waPhone 		string Основной номер телефона из Whatsapp, в формате 7XXXXXXXXXX
orderContacts.
mainContacts.
tgId 		string Основной ID Telegram. Цифры, максимум 20.
orderContacts.
mainContacts.
tgUsername 		string Основное имя пользователя Telegram. Формат: @username, username. Латинские буквы a-z, цифры 0-9, и нижнее подчеркивание. Минимум 3 символа. Максимальная длина 100 символов (без учета @).
orderContacts.
mainContacts.
vkId 		string Основной ID Vkontakte. Цифры, максимум 20.
orderContacts.
otherContacts 		object Нет Объект с дополнительными контактами сделки
orderContacts.
otherContacts.
phoneNumber 		array Нет Дополнительные номера телефона из сделки. В формате 7XXXXXXXXXX. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные телефоны, если не был передан основной телефон.
orderContacts.
otherContacts.
email 		array Нет Дополнительные Email из сделки. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные Email, если не был передан основной Email.
orderContacts.
otherContacts.
waPhone 		array Нет Дополнительные номера телефонов из Whatsapp, в формате 7XXXXXXXXXX. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные waPhone, если не был передан основной waPhone.
orderContacts.
otherContacts.
tgId 		array Нет Дополнительные ID Telegram. Цифры, максимум 20 в одном ID. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные tgId, если не был передан основной tgId.
orderContacts.
otherContacts.
tgUsername 		array Нет Дополнительные имя пользователя Telegram. Формат: @username, username. Латинские буквы a-z, цифры 0-9, и нижнее подчеркивание. Минимум 3 символа. Максимальная длина 100 символов в одном tgUsername (без учета @). Массив, максимум 3 штуки. 
Нельзя передавать дополнительные tgUsername, если не был передан основной tgUsername.
orderContacts.
otherContacts.
vkId 		array Нет Дополнительные ID Vkontakte. Цифры, максимум 20 в одном ID. Массив, максимум 3 штуки. 
Нельзя передавать дополнительные vkId, если не был передан основной vkId.

Ответ



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

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

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


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

Параметр Формат Описание
data.orders.orderNumber string Переданный ID сделки из внешний CRM в запросе на создание.
data.orders.calltouchOrderId integer 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 integer ID заявки в Calltouch
data.orders.requestInfo.requestNumber string ID заявки, переданный из формы сайта
data.orders.chatInfo object Если сделка склеилась с чатом, то блок chatInfo не пустой
data.orders.chatInfo.chatId integer ID чата в Calltouch
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": "Значение даты и времени недопустимо."
                }
            ]
        }
    }
}


Если в запросе указаны некорректные авторизационные данные — то выводится ошибка. Список типовых ответов при запросах с некорректными авторизационными данными, или некорректными данными в теле API запроса вы можете посмотреть в этой статье.

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



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

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

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

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

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


Система баллов API Calltouch



Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).

Не нашли решение проблемы?
Заполните форму, и мы вам поможем.
Похожие статьи
Недавно просмoтренные