Введение

Назначение

Данное руководство описывает REST API для управления конфигурацией шлюзов SMG.

API предоставляет возможность выполнять CRUD-операции (Create, Read, Update, Delete) над объектами конфигурации посредством HTTP-запросов.

Предварительная настройка

Перед началом работы с API необходимо:

1. Настроить API сервер шлюза

• Убедиться, что API сервер включён и настроен интерфейс управления конфигурацией

API → Сервер

2. Создать пользователя

• Пользователь создаётся через веб-интерфейс шлюза или через CLI
• Пользователю должны быть выданы права на управление конфигурацией

API → Аккаунты

Swagger

В веб-интерфейсе шлюза доступна страница Swagger, предназначенная для:

• тестирования API-запросов

• просмотра структуры эндпоинтов

• анализа форматов запросов и ответов

API → Swagger

Формат данных

• Запросы и ответы: application/json

• Аутентификация: Bearer Token

Для выполнения запросов через Swagger необходимо:

1. Выполнить запрос /login, указав имя пользователя и пароль;

2. Получить token из ответа;

3. Указать токен через кнопку Authorize.

Быстрый старт

Для начала работы с API выполните следующие шаги:

1. Авторизуйтесь и получите токен:

   curl -X POST http://<IP>:<PORT>/api/v1/login \
     -H "Content-Type: application/json" \
     -d '{"login":"<login>","password":"<password>"}'
   

2.  Скопируйте token из ответа
3. Выполните тестовый запрос используя скопированный токен в заголовке Authorization:

   curl -X GET http://<IP>:<PORT>/api/v1/config/interfaces \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>"
   

Сценарий работы с API

Типовой сценарий взаимодействия с API:

1. Авторизация пользователя (получение Bearer-токена)
2. Выполнение запросов к конфигурации
3. Сохранение конфигурации (при необходимости)

Запросы API

Поддерживаются следующие HTTP-методы:

• POST — Создание объекта
• GET — Получение одного объекта или списка объектов
• PATCH — Частичное обновление существующего объекта
• DELETE — Удаление объекта

GET запросы поддерживают два режима работы:

1. Получение одного объекта:
GET /endpoint?id=<id>

2. Получение списка объектов:
GET /endpoint

В ответе возвращается соответствующий объект или массив объектов.

POST применяется для создания нового объекта и, как правило, требует передачи всех обязательных параметров.
PATCH применяется для частичного обновления существующего объекта и допускает передачу только изменяемых параметров. Обновляет только переданные поля, остальные параметры остаются без изменений.

Структура API

• /login — авторизация
• /config/... — работа с конфигурацией
• /config/interfaces — сетевые интерфейсы
• /config/domains — домены
• /config/pbx_profiles — PBX профили
• /config/trunks — транковые группы
• /config/sip_interfaces/... — SIP интерфейсы
• /config/abonents/... — абоненты

Заголовки HTTP-запросов

• Content-Type: application/json
• Accept: application/json
• Authorization: Bearer <token>

Все запросы выполняются относительно базового URL: http://<SMG_IP>:<PORT>/api/v1/<endpoint>

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

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

{
  "status": "ok",
  "version": "v1",
  "payload": {}
}

Ошибка:

{
  "status": "error",
  "payload": {
    "code": 400,
    "message": "Описание ошибки"
  }
}

Коды ошибок:

• 400 — Bad request

• 401 — Unauthorized

• 403 — Forbidden

• 404 — Not found

• 405 — Method not allowed

• 500 — Internal server error

Авторизация и работа с сессией

curl -X POST "http://192.168.113.230:3333/api/v1/login" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{"login": "API","password":"rootpasswd"}'

curl -X GET "http://192.168.113.230:3333/api/v1/is_active" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/logout" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X POST "http://192.168.113.230:3333/api/v1/config/abonents/savedb" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Сохранение конфигурации

curl -X GET "http://192.168.113.230:3333/api/v1/config/save" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Настройка SIP интерфейса в режиме SIP

Пример запроса POST/PATCH:

curl -X POST "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij" \
-H "Content-Type: application/json" \
-d '{
"name": "sip_name",
"hostname": "host_name",
"sip_domain": "domain",
"port_source": 5060,
"port_destination": 5061,
"net_interface_sig": 1,
"net_interface_rtp": 1,
"transport": "UDP-prefer",
"regmode": "upper",
"max_active": 0,
"register_delay": 3603,
"codec_ops": [
{
"codec": "CODEC_G726",
"pte": 30,
"ptype": "119"
},
{
"codec": "CODEC_G729",
"pte": 40,
"ptype": "18"
}
],
"mode": "SIP",
  "trunk_group": {
    "id": 6
  }
}'

Обязательные параметры для метода POST:

• net_interface_sig

• net_interface_rtp

• codec_ops

• hostname

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

curl -X GET "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X DELETE "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Настройка SIP интерфейса в режиме SIP-профиль

Пример запроса POST/PATCH:

curl -X POST "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip_profile" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sip_name",
    "port_source": 5060,
    "net_interface_sig": 1,
    "net_interface_rtp": 1,
    "transport": "UDP-only",
    "max_active": 0,
    "codec_ops": [
      {
        "codec": "CODEC_G711A",
        "pte": 40,
        "ptype": "8"
      },
      {
        "codec": "CODEC_G729",
        "pte": 40,
        "ptype": "18"
      }
    ],
    "mode": "SIP profile",
    "upper_registration_profile": [
      1,
      3
    ]
  }'

Обязательные параметры для метода POST:

• net_interface_sig

• net_interface_rtp

• codec_ops

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

curl -X GET "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip_profile?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip_profile" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X DELETE "http://192.168.113.230:3333/api/v1/config/sip_interfaces/sip_profile?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Настройка транковой группы

Пример запроса POST/PATCH:

curl -X POST "http://192.168.113.230:3333/api/v1/config/trunks" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trunk_name",
    "interface_id": 3,
    "type": "sip"
  }'

Обязательных параметров нет.

curl -X GET "http://192.168.113.230:3333/api/v1/config/trunks?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/config/trunks" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X DELETE "http://192.168.113.230:3333/api/v1/config/trunks?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Настройка абонентов

Пример запроса POST/PATCH:

curl -X POST "http://192.168.113.230:3333/api/v1/config/abonents/static_abonents" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "40000",
    "sip_profile": 1,
    "pbx_profile": 1,
    "name": "abon_name",
    "domain_index": 0,
    "port": 5085,
    "ipaddr": "192.168.0.10",
    "login": "user",
    "password": "passwd",
    "authmode": "register"
  }'

Обязательные параметры для метода POST:

• number

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

curl -X GET "http://192.168.113.230:3333/api/v1/config/abonents/static_abonents?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/config/abonents/static_abonents" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X DELETE "http://192.168.113.230:3333/api/v1/config/abonents/static_abonents?id=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Настройка домена

Пример запроса POST/PATCH:

curl -X POST "http://192.168.113.230:3333/api/v1/config/domains" \
  -H "accept: application/json" \
  -H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "domen"
  }'

Обязательный параметр для метода POST:

• name
  

curl -X GET "http://192.168.113.230:3333/api/v1/config/domains?index=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/config/domains" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X DELETE "http://192.168.113.230:3333/api/v1/config/domains?index=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

Команды для получения списка различных сущностей

curl -X GET "http://192.168.113.230:3333/api/v1/config/pbx_profiles" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"

curl -X GET "http://192.168.113.230:3333/api/v1/config/interfaces" \
-H "accept: application/json" \
-H "Authorization: Bearer ilJpdO7gx5tnlg9ZU8cUlhhg8Fjaij"