API-методы создания скоринга и экспорта результатов
Описание
В статье описаны методы создания скоринга и экспорта результатов. Каждый успешный запрос создает и запускает в интерфейсе проекта скоринг.
Создание скоринга
Запрос
Пример запроса для стандартного токена и мультитокена
https://api.calltouch.ru/scoring-service/v1/api/calltouch-scoring/create
Пример запроса для мультитокена
https://api.calltouch.ru/scoring-service/v1/api/multisite/calltouch-scoring/create
HTTP-заголовки:
Заголовок | Описание |
Content-Type: application/json | Тело запросов/ответов будет в формате JSON. |
Access-Token: <token> |
Авторизация через стандартный или мульти- API-токен Calltouch |
или
|
Или
|
Метод: POST
Тело запроса в формате JSON.
Параметры запроса
Параметр | Формат | Обязателен | Описание | Валидация |
syncType | string | Да |
Формат синхронизации по клиентской базе. Если syncType=raw, то:
Если syncType=md5, то:
Если syncType=callIds, то:
|
Валидные значения:
|
clients[{}] | массив объектов | Да, syncType=raw или syncType=md5 |
Массив клиентов, по которым требуется проверить степени интереса. clients: [ {phone: '74953080100'}, {phone: '74953080122', email: 'mail@mail.ru'}] |
Валидные значения:
|
clients[n].phone | string | Да, если в объекте нет email | Номер телефона клиента. Обязательно, если по клиенту не передана почта. |
Валидные значения:
|
clients[n].email | string | Да, если в объекте нет phone | Почта клиента. Обязательно, если по клиенту не передан номер телефона. |
Валидные значения:
|
callIds | массив integer'ов | Да, если syncType=callIds |
В поле callIds передавать идентификаторы звонков из личного кабинета Calltouch. Из переданных звонков будут взяты номера звонивших для скоринга. |
Валидные значения:
|
profileClient | объект | Нет |
Пол и возраст. На основе указанного профиля будет скорректирована итоговая оценка. Если не передано, то оценки по профилю не корректируются. |
Валидные значения:
|
profileClient.gender | объект | Да, если передано profileClient |
Пол, можно указывать одно из значений:
|
Валидные значения:
|
profileClient.age | объект | Да, если передано profileClient |
Возраст в диапазоне. Можно передать один из диапазонов:
|
Валидные значения:
|
periodOfInterest | integer | Да |
Количество дней в прошлом от момента создания запроса, на котором будут проверены активности клиентов. |
Валидные значения:
|
industriesOfInterest | массив string'ов | Да |
Отрасли, к которым необходимо проверить интерес:
Список отраслей
|
Валидные значения:
|
projectsForVerification | массив integer'ов |
Да |
Список ваших проектов, по касаниям из которых будет скорректирован итоговый уровень интереса. |
Валидные значения:
|
data.geoOfInterest | объект | Нет | Выбор стран, областей и городов, в которых проверять проявленный интерес. Например, в случае, когда ваша компания представлена в нескольких регионах и вам важно видеть интерес в конкретном регионе. |
Валидные значения:
|
data.geoOfInterest.cities | массив integer'ов |
Нет |
Города, в которых выявлен интерес. |
Валидные значения:
|
data.geoOfInterest.regions | массив integer'ов | Нет | Области (регионы), в которых выявлен интерес. |
Валидные значения:
|
data.geoOfInterest.countries | массив integer'ов |
Нет |
Страны, в которых выявлен интерес. |
Валидные значения:
|
Пример
{ "syncType": "callIds/md5/raw", "callIds": [123,213,312], // параметр callIds использовать при syncType=callIds "clients": [ // параметр clients использовать при syncType=md5 или syncType=raw { "phone": "4fec00b25336e719d4a0b255ea5aa0f5", // при syncType=md5 использовать хеширование от номеров в формате +79хххххххххх, т.е. в начале символ +, код страны (семерка) и телефон, только цифры "email": "3b5856c3df2613553b8d0e781be69380" // при syncType=md5 использовать хеширование почт }, { "phone": "+7 920 000 22-22" // при syncType=raw номер телефона можно передавать по любой маске }], "geoOfInterest": { "cities": [12,223,4145], "regions": [1123,2234,44145], "countries": [22,333,213445] }, "periodOfInterest": 10, "profileClient": { "age": "all", "gender": "all" }, "industriesOfInterest": ["Квартиры и апартаменты - Эконом и Стандарт"], "projectsForVerification": [303,3034] }
Ответ
Успешный ответ при выполнении всех условий:
- авторизация пройдена;
- валидный JSON;
- услуга Скоринг включена;
- валидация входящих параметров пройдена.
Успешный ответ содержит информацию об идентификаторе скоринга. Если запрос на создание скоринга по какой-либо причине завершен ошибкой, то ID скоринга не будет выдан.
Пример ответа
{ "data": { "scoringId": 123 } }
Параметры ответа
Параметр | Формат | Описание |
data.scoringId | integer | Идентификатор запроса, по которому можно будет узнать статус и получить результаты скоринга. |
Типовые ошибки
Ответ с ошибкой в случаях:
- ошибка авторизации;
- невалидный JSON;
- валидация хотя бы по одному из входящих параметров не пройдена;
- услуга Скоринг выключена.
Ошибочный ответ содержит информацию о типе ошибки и пояснения к ней.
Отсутствие доступа к методу
{ "meta": [], "data": { "message": "Пользователь {party_name} не имеет доступа к данному методу API" } }
Ошибка авторизации
{ "message": "Invalid credentials." }
Услуга Скоринг выключена
{ "meta": [], "data": { "message": "Услуга «Скоринг клиентов» выключена на проекте ID {site_id} {site_name}" } }
Ошибка формата тела запроса
{ "meta": [], "data": { "type": "apiError", "apiErrorData": { "errorCode": 1, "errorMessage": "Синтаксическая ошибка JSON в запросе или запрос пустой", "errorDescription": null }, "validationErrorData": null } }
Ошибка в содержимом параметров
{ "meta": [], "data": { "type": "validationError", "apiErrorData": null, "validationErrorData": { "violations": [ { "fieldPath": "periodOfInterest", "message": "Значение должно быть между \"5\" и \"45\"." }, { "fieldPath": "clients", "message": "Эта коллекция должна содержать больше или равно 100 элементов." }, { "fieldPath": "callIds", "message": "Эта коллекция должна содержать больше или равно 100 элементов." }, { "fieldPath": "syncType", "message": "Выбранное Вами значение недопустимо." }, { "fieldPath": "industriesOfInterest", "message": "Переданы недопустимые интересы для проекта. Список доступных сфер представлен в справочном центре - https://www.calltouch.ru/support/skoring-klientov/" }, { "fieldPath": "geoOfInterest.cities", "message": "Значение не найдено в справочнике. Список доступных стран, регионов и городов представлен в справочном центре - https://www.calltouch.ru/support/skoring-klientov/” } ] } } }
Отсутствие обязательных полей в запросе
{ "meta": [], "data": { "type": "validationError", "apiErrorData": null, "validationErrorData": { "violations": [ { "fieldPath": "syncType", "message": "Значение не должно быть пустым." } ] } } }
Результаты скоринга
Запрос
https://api.calltouch.ru/scoring-service/v1/api/calltouch-scoring/123/result
Где 123 — scoringId, полученный в ответе на создание скоринга.
HTTP-заголовки:
Заголовок | Описание |
Content-Type: application/json | Тело запросов/ответов будет в формате JSON. |
Access-Token: <token> | Авторизация через стандартный или мульти-API-токен Calltouch |
SiteId: <site_id> |
Идентификатор проекта в Calltouch, в котором создан скоринг и по которому необходимо получить результаты. Его можно получить в разделе
Интеграции /
Отправка данных во внешние системы => API и WebhooksI => ID личного кабинета. |
Метод: GET
В запросе передается идентификатор запроса, полученный из ответа на создание скоринга.
Ответ
В ответе будут ранее отправленные данные в запросе создания скоринга, поверх которых добавится параметр status, в котором будут актуальные статусы импортов. Если status=Завершен, то в ответ добавляется массив resultOfScoring.
{ "meta": [], "data": { "scoringId": 123, "status": "Завершен", "syncType": "callIds/md5/raw", "callIds": [123,213,312], // параметр callIds передается при syncType=callIds "clients": [ // параметр clients передается при syncType=md5 или syncType=raw { "phone": "4fec00b25336e719d4a0b255ea5aa0f5", // при syncType=md5 указывается хешированый номер от формат +79хххххххххх, т.е. в начале символ +, код страны (семерка) и телефон, только цифры "email": "3b5856c3df2613553b8d0e781be69380" // при syncType=md5 указывается хешированая почта }, { "phone": "+7 920 000 22-22" // при syncType=raw указывается номер телефона в явном виде }], "periodOfInterest": 10, "geoOfInterest": { "cities": [10683,16387], "regions": [463,110], "countries": [112,246] }, "profileClient": { "age": "all", "gender": "all" }, "industriesOfInterest": ["Квартиры и апартаменты - Эконом и Стандарт"], "projectsForVerification": [303,3034] "resultOfScoring":[ { "phone": "4fec00b25336e719d4a0b255ea5aa0f5", "email": "3b5856c3df2613553b8d0e781be69380", "levelOfInterest": "high" }, { "phone": "79200002222", "levelOfInterest": "middle" }, { "email": "mail@example.ru", "levelOfInterest": "low" }, { "callId": 342, "levelOfInterest": "none" } ] } }
Параметры ответа
Параметр | Формат | Описание |
data.scoringId |
integer |
Идентификатор запроса, по которому можно будет узнать статус и получить результаты скоринга. |
data.status |
string |
Статус скоринга. Возможные значения:
|
data.syncType |
string |
Формат синхронизации по клиентской базе. Возможные значения:
|
data.callIds |
массив integer’ов |
Список идентификаторов звонков, переданных при создании скоринга. Параметр callIds передается при syncType=callIds. |
data.clients |
массив объектов |
Список номеров и почт клиентов, переданных для выявления интереса при создании скоринга. Параметр clients передается при syncType=md5 или syncType=raw. |
data.clients.[n].phone |
string |
Номер телефона клиента в федеральном или шифрованном формате, зависит от data.syncType. Может отсутствовать, если номер по клиенту не передавался при создании скоринга. |
data.clients.[n].email |
string |
Почта клиента в обычном или шифрованном формате, зависит от data.syncType. Может отсутствовать, если почта по клиенту не передавалась при создании скоринга. |
data.geoOfInterest | объект | Выбор стран, областей и городов, в которых проверять проявленный интерес. Например, в случае, когда ваша компания представлена в нескольких регионах и вам важно видеть интерес в конкретном регионе. |
data.geoOfInterest.cities | массив integer'ов | Города, в которых выявлен интерес. |
data.geoOfInterest.regions | массив integer'ов | Области (регионы), в которых выявлен интерес. |
data.geoOfInterest.countries | массив integer'ов | Страны, в которых выявлен интерес. |
data.periodOfInterest |
Integer |
Период проявления интереса в днях. |
data.profileClient |
объект |
Пол и возраст. На основе указанного профиля будет скорректирована итоговая оценка. Если не передано, то оценки по профилю не корректируются. |
data.profileClient.gender |
string |
Пол. |
data.profileClient.age |
string |
Возраст в диапазоне. |
data.projectsForVerification |
массив integer'ов |
Список ваших проектов, по касаниям из которых будет скорректирован итоговый уровень интереса. |
data.industriesOfInterest |
массив string'ов |
Интерес, который проверяется у клиентов. |
data.resultOfScoring |
массив объектов |
Результаты скоринга, по каждому клиенту или ID звонка указывается уровень интереса. Объект доступен, если data.status=”Завершен”. |
data.resultOfScoring.[n].phone |
string |
Номер телефона клиента в федеральном или шифрованном формате, по которому указан интерес. Присутствует в случае data.syncType=”raw” и data.syncType=”md5”. |
data.resultOfScoring.[n].email |
string |
Почта клиента в обычном или шифрованном формате, по которому указан интерес. Присутствует в случае data.syncType=”raw” и data.syncType=”md5”. |
data.resultOfScoring.[n].callId |
integer |
ID звонка, из которого будет взят номер телефона клиента. Присутствует в случае data.syncType=”callIds”. |
data.resultOfScoring.[n].levelOfInterest |
string |
Уровень интереса. Возможные значения:
|
Типовые ошибки
Ответ с ошибкой в случаях:
- ошибка авторизации;
- нет доступа к запрошенному ID скоринга;
- услуга Скоринг выключена.
Ошибочный ответ содержит информацию о типе ошибки и пояснения к ней.
Отсутствие доступа к методу
{ "meta": [], "data": { "message": "Пользователь {party_name} не имеет доступа к данному методу API" } }
Ошибка авторизации
{ "message": "Invalid credentials." }
Услуга Скоринг выключена
{ "meta": [], "data": { "message": "Услуга «Скоринг клиентов» выключена на проекте ID {site_id} {site_name}" } }
Передан несуществующий ID скоринга
{ "meta": [], "data": { "message": "Скоринг не найден" } }
Отсутствие доступа к ID скоринга
{ "meta": [], "data": { "message": "У проекта 123 нет доступа к данному скорингу" } }
Доступ к методу
В настройках прав доступа прав доступов есть чекбокс "API-методы для управления Скорингом", на редактирование и чтение. Подробнее о настройках пользователей и прав доступа смотрите в статье: Управление правами доступа.
- Если созданному пользователю выдан доступ на чтение, то он сможет использовать метод
https://api.calltouch.ru/scoring-service/v1/api/calltouch-scoring/123/result
- Если выдан доступ на чтение и редактирование, то сможет использовать методы
https://api.calltouch.ru/scoring-service/v1/api/calltouch-scoring/123/result
https://api.calltouch.ru/scoring-service/v1/api/calltouch-scoring/create
- Если доступ не выдан, то пользоваться API-методами для работы со скорингами нельзя.
Система баллов API Calltouch
Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.
Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)