Импорт заявок

Читать 8

Описание

В статье описан API-метод импорта заявок.

Запрос

POST: 

https://api.calltouch.ru/lead-service/v1/api/request/create

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

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

Пример тела запроса

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

{
    "requests":
        [
        
         // Заявка 1
        
            {
                "requestNumber": "Уникальный ID заявки с формы на сайте",
                "subject": "Название формы",
                "requestUrl": "Адрес страницы, с которой отправлена заявка",
                "requestDate": "Дата и время отправки заявки",
                "sessionId": "ID сессии Calltouch",
                "phoneNumber": "Номер телефона клиента",
                "email": "Почта клиента",
                "fio": "ФИО пользователя",
                "comment": {
                    "text": "Комментарий к заявке"
                },
                "addTags": [
                    {"tag": "Тег 1"},
                    {"tag": "Тег 2"},
                    {"tag": "Тег N"}
                ],
                "manager": "Менеджер",
                "customSources": {
                    "source": "Произвольный источник",
                    "medium": "Произвольный канал",
                    "campaign": "Произвольная кампания",
                    "content": "Произвольное объявление",
                    "term": "Произвольная ключевая фраза"
                },
                "customFields": [
                    {"field": "name", "value": "Вася"},
                    {"field": "birthday", "value": "1990-01-01"}
                ]
            }
        
            // Заявка N
            
            ...
        ]
}

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

Параметр Формат Обязательный Описание
requests array Да Массив заявок. Можно перечислить до 100 заявок за 1 запрос. Импорт происходит в режиме онлайн. Результат импорта будет доступен сразу в ответе. Обязательно.
requests.requestNumber string Да Уникальный ID заявки с формы на сайте. Любые символы, максимум 100.
requests.subject string Нет Название формы. Любые символы, максимум 100.
requests.requestUrl string Нет Адрес страницы, с которой отправлена заявка. Любые символы, максимум 1000.
requests.requestDate string Да Дата и время отправки заявки. Формат: dd-mm-yyyy hh:mm:ss.
requests.sessionId string Нет

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

Подробнее о получении sessionId в статье: Получение id сессии Calltouch

requests.phoneNumber string Нет Номер телефона клиента. Номер может быть в любом формате, 71234567890, +71234567890, 8 (123) 456-78-90 и любом другом — он будет автоматически конвертирован в 11-значный формат.
requests.email string Нет Почта клиента. Формат x@x.x, любые символы.
requests.fio string Нет ФИО пользователя. Любые символы, максимум 100.
requests.comment.text string Нет Комментарий к заявке. Любые символы, максимум 1000.
requests.addTags array Нет Добавление тегов к заявке. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Любые символы, максимум 100 в каждом теги. Максимум 100 тегов.
requests.manager string Нет Менеджер, обработавший заявку. Любые символы, максимум 50.
requests.customSources object Нет Произвольные источники заявки. Используются только когда не указан sessionId. Необязательно. Если не указан ни sessionId ни произвольные источники, то заявка создается без источника.

requests.customSources.

source

string Да, если указан customSources. Произвольный источник

requests.customSources.

medium

string Да, если указан customSources. Произвольный канал

requests.customSources.

campaign

string Да, если указан customSources. Произвольная кампания

requests.customSources.

content

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

requests.customSources.

term

string Нет Произвольная ключевая фраза

requests.customFields

array Нет

Данные по пользовательским полям в заявке.

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

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

Формат: 

"customFields": [
     {"field": "name", "value": "Вася"},
     {"field": "birthday", "value": "1990-01-01"}
]

В field передается название пользовательского поля в API, в value передается значение пользовательского поля.

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

Ответ

Если валидация всех параметров прошла успешно, то запускается процесс импорта заявок и в ответ отдается информация по импортированным заявкам.

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

{
    "meta": [],
    "data": {
        "requests": [
            {
                "imported": true,
                "requestNumber": "HG6Z4qxVEoI4ewZ8",
                "calltouchRequestId": 1257831,
                "error": null
            }
        ]
    }
}

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

Параметр Формат Описание
data.requests.imported boolean Флаг импортирована ли заявка или нет
datarequests.requestNumber string ID заявки с сайта
datarequests.calltouchRequestId string ID заявки в Calltouch, может быть null
datarequests.error string Отображается причина ошибки импорта заявок

Типовые ошибки

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

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

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

{

 "meta": [],

 "data": {

 "message": "Ошибка доступа"

 }

}

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

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

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

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

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


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