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


Маршруты и аутентификация


Для обеспечение интеграции со внешними системами, необходимо настроить отправку запросов на адрес сервера кол-трекинг. Адрес сервера выдается по запросу технической командой кол-трекинг.


Тип данныхСпособ получения
URLВыдается по запросу, технической службой кол-трекинг


Для обеспечения аутентификации используется токен аутентификации и имя провайдера:


ПараметрСпособ получения
provider_auth_tokenВыдается по запросу, технической службой кол-трекинг
provider_nameВыдается по запросу, технической службой кол-трекинг



Структура запросов


В работе с пользователями в API используются запросы шести типов:


  • user_create - для добавления новых пользователей
  • user_update - для редактирования су пользователей
  • user_delete - для удаления пользователей
  • user_login - для получения ссылки авторизации выбранного пользователя
  • user_logout - для отмены сессии залогиненного ранее пользователя
  • user_read - для получения данных о пользователях в базе Call Tracking

 

Данные передаются в формате JSON. Ниже представлено описание основных параметров, которые должны быть включены в запрос:



user_create
POST /users

 

Параметр

Тип данных

Описание

provider_auth_token

string

Токен аутентификации провайдера

provider_name

string

Имя провайдера

ext_user_id

string

Уникальный идентификатор пользователя в сторонней АТС

user_name

string

Название пользователя (имя компании)

numbers_to_add

string

Список телефонных номеров кол-трекинг для этого пользователя. Указываются в международном формате в виде массива.

email

string

адрес электронной почты для отправки логина и пароля

*Все параметры являются обязательными.


Пример запроса:

{
   "provider_name": "Provider",
   "provider_auth_token": "123dflmsdvpm123",
    "ext_user_id": "45655",
    "user_name": "ООО ПитерзГарден",
    "numbers_to_add": ["+375291010101","+375291010102","+375291010103"],
    "email": "example@mail.com"
}


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

{
    "status_code": 200,
    "status": "OK",
    "user_uid": "sadlem123m593"
}


В случае успеха, в ответе будет содержаться параметр user_uid - уникальный идентификатор в системе кол-трекинг для данного клиента. Он будет необходим для отправки всех последующих запросов, связанных с данным клиентом: события звонков, чтение, изменение и удаление данных клиента.



user_update

PATCH /users/USER_UID

 

Параметр

Тип данных

Описание

provider_name

*string

Имя провайдера

provider_auth_token

*string

Токен аутентификации провайдера

user_uid

*string

Уникальный идентификатор пользователя в системе кол-трекинг

user_name 

**string

Новое имя клиента

numbers_to_add

**string

Список новых телефонных номеров кол-трекинг для этого пользователя. Указываются в международном формате в виде строки, с разделением запятой.

numbers_to_delete

**string

Список телефонных номеров кол-трекинг, которые следует открепить от этого пользователя. Указываются в международном формате в виде строки, с разделением запятой.

number_to_set_inactive

**string

Список телефонных номеров кол-трекинг, которые следует деактивировать, не открепляя от этого пользователя. Указываются в международном формате в виде строки, с разделением запятой.

number_to_set_active

**string

Список деактивированных телефонных номеров кол-трекинг, которые следует активировать заново этого пользователя. Указываются в международном формате в виде строки, с разделением запятой 

! Не все параметры являются обязательными.

* - обязательные параметры
** - необязательные параметры


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


{
"status code": 200
"status": "Ok", 
"message": "No parameters to update"
}


Пример запроса на добавление номеров: 

{
 "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "user_name":  "",
  "numbers_to_add": ["+375291010101","+375291010102","+375291010103"],
  "numbers_to_delete": "",
  "numbers_to_set_active": "",
  "numbers_to_set_inactive": ""
}

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

{
    "status_code": 200,
    "status": "Ok"
}




Пример запроса на удаление номеров: 

{
  "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "numbers_to_delete": ["+375291010101"]
}

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

{
    status_code: 200,
    status: "Ok"
}




Пример запроса на изменение имени: 

{
  "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "name": "Иван Петров"
}

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

{
    "status_code": 200,
    "status": "OK"
}




Пример запроса на деактивацию номеров: 

{
   "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "numbers_to_set_active": ["+375291010102"]
}

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

{
    "status_code": 200,
    "status": "OK"
}




Пример запроса на активацию номеров: 

{
   "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "numbers_to_set_active": ["+375291010102"]
}

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

{
    "status_code": 200,
    "status": "OK"
}


В случае попытки деактивации номеров, которые уже были деактивированы, либо активации номеров, которые являются активными на данный момент, ответ будет содержать ошибку 400:

{
    "status_code": 400,
    "status": "Fail",
    "errors": "Can't parse params"
}




user_delete

DELETE /users/USER_UID

 

Параметр

Тип данных

Описание

provider_name 

string

Имя провайдера

provider_ auth_token

string

Токен аутентификации провайдера

user_uid

string

Уникальный идентификатор пользователя в системе кол-трекинг.

*Все параметры являются обязательными.


Пример запроса:

{
  "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123"
}

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

{
    "status_code": 200,
    "status": "OK"
}

 


 

user_login

POST /Login


Параметр

Тип данных

Описание

provider_name  

string

Имя провайдера

provider_ auth_token

string

Токен аутентификации провайдера

user_uid

string

Уникальный идентификатор пользователя в системе кол-трекинг.

*Все параметры являются обязательными.



Пример запроса:

{
  "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "user_uid": "sadlem123m593"
}

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

{
    "status_code": 200,
    "message": "OK",
    "link": "https://provider.call-tracking.by/users/sadlem123m593/?session=456d44v2216s"
}




user_logout

POST /Logout

 

Параметр

Тип данных

Описание

provider_name   

string

Имя провайдера

provider_ auth_token

string

Токен аутентификации провайдера

user_uid

string

Уникальный идентификатор пользователя в системе кол-трекинг.

*Все параметры являются обязательными.



Пример запроса:

{
  "provider_name": "Provider",
  "provider_auth_token": "123dflmsdvpm123",
  "user_uid": "sadlem123m593"
}

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

{
    "status_code": 200,
    "message": "OK"
}



user_read

GET /users/USER_UID?auth=PROVIDER_NAME:PROVIDER_AUTH_TOKEN


Параметр

Тип данных

Описание

provider_name  

string

Имя провайдера

provider_ auth_token

string

Токен аутентификации провайдера

user_uid

string

Уникальный идентификатор пользователя в системе кол-трекинг.

*Все параметры являются обязательными.


Пример запроса:

https://provider.call-tracking.by/users/sadlem123m593/?auth=Provider:123dflmsdvpm123

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

{
    "status_code": 200,
    "status": "OK",
    "ext_user_id": "45655",
    "user_uid": "sadlem123m593",
    "user_name": "Иван Петров",
    "email": "example@mail.com",
    "active_numbers": ["+375291010102", "+375291010103"],
    "inactive_numbers": ["+375291010101"]
}



Ограничения


В стандартной конфигурации на отправку событий распространяются следующие ограничения:


Период действия ограниченияМаксимальное количество событий
1 секунда100
1 сутки25000


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


Возвращаемые значения


Ответ
КодОписание
{status: ok }200
Событие обработано
{status: fail, errors: "Missing require params [*]"}
400Неверный запрос, отсутствует один из параметров
{status: fail, errors: "Can’t parse params"}
400Неверный тип данных, либо недопустимое значение в передаваемых параметрах
{status: fail, errors: "Invalid uid"}
401Неверный user_uid
{status: fail, errors: "Invalid provider name"}
401Неверный идентификатор провайдера
{status: fail, errors: "Requests limit"}
403Превышен лимит на отправку событий


Перечень ответов и ошибок будет дополняться по мере доработки решения.