Методы 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 |
Произошла внутренняя ошибка при удалении напоминания |