Содержание
Тело запроса
При обращении к веб-сервису внешнего программного интерфейса необходимо передавать входные данные в формате JSON.
Запрос к API должен содержать параметр general, который содержит следующие вложенные параметры:
| Параметр | Вложенный параметр | Описание |
|---|---|---|
| general | Основные параметры метода | |
type | Указывает на раздел программного интерфейса (значение — строка). Должен содержать значение:
| |
method | Имя метода, который необходимо выполнить в информационной базе менеджера сервиса (значение — строка) | |
| debug | При наличии этого параметра (с произвольным значением) менеджер сервиса выводит в свой журнал регистрации полные тексты запроса и ответа | |
Запросы к API, выполняющие действия пользователя абонента (кроме метода account/list), должны содержать параметр auth, который содержит следующие вложенные параметры:
| Параметр | Вложенный параметр | Описание |
|---|---|---|
| auth | Параметры авторизации | |
account | Код абонента, от имени которого выполняется обращение к API (значение — число). | |
Состав остальных параметров запроса определяется методом, который необходимо выполнить. Некоторые методы могут не содержать дополнительных входных параметров.
Пример тела запроса (метод «Получить список доступных абонентов»):
|
Тело ответа
Сервис возвращает данные ответа в формате JSON.
Ответ HTTP-сервиса содержит один предопределенный параметр general, который является структурой (содержит вложенные параметры). Предопределенные параметры ответа приведены в таблице.
| Параметр | Вложенный параметр | Описание |
|---|---|---|
| general | Параметры ответа | |
response | Код возврата (значение — число). Типовые коды возврата приведены ниже | |
error | Флаг ошибки (значение — булево). Значение Истина означает, что при выполнении метода возникла ошибка | |
message | Описание ошибки (значение — строка) | |
version | Версия API, которая была задействована при выполнении запроса (значение — число) | |
sm_version | Версия конфигурации менеджера сервиса (значение — строка) | |
sm_timezone | Часовой пояс информационной базы менеджера сервиса (значение — строка) | |
В ответе HTTP-сервиса могут быть дополнительные параметры. Состав этих параметров ответа определяется методом, который был выполнен. Некоторые методы могут не возвращать дополнительных выходных параметров.
Пример тела ответа (метод «Получить список доступных абонентов»):
|
HTTP код состояния
HTTP-сервис ExtAPI всегда возвращает HTTP код состояния 200 OK. Коды, описывающие результат выполнения HTTP-сервиса, передаются в параметре ответа general.response (см. ниже).
Если при обращении к HTTP-сервису ExtAPI в ответе был получен HTTP код состояния, отличающийся от 200, например, 500, 400, 403, 404 и др., это означает, что HTTP-сервис ExtAPI не был выполнен. Полученный HTTP код состояния был выдан одной из программных или аппаратных компонент, находящихся на пути от клиента к серверу, обеспечивающему HTTP-сервис ExtAPI, например:
- фронтенд веб-сервером облачного сервиса Фреш (nginx и др.),
- веб-сервером на котором опубликована информационная база менеджера сервиса,
- прокси-сервером, сетевым шлюзом и т.п.
Коды возврата HTTP-сервиса
Коды возврата HTTP-сервиса передаются в параметре ответа general.response. Типовые коды возврата приведены в таблице.
Код | Значение | Примечание |
|---|---|---|
10200 | Запрос успешно выполнен | Основной код ответа синхронных методов |
10202 | Запрос принят для обработки | Основной код ответа асинхронных методов |
10240 | Запрос выполнен с корректировкой | Запрос успешно выполнен, однако параметры запроса были скорректированы |
10400 | Плохой запрос | В запросе отсутствуют обязательные параметры, либо указаны некорректные значения параметров |
10401 | Запрос не авторизован | Проверка реквизитов авторизации не прошла. |
10403 | Запрещено | Нарушение прав доступа (попытка выполнить операцию над недоступным объектом) |
10404 | Объект не найден | По указанному коду (идентификатору) не удалось найти в базе МС необходимый объект |
10405 | Метод не поддерживается | Метод не поддерживается выбранной для работы версией API (минимальной среди версий API клиента и сервера) |
10406 | Неприемлемые входные данные | Каждый из входных параметров указан корректно, но во входных данных обнаружен конфликт (например, «дата завершения меньше даты начала») |
10409 | Конфликт | Конфликт запроса с текущим состоянием сервера. Например, «указанный адрес уже используется», «запрошенная резервная копия не принадлежит указанному абоненту», и так далее |
10500 | Внутренняя ошибка | Возвращается в случае, если при выполнении прикладной логики возникло исключение |
10501 | Метод не реализован | Вызываемый метод описан в API, но еще не полностью реализован/проверен |
10520 | Неизвестная ошибка | При выполнении метода возникли внутренние ошибки в коде |
Системные перечисления
При передаче данных в формате JSON перечисления конфигурации менеджера сервиса кодируются строковыми значениями.
Значения перечислений приведены в таблице.
Имя в JSON | Значение в конфигурации |
Роль пользователя абонента | |
owner | Владелец абонента |
administrator | Администратор абонента |
operator | Оператор абонента |
user | Пользователь абонента |
Роль пользователя области | |
user | Запуск |
administrator | Запуск и администрирование |
| api | Доступ к API |
Статус области | |
ready | Готова |
preparation | Готовится к использованию |
used | Используется |
converted | Конвертируется |
copied | Копируется |
decommissioned | К удалению |
new | Новая |
missing | Отсутствует |
error | Ошибка подготовки |
removed | Удалена |
Тип клиентского приложения | |
thin | Тонкий клиент |
thick | Толстый клиент |
web | Веб-клиент |
ws | Web-соединение |
hs | HTPS-соединение |
conf | Конфигуратор |
com | Внешнее соединение |
job | Фоновое задание |
Тип подписки | |
basic | Основная |
prolonging | Продлевающая |
extending | Расширяющая |
Тип услуги | |
unlimited | Безлимитная |
limited | Лимитированная |
unique | Уникальная |
Типы значений дополнительных реквизитов и дополнительных свойств
При чтении дополнительных реквизитов и дополнительных свойств методы API выдают тип и значение дополнительного реквизита/свойства — параметры type и value (см., например, описание метода account/customers/attached_info).
№ | Тип реквизита или свойства | type | value |
|---|---|---|---|
| 1 | Строка | string | Значение |
| 2 | Число | decimal | Значение |
| 3 | Дата | date | Значение |
| 4 | Булево | boolean | Значение |
| 5 | Абоненты | subscriber | Код |
| 6 | ВидыОграниченийТарифов | service | Код |
| 7 | ЗначенияСвойствОбъектовИерархия | additional_value_group | Наименование |
| 8 | ЗначенияСвойствОбъектов | additional_value | Наименование |
| 9 | Тарифы | tariff | Код |
| 10 | ТарифыПоставщиковУслуг | service_provider_tariff | Код |
| 11 | Пользователи | user | Код |
| 12 | ПериодыДействияТарифов | tariff_period | Код |
| 13 | Подписка | subscription | Номер |
При установке значений дополнительных реквизитов и дополнительных свойств также указываются тип и значение дополнительного реквизита/свойства — параметры type и value (см., например, описание метода account/customers/update_attached_info). Тип можно не указывать, если дополнительный реквизит или дополнительное свойство может иметь значения только одного типа.
Если значение дополнительного реквизита или дополнительного свойства должно быть значением из заданного перечисления (фиксированного набора значений), то в поле value можно использовать спецсимволы, аналогичные используемым в строках языка запроса 1С:
- % (процент) — последовательность, содержащая любое количество произвольных символов.
- _ (подчеркивание) — один произвольный символ.
- / — следующий символ нужно интерпретировать как обычный символ.