Методы RESTful API

Методы RESTful API - это набор обработчиков, с которыми можно взаимодействовать через сеть Интернет по протоколу HTTP.

Передача параметров при отправке HTTP-запросов производится в составе URL.

Результат выполнения запроса возвращается обработчиком в формате JSON.

Доступ к REST API

Разграничение доступа к REST API выполняется на основе JWT-токенов. Токен передается либо в заголовке Authorization, либо как параметр token в составе запрашиваемого URL.

Управление действующими токенам производится в Личном кабинете пользователя с правами администратора на странице Профиль - Пользователь.

В Личном кабинете пользователя также можно создать токен для личного использования со всеми доступными пользователю правами.

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

Получение информации о текущем пользователе

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

Метод Путь
GET https://www.telestore.ru/rest/user

Требуемые разрешения для токена: profile.user.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
Код ответа Описание
200 Информация о клиенте
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении данных о пользователе

Успешный ответ:

Параметр Тип Описание
auth_by_phone булев аутентификация через код из SMS, которая отправляется на контактный мобильный номер
email строка адрес электронной почты пользователя
email_state целое число статус адреса электронной почты пользователя (0 - отсутствует, 1 - не подтвержден, 2 - подтвержден)
is_blocked булев пользователь заблокирован
last_usage временная метка временная метка последнего обращения пользователя к личному кабинету
login строка логин пользователя
name строка имя пользователя
phone строка контактный мобильный номер
send_news булев отправлять на адрес электронной почты пользователя рассылки с новостями и акциями компании
show_tips булев показывать подсказки
roles массив список ролей пользователя
roles[].id целое число уникальный идентификатор роли
roles[].role целое число тип роли
roles[].service целое число уникальный идентификатор клиента (для клиентской роли)
roles[].vpbx строка код клиента (для клиентской роли)
roles[].agent целое число уникальный код агента (для агентской роли)
roles[].description строка название клиента (для клиентской роли)

Получение информации об услуге

Данный метод используется для получения общей информации об услуге, подключенной пользователю.

Метод Путь
GET https://www.telestore.ru/rest/service

Требуемые разрешения: service.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
Код ответа Описание
200 Информация о пользователе
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении данных о пользователе

Успешный ответ:

Параметр Тип Описание
acc_email строка адрес электронной почты финансового контакта
acc_email_state целое число статус адреса электронной почты финансового контакта (0 - отсутствует, 1 - не подтвержден, 2 - подтвержден)
acc_name строка имя финансового контакта
agent целое число код агента
balance число сумма денежных средств на лицевом счете клиента
bonuses число сумма бонусов на лицевом счете клиента
consider_holidays булев считать при работе услуги государственные праздники как выходные дни
credit_limit число сумма кредитного лимита, установленного на лицевом счете клиента
customer строка имя клиента или наименование организации клиента
enabled_from временная метка момент времени активации услуги
enabled_to временная метка момент времени блокировки исходящей связи из-за отрицательного баланса лицевого счета клиента
ext_from строка городской номер, используемый в услуге по умолчанию
id целое число идентификатор клиента
is_blocked булев клиент заблокирован
location целое число локация клиента (1 - локация по умолчанию)
max_accounts целое число допустимое число аккаунтов/транков/сотрудников
max_dest_group_type целое число направления, открытые для исходящей связи (0 - только добавочные номера, 1 - только городские номера, 2 - городские и мобильные номера, 3 - все, кроме международной связи, 4 - все, кроме дальнего зарубежья, 5 - все, кроме спутниковой связи, 6 - все)
max_neighbours целое число допустимое число "своих" номеров
promised_till временная метка момент времени, до которого действует обещанный платеж
simcalls целое число допустимое число одновременных исходящих соединений
tariffplan целое число тарифный план (1 - тарифный план по умолчанию)
tech_email строка адрес электронной почты технического контакта
tech_email_state целое число статус адреса электронной почты технического контакта (0 - отсутствует, 1 - не подтвержден, 2 - подтвержден)
tech_name строка имя технического контакта
testing_till временная метка момент времени, до которого действует тестовый период
type целое число тип услуги (1 - ТелеТранк, 2 - ТелеЛайт, 4 - ТелеВАТС, 5 - ТелеНомер)
vpbx строка код клиента

Получение информации о внутренних аккунтах

Данный метод используется для получения информации о внутренних аккаунтах услуги (транках или сотрудниках).

Метод Путь
GET https://www.telestore.ru/rest/service/accounts

Требуемые разрешения: service.accounts.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
Код ответа Описание
200 Список аккаунтов
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении данных об аккаунтах

Успешный ответ:

Параметр Тип Описание
accounts массив список аккаунтов клиента
accounts[].autoanswer массив строк список идентификаторов аккаунтов, от которых вызовы на данный аккаунт идут с запросом автоответа
accounts[].ext-from строка номер телефона в формате E.164, которым будут закрываться исходящие вызовы в город с данного аккаунта. При этом, если совершается исходящий вызов с номером А, который есть в списке подключенных данному клиенту городских номеров, то номер А пропускается прозрачно. Если номер А есть в белом списке (white-list), то данный номер устанавливается в качестве номера переадресации
accounts[].forward хэш правила переадресации для аккаунта. Если параметр отсутствует или пустой, то считается, что никакие правила переадресации не установлены. Правила применяются в следующем порядке: unconditional, busy, no-answer, emergency
accounts[].forward.busy строка если параметр задан, то в случае, если аккаунт занят или вызов был сброшен абонентом, входящий вызов направляется на номер переадресации. Может быть как внешний номер, так и логин другого аккаунта
accounts[].forward.emergency строка если параметр задан, то в случае отсутствия действующих регистраций для данного аккаунта, а также если от аккаунта не приходит никакого ответа (таймаут) или приходит ответ c кодом >= 500, вызов направляется на номер переадресации. Может быть как внешний номер, так и логин другого аккаунта
accounts[].forward.no-answer строка если параметр задан, то в случае, если абонент не отвечает, входящий вызов направляется на номер переадресации. Может быть как внешний номер, так и логин другого аккаунта
accounts[].forward.no-answer-timeout целое число таймаут в секундах перед выполнением переадресации по неответу
accounts[].forward.unconditional строка если параметр задан, то в любом случае входящий вызов направляется не на аккаунт, а на номер переадресации. Может быть как внешний номер, так и логин другого аккаунта
accounts[].id строка идентификатор аккаунта, соответствующий последним 4 цифр его логина
accounts[].int-from строка внутренний номер аккаунта
accounts[].int-name строка внутреннее имя аккаунта
accounts[].is_blocked булев аккаунт заблокирован
accounts[].max-dest-group-type целое число направления, открытые для исходящей связи с аккаунта (0 - только добавочные номера, 1 - только городские номера, 2 - городские и мобильные номера, 3 - все, кроме международной связи, 4 - все, кроме дальнего зарубежья, 5 - все, кроме спутниковой связи, 6 - все). Если параметр превышает значение параметра max_dest_group_type услуги или отсутствует, то считается, что ограничения на исходящую связь для данного учетной записи определяются параметром max_dest_group_type услуги
accounts[].pickupers массив строк список идентификаторов аккаунтов, которые могут отслеживать состояние данного аккаунта (subscribe) и перехватывать (puckup) поступающие на него вызовы
accounts[].recording булев запись всех разговоров аккаунта
accounts[].ref строка реферальный код для регистрации пользователя, относящегося к данному аккаунту
accounts[].role целое число тип роли пользователя, относящегося к данному аккаунту
accounts[].use-neighbour целое число идентификатор транка ("своего номера"), в который необходимо отправлять все исходящие или переадресованные от аккаунта вызовы. Если параметр отсутствует или транк с указанным идентификатором отсутствует, то вызовы направляются маршрутом по умолчанию
accounts[].user целое число идентификатор пользователя, относящегося к данному аккаунту
accounts[].whitelist массив строк список номеров, с которых могут звонить на данный аккаунт. Если список не пустой и номер переадресации или номер А не попадает в него, то вызов направляется на номер переадресации по занятости (forward.busy)

Получение списка URL для Webhook'ов

Данный метод используется для получения списка URL, на которые отправляются события о звонках.

Метод Путь
GET https://www.telestore.ru/rest/service/webhooks

Требуемые разрешения: service.webhooks или service.webhooks.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
Код ответа Описание
200 Список Webhook'ов
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении данных о Webhook'ах

Успешный ответ:

Параметр Тип Описание
webhooks массив строк список установленных URL Webhook'ов

Обновление списка URL Webhook'ов

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

Метод Путь
POST https://www.telestore.ru/rest/service/webhooks

Требуемые разрешения: service.webhooks

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
webhooks Массив строк в формате Json
Код ответа Описание
204 Список Webhook'ов обновлен
400 Переданы неправильные параметры
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при обновлении списка Webhook'ов

Обратный звонок

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

Метод Путь
GET https://www.telestore.ru/rest/service/accounts/callback

Требуемые разрешения: service.accounts.callback

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
account Последние 4 цифры логина аккаунта
aNumber Номер в формате E.164 (например, 74991112233), с которого будет выполняться вызов к абоненту Исходящий номер, установленный в настройках аккаунта
bNumber или number Номер абонента в формате E.164 (например, 74991112233)
name Имя абонента (до 128 символов), которое будет отображаться на телефоне аккаунта (необязательный)
prompt Флаг, определяющий нужно ли голосовое приветствие "Это обратный звонок" (true или false) true
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
hangupTimeout Таймаут принудительного завершения звонка после ответа абонента, секунды 3600 (1 час)
Код ответа Описание
202 Задание на обратный звонок создано
400 Переданы неправильные параметры
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при создании задания на обратный звонок

Получение детализации разговоров

Данный метод используется для получения детализации разговоров по определенному фильтру.

Метод Путь
GET https://www.telestore.ru/rest/service/calls/history

Требуемые разрешения: service.calls.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента Значение атрибута service токена доступа
type Тип разговоров (all, incoming, missed, outgoing, internal, faxes) all
begin Начало периода, за который запрашивается детализация (unix epoch)
end Конец периода, за который запрашивается детализация (unix epoch)
query Строка, по которой производится фильтрация разговоров
offset Смещение, с которым запрашивается детализация
limit Количество запрашиваемых вызовов
Код ответа Описание
200 Детализация разговоров
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении данных о разговорах

Успешный ответ:

Параметр Тип Описание
calls массив объектов детализация разговоров
noMore булев в базе больше нет данных, соответствующих запросу
calls[].a_account строка аккаунт абонента А
calls[].a_def строка номер мобильного абонента, который инициировал вызов (в случае инициации вызова с SIM-карты)
calls[].a_name строка отображаемое имя абонента А
calls[].a_number строка номер абонента А (From)
calls[].answer_timestamp временная метка момент начала разговора
calls[].b_def строка номер мобильного абонента, на который поступил вызов (в случае завершения вызова на SIM-карту)
calls[].b_account строка аккаунт абонента Б
calls[].b_number строка номер абонента Б (To)
calls[].fax строка URL принятого факсимильного документа
calls[].hangup_cause строка причина разъединения
calls[].hangup_cause_code целое число код причины разъединения
calls[].hangup_timestamp временная метка момент завершения разговора
calls[].id строка идентификатор звонка (Call-Id)
calls[].neighbour строка идентификатор "своего" номера, через который был совершен разговор (user@domain.com)
calls[].r_account строка аккаунт абонента, с которого была совершена переадресация
calls[].r_number строка номер абонента, с которого была совершена переадресация (Diversion)
calls[].record строка URL записи разговора
calls[].record_stereo строка URL записи разговора в стерео (срок хранения 1 неделя)
calls[].start_timestamp временная метка момент начала звонка
calls[].type строка тип разговора (incoming, missed, outgoing, internal, fax, voicemail)
calls[].voicemail строка URL голосового сообщения, оставленного в голосовой почте

Получение статистики разговоров

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

Метод Путь
GET https://www.telestore.ru/rest/service/calls/stats

Требуемые разрешения: service.calls.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента Значение атрибута service токена доступа
type Тип разговоров (all, incoming, missed, outgoing, internal, faxes) all
begin Начало периода, за который запрашивается статистика (unix epoch)
end Конец периода, за который запрашивается статистика (unix epoch)
Код ответа Описание
200 Статистика разговоров
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении статистики

Успешный ответ:

Параметр Тип Описание
stats массив объектов Статистика разговоров
stats[].timestamp строка Час, за который посчитана статистика
stats[].value целое число Количество разговоров

Создание задания на подготовку архива с записями разговоров

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

Метод Путь
POST https://www.telestore.ru/rest/service/jobs

Требуемые разрешения: service.jobs

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента Значение атрибута service токена доступа
job ArchiveOfRecords - подготовка архива с записями разговоров
type Тип разговоров (all, incoming, missed, outgoing, internal, faxes) all
begin Начало периода, за который запрашивается детализация (unix epoch)
end Конец периода, за который запрашивается детализация (unix epoch)
query Строка, по которой производится фильтрация разговоров
minDuration Минимальная длительность разговора, который нужно добавить в архив, секунды
Код ответа Описание
200 Задание создано
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при создании задания

Успешный ответ:

Параметр Тип Описание
job целое число ID задания

Получение статуса выполнения задания

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

Метод Путь
GET https://www.telestore.ru/rest/service/jobs

Требуемые разрешения: service.jobs

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента Значение атрибута service токена доступа
job ID задания
Код ответа Описание
200 Текуший статус выполнения задания
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при чтении статуса выполнения задания

Успешный ответ:

Параметр Тип Описание
status строка Статус выполнения задания (new - новое задание, producing - в стадии выполнения, empty - результат не содержит данных, failed - произошла ошибка при выполнении задания, finished - задание выполнено)
progress целое число Текущий процент выполнения задания (для задания на подготовку архива с записями разговоров)
url строка URL архива (для задания на подготовку архива с записями разговоров)

Получение списка подключенных SIM-карт

Данный метод используется для получения списка подключенных SIM-карт и привязанных к ним аккаунтов

Метод Путь
GET https://www.telestore.ru/rest/service/accounts/fmc

Требуемые разрешения: service.accounts или service.accounts.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
Код ответа Описание
200 Список подключенных SIM-карт
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении списка подключенных SIM-карт

Успешный ответ:

JSON Тип Описание
fmc[].account строка привязанный аккаунт
fmc[].def строка мобильный номер, привязанный к SIM-карте
fmc[].iccid число идентификатор SIM-карты

Обновление списка подключенных SIM-карт

Данный метод используется для полного обновления списка подключенных SIM-карт и привязанных к ним аккаунтов

Метод Путь
POST (JSON) https://www.telestore.ru/rest/service/accounts/fmc

Требуемые разрешения: service.accounts

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
JSON Тип Описание
fmc[].account строка привязанный аккаунт
fmc[].def строка мобильный номер, привязанный к SIM-карте
Код ответа Описание
204 Список подключенных SIM-карт обновлен
400 Переданы неправильные параметры
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при обновлении списка подключенных SIM-карт

Получение списка напоминаний об оплате

Данный метод используется для получения списка напоминаний об оплате

Метод Путь
GET https://www.telestore.ru/rest/service/notification_triggers

Требуемые разрешения: service или service.readonly

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
Код ответа Описание
200 Список напоминаний
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при получении списка напоминаний

Успешный ответ:

JSON Тип Описание
[].id целое число идентификатор напоминания
[].type целое число тип напоминания (1 - ежемесячное напоминание, 2 - напоминание при достижении минимального баланса лицевого счета)
[].value_int целое число пороговое значение (для type = 1 - день месяца, когда будет выполняться напоминание, для type = 2 - минимальное значение баланса лицевого счета)
[].value_str строка зарезервировано
[].details.amount число сумма автоматически созданного счета для пополнения баланса
[].details.email строка email пользователя, которому будет направлено напоминание (должен быть верифицирован)
[].details.name строка имя пользователя, которому будет направлено напоминание
[].executed_at временная метка момент последнего выполнения напоминания
[].reseted_at временная метка момент изменения настроек напоминания

Изменение настроек напоминания об оплате

Данный метод используется для изменения настроек напоминания об оплате

Метод Путь
POST (JSON) https://www.telestore.ru/rest/service/notification_triggers

Требуемые разрешения: service

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
JSON Тип Описание
id целое число идентификатор напоминания
type целое число тип напоминания (1 - ежемесячное напоминание, 2 - напоминание при достижении минимального баланса лицевого счета)
value_int целое число пороговое значение (для type = 1 - день месяца, когда будет выполняться напоминание, для type = 2 - минимальное значение баланса лицевого счета)
value_str строка зарезервировано
details.amount число сумма автоматически созданного счета для пополнения баланса
details.email строка email пользователя, которому будет направлено напоминание (должен быть верифицирован)
details.name строка имя пользователя, которому будет направлено напоминание
Код ответа Описание
204 Напоминание обновлено
400 Переданы неправильные параметры
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при обновлении напоминания

Удаление напоминания об оплате

Данный метод используется для удаления напоминания об оплате

Метод Путь
DELETE https://www.telestore.ru/rest/service/notification_triggers

Требуемые разрешения: service

Параметр Описание Значение по умолчанию
token Токен доступа к API Значение заголовка Authorization
service Уникальный идентификатор клиента (необязательный) Значение атрибута service токена доступа
id Уникальный идентификатор напоминания
Код ответа Описание
204 Напоминание удалено
400 Переданы неправильные параметры
403 Доступ запрещен, невалидный токен
503 Произошла внутренняя ошибка при удалении напоминания