API-методы создания скоринга и экспорта результатов

Читать 21

Создание скоринга

Запрос

Для стандартного токена и мультитокена:  

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
  • SiteId: <site_id>

или 

  • SiteIds: <site_id1>,<site_id2>,<site_idn>
  • Идентификатор проекта в Calltouch. Его можно получить в разделе  Интеграции / Отправка данных во внешние системы  => API и WebhooksI =>  ID личного кабинета.

Или

  • Список проектов, по которым необходимо найти получить клиентскую базу на основе callIds. Скоринг будет создан в том проекте, который указан первый в списке.

Метод: POST

Формат запроса: JSON

Параметры:

 Параметр Формат  Обязателен  Описание  Валидация 
syncType string Да

Формат синхронизации по клиентской базе.

Если syncType=raw, то:

  • в поле clients[n].phone номера в федеральном формате с любой маской - 8 902 234 32-23, 79209992233 и т.д.
  • в поле clients[n].email ожидаются почты в явном виде.

Если syncType=md5, то:

  • в поле clients[n].phone ожидаются зашифрованные алгоритмом MD5 номера в формате +74953080100 (т.е. с плюсом в начале и семеркой, не цифры недопустимы);
  • в поле clients[n].email ожидаются зашифрованные алгоритмом MD5 почты.

Если syncType=callIds, то:

  • в поле callIds передавать идентификаторы звонков из личного кабинета Calltouch. Из переданных звонков будут взяты номера звонивших для скоринга.

Валидные значения:

  • raw;
  • md5;
  • callIds.
clients[{}] массив объектов Да, syncType=raw или syncType=md5

Массив клиентов, по которым требуется проверить степени интереса.

clients: [

{phone: '74953080100'},

{phone: '74953080122', email: 'mail@mail.ru'}]

Валидные значения:

  • Если передано, то не пустое.
clients[n].phone string Да, если в объекте нет email Номер телефона клиента. Обязательно, если по клиенту не передана почта.

Валидные значения:

  • Тип значения - string;
Если syncType=raw, то соответствует формату любому формату номера с кодом:
  • 74953080100;
  • 84953080100;
  • +7 (495) 308-01-00;
  • т.п.
Если syncType=md5, то зашифрованные алгоритмом MD5 номера в формате +74953080100 (т.е. с плюсом в начале и семеркой, не цифры недопустимы).
clients[n].email string Да, если в объекте нет phone Почта клиента. Обязательно, если по клиенту не передан номер телефона.

Валидные значения:

  • Тип значения - string;
  • Наличие символа @ и домена первого уровня;
  • Если syncType=raw, то почты клиентов в явном виде;
  • Если syncType=md5, то зашифрованные алгоритмом MD5 почты.
callIds массив integer'ов Да, если syncType=callIds

В поле callIds передавать идентификаторы звонков из личного кабинета Calltouch. Из переданных звонков будут взяты номера звонивших для скоринга.

Валидные значения:

  • если передано, то не пустое;
  • каждый элемент массива - integer.
profileClient объект Нет

Пол и возраст. На основе указанного профиля будет скорректирована итоговая оценка. Если не передано, то оценки по профилю не корректируются.

Валидные значения:

  • Если передано, то наличие параметров gender и age.
profileClient.gender объект Да, если передано profileClient

Пол, можно указывать одно из значений:

  • Мужчины;
  • Женщины;
  • Все.

Валидные значения:

  • male;
  • female;
  • all.
profileClient.age объект Да, если передано profileClient

Возраст в диапазоне. Можно передать один из диапазонов:

  • 18-24;
  • 25-34;
  • 35-44;
  • 45-54;
  • 55-64;
  • 65+;
  • Все.

Валидные значения:

  • 18-24;
  • 25-34;
  • 35-44;
  • 45-54;
  • 55-64;
  • 65+;
  • all.
periodOfInterest integer Да

Количество дней в прошлом от момента создания запроса, на котором будут проверены активности клиентов.


Валидные значения:

  • Тип значения - integer;
  • От 5 до 45.
industriesOfInterest массив string'ов Да

Отрасли, к которым необходимо проверить интерес:

Список отраслей

  • Ателье, ремонт одежды и обуви;
  • Прачечные, химчистки, клининг;
  • Финансы;
  • Авто;
  • Недвижимость;
  • Интернет-магазины - Бытовая техника;
  • Интернет-магазины - Детские товары;
  • Интернет-магазины - Мебель и интерьер;
  • Интернет-магазины - Одежда и обувь;
  • Интернет-магазины - Подарки;
  • Интернет-магазины - Продукты питания;
  • Интернет-магазины - Спортивные товары;
  • Интернет-магазины - Строительство и ремонт;
  • Интернет-магазины - Ткани и фурнитура;
  • Интернет-магазины - Товары для творчества;
  • Интернет-магазины - Электроника;
  • Интернет-магазины - Другое.
  • Образование;
  • Маркетинговые, рекламные, тренинг-агентства;
  • Новые авто - Acura;
  • Новые авто - Alfa Romeo;
  • Новые авто - Aston Martin;
  • Новые авто - Audi;
  • Новые авто - Aurus;
  • Новые авто - BAIC;
  • Новые авто - BMW;
  • Новые авто - BYD;
  • Новые авто - Bentley;
  • Новые авто - Brilliance;
  • Новые авто - Bugatti;
  • Новые авто - Buick;
  • Новые авто - Cadillac;
  • Новые авто - Changan;
  • Новые авто - Chery;
  • Новые авто - Chevrolet;
  • Новые авто - Chevrolet Niva;
  • Новые авто - Chrysler;
  • Новые авто - Citroen;
  • Новые авто - DW Hower;
  • Новые авто - Daewoo;
  • Новые авто - Daihatsu;
  • Новые авто - Datsun;
  • Новые авто - Dayun;
  • Новые авто - Dodge;
  • Новые авто - Dongfeng;
  • Новые авто - EXEED;
  • Новые авто - Evolute;
  • Новые авто - FAW;
  • Новые авто - Ferrari;
  • Новые авто - Fiat;
  • Новые авто - Ford;
  • Новые авто - Foton;
  • Новые авто - GAC;
  • Новые авто - Geely;
  • Новые авто - Genesis;
  • Новые авто - Great Wall;
  • Новые авто - Haval;
  • Новые авто - Hawtai;
  • Новые авто - Honda;
  • Новые авто - Hongqi;
  • Новые авто - Hyundai;
  • Новые авто - Infiniti;
  • Новые авто - Isuzu;
  • Новые авто - JAC;
  • Новые авто - JLR;
  • Новые авто - Jaecoo;
  • Новые авто - Jaguar;
  • Новые авто - Jeep;
  • Новые авто - Jetour;
  • Новые авто - Jetta;
  • Новые авто - KIA;
  • Новые авто - LADA (ВАЗ);
  • Новые авто - Lamborghini;
  • Новые авто - Land Rover;
  • Новые авто - Lexus;
  • Новые авто - Lifan;
  • Новые авто - Lincoln;
  • Новые авто - Livan;
  • Новые авто - Luxgen;
  • Новые авто - Lynk & Co;
  • Новые авто - MAN;
  • Новые авто - MINI;
  • Новые авто - Maserati;
  • Новые авто - Mazda;
  • Новые авто - McLaren;
  • Новые авто - Mercedes-Benz;
  • Новые авто - Mitsubishi;
  • Новые авто - Nissan;
  • Новые авто - Omoda;
  • Новые авто - Opel;
  • Новые авто - Peugeot;
  • Новые авто - Polestar;
  • Новые авто - Ravon;
  • Новые авто - Porsche;
  • Новые авто - Renault;
  • Новые авто - Rolls-Royce;
  • Новые авто - SWM;
  • Новые авто - Seat;
  • Новые авто - Skoda;
  • Новые авто - Skywell;
  • Новые авто - SsangYong;
  • Новые авто - Smart;
  • Новые авто - Sollers;
  • Новые авто - Subaru;
  • Новые авто - Suzuki;
  • Новые авто - Tank;
  • Новые авто - Tesla;
  • Новые авто - Toyota;
  • Новые авто - VOYAH;
  • Новые авто - Volkswagen;
  • Новые авто - Volvo;
  • Новые авто - Zotye;
  • Новые авто - ГАЗ;
  • Новые авто - Москвич;
  • Новые авто - УАЗ;
  • Автозапчасти;
  • Автомобили с пробегом;
  • Мототехника;
  • Автосервис и шиномонтаж;
  • Спецтехника;
  • Шины и диски;
  • Медицина;
  • Квартиры и апартаменты - Эконом и Стандарт;
  • Квартиры и апартаменты - Комфорт и Комфорт+;
  • Квартиры и апартаменты - Бизнес;
  • Квартиры и апартаменты - Премиум;
  • Коммерческая недвижимость;
  • Загородная недвижимость;
  • Аренда недвижимости;
  • Безопасность, охранная деятельность;
  • Ветеринарные клиники;
  • Товары для животных;
  • Гостиницы;
  • Деловые услуги и консалтинг;
  • Перевозки, логистика;
  • Окна и двери - продажа и установка;
  • Дизайн и проектирование;
  • Промышленное оборудование, техника, станки;
  • Развлечения;
  • Ремонт и строительство;
  • Рестораны;
  • Салоны красоты;
  • Спортивные и фитнес-клубы;
  • Телекоммуникации, связь;
  • Юридические услуги;
  • Туристические агентства, операторы;
  • IT, системная интеграция;
  • Дизайн и проектирование;
  • Дом и дача;
  • Рекламные площадки;
  • Ремонт бытовой техники и электроники.

Валидные значения:

  • Тип значения - массив;
  • Каждое значение - string;
  • Значение переданного параметра не может быть пустым;
  • Переданные сферы являются доступными для скоринга по проекту, в котором скоринг создается:
  • Пример - ["Образование"].
projectsForVerification массив integer'ов Да
 Список ваших проектов, по касаниям из которых будет скорректирован итоговый уровень интереса.

Валидные значения:

  • Тип значения - массив;
  • Каждое значение - integer;
  • Значение переданного параметра не может быть пустым;
  • Пример - [303, 323];
  • Можно передать любой список, проверки доступа к сайту нет.
data.geoOfInterest  объект Нет Выбор стран, областей и городов, в которых проверять проявленный интерес. Например, в случае, когда ваша компания представлена в нескольких регионах и вам важно видеть интерес в конкретном регионе.      Валидные значения:
  • Тип значения - массив;
  • Каждое значение - integer;
  • Значение переданного параметра не может быть пустым;
  • Пример - [212312, 2352];
  • Можно передать ID, которые находятся в справочнике города, области или страны. Ссылки на справочники в статье: Скоринг клиентов.
data.geoOfInterest.cities  массив integer'ов  Нет
 Города, в которых выявлен интерес.        Валидные значения:
  • Тип значения - массив;
  • Каждое значение - integer;
  • Значение переданного параметра не может быть пустым;
  • Пример - [212312, 2352];
  • Можно передать ID, которые находятся в справочнике города, области или страны. Ссылки на справочники в статье: Скоринг клиентов.
data.geoOfInterest.regions  массив integer'ов  Нет     Области (регионы), в которых выявлен интерес.        Валидные значения:
  • Тип значения - массив;
  • Каждое значение - integer;
  • Значение переданного параметра не может быть пустым;
  • Пример - [212312, 2352];
  • Можно передать ID, которые находятся в справочнике города, области или страны. Ссылки на справочники в статье: Скоринг клиентов.
data.geoOfInterest.countries  массив integer'ов  Нет
 Страны, в которых выявлен интерес.        Валидные значения:
  • Тип значения - массив;
  • Каждое значение - integer;
  • Значение переданного параметра не может быть пустым;
  • Пример - [212312, 2352];
  • Можно передать ID, которые находятся в справочнике города, области или страны. Ссылки на справочники в статье: Скоринг клиентов.

Пример: 

{
    "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

Формат синхронизации по клиентской базе. Возможные значения:

  • callIds
  • md5
  • raw

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

Уровень интереса. Возможные значения:

  • high
  • middle
  • low
  • none

Ошибки

Ответ с ошибкой в случаях:

  • ошибка авторизации;
  • нет доступа к запрошенному 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-запросы завершатся с ошибкой.


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