Общая информация

Общая информация

Форматы данных: JSON (in/out), XML (in/out), POST(in)
Входные параметры собираются последовательно. При совпадении названий параметров старые значения будут заменены новыми. Последовательность получения входных параметров:
1) Параметры из GET
2) Параметры из тела запроса (POST) в формате согласно указанному mode — JSON[P] / XML. Если не получается разобрать параметры тела запроса согласно формату ‘mode’ — делается попытка загрузить POST-параметры или разобрать тело запроса (POST) самостоятельно по формату «application/x-www-form-urlencoded».
Языки: русский, английский.
Виды авторизации:
Подпись запроса (симметричный ключ, известный клиенту и серверу). Подпись необходима во многих запросах. см. Алгоритм формирования подписи ниже.
Собственная авторизация API-вызова, когда скрипт конкретного API-вызова ожидает на вход параметры login+password или что-то подобное.

4

3

Наверх

Общие входные параметры

svc Обязательный Код запроса
mode Необязательный, по-умолчанию: xml. Формат обмена. Только в GET. Доступны форматы: json, jsonp, xml.
lang Необязательный, по-умолчанию: en. Язык сообщений. Доступные значения: ru, en.
rlogin Обязательный для некоторых запросов Идентификатор (логин) приложения-клиента API
rsign Обязательный для некоторых запросов Подпись запроса.

 

При форматах json и xml запросы передаются в теле HTTP POST.

2

2

Наверх

Форматы входных параметров

string Строка из любых символов
date Дата yyyy-mm-dd
time Время HH:MM:SS
datetime Дата+время yyyy-mm-dd HH:MM:SS
int Целое число
decimal Дробное число
login Логин
alpha Буквы ctype_alpha()
alnum Буквы+цифры ctype_alnum()
digit / numeric Цифры ctype_digit()
email Адрес эл. почты
phone Номер телефона

2

2

Наверх

Формат ответа

В формате результата XML массивы передаются как элементы <item1></item1><item2></item2> … <itemN></itemN> .

Ответ

Обычно ответ содержит 2 параметра:

result Результат 1-успех, 0-ошибка
data Данные, если result=1 ИЛИ текст ошибки, если result=0

 

Формат содержимого поля data (данные) зависит от запроса, часто это бывает ассоциативный массив (ключи — строки).

Табличные данные

Типовой формат data при возврате табличных данных — массив :

names Массив название колонок array
data Массив записей array
total Общее количество записей int

 

Названия и типы колонок data.names зависят от запроса. Формат data.names — массив значений. Массив не ассоциативный.

Формат data.data — массив из массивов значений. Массивы не ассоциативные.

2

2

Наверх

Алгоритм формирования подписи запроса

Некоторые запросы требуют подписи. Для таких запросов должны быть переданы параметры: rlogin и rsign .

Алгоритм формирования подписи:

  1. Создается массив пар (ключ-значение) из всех параметров будущего запроса, кроме: mode, svc, lang, rsign, charset
  2. Полученный массив сортируется по ключу. Сортировка по возрастанию по ASCII-коду (функция php sort(), флаг сортировки SORT_REGULAR или javascript Array().prototype.sort() без ‘compare function’)
  3. Все параметры (только значения) соединяются через разделитель ‘;’ в одну строку, к этой строке добавляется личный rkey пользователя
  4. Полученная строка хешируется md5
  5. Результат хеширования помещается в параметр rsign

Пример.

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

  • svc=testme
  • lang=ru
  • mode=json
  • name=john
  • fname=doe
  • birthday=2000-01-01
  • login=john.d

Персональные данные пользователя:

  • rlogin=vasya
  • rkey=01234567890

Строка для хеширования:

2000-01-01;doe;john.d;john;vasya;01234567890

Строк после хеширования ⇒ подпись:

4aeb7e509b1cc152321bc641e34cd18b

Запрос, передаваемый на сервер (вариант GET/POST, для xml/json будут соответствующие им форматы):

svc=testme&lang=ru&mode=json&name=john&fname=doe&birthday=2000-01-01&login=
john.d&rlogin=vasya&rsign=4aeb7e509b1cc152321bc641e34cd18b

2

3

Наверх

Основные вызовы API

connect2

Соединить два номера.

Параметры POST:

sip_login Логин учетной записи int(7)
sip_password Пароль учетной записи string
caller Вызывающий номер string
callee Вызываемый номер string

 

Результат:

result Результат обработки 1-успех, 0-ошибка
data Ассоциативный массив, если result=1 ИЛИ текст ошибки, если result=0

 

Содержимое data:

cbid Код запроса соединения string

 

3

2

Наверх

getBalance2

Получить баланс.

Авторизация через любую активную учетную запись клиента.

Параметры POST:

sip_login Логин учетной записи int(7)
sip_password Пароль учетной записи string

 

Результат:

result Результат 1-успех, 0-ошибка
data Ассоциативный массив, если result=1 ИЛИ текст ошибки, если result=0

 

Содержимое data при ‘result’ == 1:

balance Баланс указанной учетной записи float

 

3

2

Наверх

getPriceByDirection2

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

Параметры POST:

sip_login Логин учетной записи int(7)
sip_password Пароль учетной записи string
phonenumber Номер телефона для расчета тарифа int

 

Результат:

result Результат 1-успех, 0-ошибка
data Ассоциативный массив, если result=1 ИЛИ текст ошибки, если result=0

 

Содержимое data при ‘result’ == 1:

prefix Префикс направления string
name Название направления string
price Стоимость минуты float
currency Валюта string

 

3

2

Наверх

getSipInfo

Получение информации об указанной учетной записи.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный (*1)
login Логин ЛК или SIP string Необязательный (*1)
password Пароль ЛК или SIP string Необязательный (*1)
sip_login Логин SIP int(7)
sip_password Пароль SIP string Устаревший, необязательный (*2)

 

  • *1) Обязательно указать один набор параметров — access_token или login+password. Login+password могут быть данными SIP, в таком случае sip_login должен совпадать с login, доступ будет только к нему.
  • *2) Если не указаны login+password, то будут проверены параметры sip_login+sip_password

Результат:

result Результат 1-успех, 0-ошибка
data Ассоциативный массив, если result=1 ИЛИ текст ошибки, если result=0

 

Содержимое data при ‘result’ == 1:

name Имя, присвоенное учетной записи string

 

3

2

Наверх

getUserInfo

Информация о пользователе.

В случае, если представлены учетные данные SIP и есть роль ‘full_user_access’ — информация будет выдана об админском пользователе ЛК.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный (*1)
login Логин ЛК или SIP string Необязательный (*1)
password Пароль ЛК или SIP string Необязательный (*1)
sip_login Логин SIP int(7) Устаревший, необязательный (*2)
sip_password Пароль SIP string Устаревший, необязательный (*2)

 

  • *1) Обязательно указать один набор параметров — access_token или login+password.
  • *2) Если не указаны login+password, то будут проверены параметры sip_login+sip_password

Результат:

result Результат 1-успех, 0-ошибка
data Ассоциативный массив, если result=1 ИЛИ текст ошибки, если result=0

 

Содержимое data при ‘result’ == 1:

name ФИО / Название организации string
lk_login Логин в личном кабинете string
lk_image_url URL на картинку в профиле string
lk_avatar_url URL на картинку в профиле string
currency Валюта договора string
currency_code Валюта договора (код) string

 

2

2

Наверх

Статистика (stats)

getCallsTotals

Получение итоговых данных по вызовам за период.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный*
login Логин ЛК string Необязательный*
password Пароль ЛК string Необязательный*
from Начальное время datetime
to Конечное время datetime

 

*Обязательно указать один набор параметров — access_token или login+password.

Результат — табличные данные.

Названия и типы колонок:

sip_login SIP логин string
inbound_count Количество входящих int
inbound_time Общее время входящих time
outbound_count Количество исходящих int
outbound_time Общее время исходящих time
amount Общая стоимость decimal (.2)
currency Валюта string

 

 

3

2

Наверх

getCallsDetails

Получение детализации по вызовам за период.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный*
login Логин ЛК string Необязательный*
password Пароль ЛК string Необязательный*
sip_login SIP логин string
from Начальное время datetime
to Конечное время datetime
min_duration Минимальная длительность разговора int Необязательный, по-умолчанию 0
page_size Количество на странице int Необязательный, по-умолчанию 10
page_number Номер страницы, начинается с 1 int Необязательный, по-умолчанию 1
sort Сортировка. Варианты: date-desc, date-asc string Необязательный, по-умолчанию ‘date-asc’
show_cb_id Показывать колонку cbid? int Необязательный

 

*Обязательно указать один из параметров — access_token или login+password.

Результат — табличные данные.

Названия и типы колонок:

time Время записи datetime
numfrom Номер А digit
numto Номер Б digit
direction Направление. 1 ⇒ от А к Б int
duration Длительность в секундах int
zone Тарифное направление digit
amount Стоимость decimal(.2)
currency Валюта string
callid Идентификатор разговора string(32)
disposition Статус завершения звонка string
cbid Идентификатор callback string Колонка будет выдана, если в запросе будет передан непустой параметр show_cb_id

 

4

8

Наверх

Записи разговоров (callrec)

getCallsRecords

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

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный (*1)
login Логин ЛК string Необязательный (*1)
password Пароль ЛК string Необязательный (*1)
master_password Мастер-пароль ЛК string Необязательный (*2)
from Начальное время datetime
to Конечное время datetime
page_size Количество на странице int Необязательный, по-умолчанию 10
page_number Номер страницы, начинается с 1 int Необязательный, по-умолчанию 1
sort Сортировка. Варианты: date-desc, date-asc string Необязательный, по-умолчанию ‘date-asc’

 

  • *1) Обязательно указать один набор параметров — access_token или login+password.
  • *2) Параметр master_password обязателен, если у пользователя включена проверка мастер-пароля, иначе он будет игнорирован.

Результат — табличные данные.

Названия и типы колонок:

id id записи для скачивания int
time Время записи datetime
numfrom Номер А string
numto Номер Б string
filesize Размер файла int
callid Идентификатор разговора string(32)

 

 

4

12

Наверх

downloadCallRecord

Скачивание записи по ее идентификатору.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный (*1)
login Логин ЛК string Необязательный (*1)
password Пароль ЛК string Необязательный (*1)
master_password Мастер-пароль ЛК string Необязательный (*2)
record_id id записи для скачивания int
call_id Идентификатор разговора string(32)

 

  • *1) Обязательно указать один набор параметров — access_token или login+password.
  • *2) Параметр master_password обязателен, если у пользователя включена проверка мастер-пароля, иначе он будет игнорирован.

Если recordId задан, то он используется для поиска записи. Иначе — callId.

Результат при успехе:

mp3-файл

Результат при ошибке:

result=0 Результат
data Текст ошибки

4

4

Наверх

События с платформы

listEventActions

Получить список настроек обработки событий с платформы.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный*
login Логин ЛК string Необязательный*
password Пароль ЛК string Необязательный*

 

*Обязательно указать один набор параметров — access_token или login+password.

Результат:

result Результат 1-успех, 0-ошибка
data Ассоциативный массив, если result=1 ИЛИ текст ошибки, если result=0

 

Содержимое data при ‘result’ == 1:

id Id записи int
type Тип («incoming» — входящий / «outgoing» — исходящий / «missed» — пропущенный / «lost» — упущенный / «sip_ringing» — звонит SIP / «sip_hangup» — SIP положил трубку) string
type_param1 Параметр типа (то, что в колонке «Параметр» в модуле РИТКИ «Настройка фильтра событий) string
action Действие (websocket / http / sms / email) string
action_param1 Параметр действия string
flt_phone Входящий телефон (параметр действия) int
flt_wdays Дни недели, строка из 7 цифр 0/1. Каждый день — день недели. Первый день недели — понедельник int(7)
flt_start_time Время начала действия HH:MM:SS
flt_end_time Время окончания действия HH:MM:SS

 

Параметры действия (action_param1) в зависимости от действия (action):

websocket «Пусто»
http URL, который будет вызван
sms Номер телефона, на который будет отправлено SMS
email Адрес эл. почты, на который будет отправлено письмо

 

5

3

Наверх

updateEventAction

Создать/отредактировать/удалить настройку обработки события с платформы.

Параметры POST:

rlogin Логин запрашивающей системы
rsign Подпись запроса
access_token Access token string Необязательный*
login Логин ЛК string Необязательный*
password Пароль ЛК string Необязательный*
id Id записи int
operation Вид операции: create / update / delete string
type Тип («incoming» — входящий / «outgoing» — исходящий / «missed» — пропущенный / «lost» — упущенный / «sip_ringing» — звонит SIP / «sip_hangup» — SIP положил трубку) string Не должен быть обязательным для delete!
Обязательные для operation=create,update
type_param1 Параметр типа (то, что в колонке «Параметр» в модуле РИТКИ «Настройка фильтра событий) string
action Действие (websocket / http / sms / email) string
action_param1 Параметр действия string
flt_phone Входящий телефон (параметр действия) int
flt_wdays Дни недели, строка из 7 цифр 0/1. Каждый день — день недели. Первый день недели — понедельник int(7)
flt_start_time Время начала действия time
flt_end_time Время окончания действия time

 

*Обязательно указать один набор параметров — access_token или login+password.

Результат:

result Результат 1-успех, 0-ошибка
data Пусто при result=1 ИЛИ текст ошибки, если result=0

 

2

3

Наверх