Доступно с версии 0.84

Рекомендуемая минимальная версия для использования 1.00

• RESTful JSON API tests
• RESTful JSON API logs
• USER RESTful JSON API
• ADMIN RESTful JSON API
• Примеры работы
• Конфигурация API
• Настройка Mojolicious демона

• USER API Redocly
• ADMIN API Redocly
• Список ошибок REST API

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

Подключение

$conf{API_ENABLE} = 1;

Конфигурация

В системе реализован RESTful интерфейс управления услугами и абонентами. Интерфейс находит по адресу /api.cgi.
Отправка, получение данных производится по протоколу HTTP POST/GET/PUT/DELETE. Все взаимодействие по интерфейсу выполняется по принципам REST (ресурс определяться по средствам задания имени в URL).

Для сохранение совместимости с стандартом REST все ключи автоматически переводятся в camelCase, но поскольку несоответствие названий в базе данных может усложнить разработку – существует возможность отключить такое превращение используя несколько вариантов:

1. Параметр $conf{API_FILDS_CAMELIZE} в конфигурационном файле
2. Задать параметрах snakeCase=1 в GET или в POST "snakeCase": "1"

Сделать ограничение на Admin RESTful API, можно с помощью опции $conf{API_IPS}, в конфигурационном файле config.pl, пример

$conf{API_IPS} = '192.20.208.1, 217.116.76.0/24, 104.81.60.171';

Или в настройках Настройка>Администраторы>Доступ

Возвращать по почту письма, смс или другие вещи которые поддерживают перевод в RESTful API, можно включить с помощью опции $conf{API_CONF_LANGUAGE}, в конфигурационном файле config.pl, пример

$conf{API_CONF_LANGUAGE} = 1;

Опция дебага, позволяет выводить debuginfo при ошибке, и также её сохранять с API_LOG. Никак не влияет на работу системы.

$conf{API_DEBUG} = 1;

Авторизация

Для подтверждения личности при выполнении запросов, некоторые пути требуют соответствующий привилегии:

• Авторизация администратора выполняется через API_KEY. Ключ нужно передать в заголовке запроса KEY в значении API_KEY.
  Для получения API_KEY нужно его задать через веб-интерфейс Настройки > Администраторы, поле API_KEY.
  
• Пользователям нужно использовать идентификатор сессии (sid), передавая его значение в заголовке USERSID. 
  Для получения sid можно воспользоваться авторизацией через API используя путь авторизация абонента (/user/login).

Разрешить получить сессию администратора с помощью REST API

$conf{API_ADMIN_AUTH_LOGIN} = 1;

Если данная опция не включена система возвращает 

{"errno":1000002,"errstr":"ERR_AUTH_PASSWORD_LOGIN_DISABLED"}

СТРОГО НЕ РЕКОМЕНДУЕТСЯ ДЛЯ ИСПОЛЬЗОВАНИЯ!!! Возвращает apiKey в запросе на получение сессии!!!

$conf{API_ADMIN_AUTH_LOGIN_RETURN_API_KEY} = 1;

Запуск на nginx

Чтобы включить поддержку nginx нужно:

• прописать в config.pl опцию

  $conf{API_NGINX}=1;

• Отредактировать ваш конфигурационный файл nginx

Работа с API для ботов

для авторизации в USER API телеграмм бота необходимо

1) Прописать IP с которых будет обращаться бот к серверу

$conf{BOT_APIS}='127.0.0.1';

2) Прописать секрет бота для дополнительной проверки запроса (любое значение)

$conf{BOT_SECRET}='test1234567787654';

Авторизация происходит по хедеру X-ABillS-Bot-Secret

X-ABillS-Bot-Secret хранится в телеграм боте и передается для авторизации

Получение информации по пользователю и работа с пользователем

1) хедер X-ABillS-Bot - какой именно бот авторизуется, возможные варианты - Viber, Telegram

2) хедер X-ABillS-User-ID - id пользователя в боте

3) хедер X-ABillS-Admin-ID - id админа в боте

Поддержка Idempotency-Key (experimental)

Сейчас поддерживается только для одного пути 

Нужно включить опцию

$conf{API_IDEMPOTENCY_KEY} = 1;

После этого нужно создать таблицы с дампа

mysql --default-character-set=utf8 -D abills < /usr/abills/db/Api.sql -p

Теперь в запросах должен всегда быть хедер Idempotency-Key в формате UUID, если его не будет, или будет невалидный будет статус HTTP 400, если уже существует - 409

Получить OpenAPI вашей версии

1) Прямо с API

Выставьте переменную:

$conf{API_SWAGGER} = 1;

Обращайтесь за
USER API     - /api.cgi/swagger
ADMIN API - /api.cgi/swagger/admin

Для того, чтобы развернуть Redocly, скопируйте файлы с misc/api/redocly/ в cgi-bin.
USER API     - /redocly-user.html
ADMIN API - /redocly-admin.html

2) Прямо с файла

В каждом биллинге уже установлен полностью скомпилированный OpenAPI.
Они находятся за путями misc/api/bundle_user.yaml и misc/api/bundle_admin.yaml

Стандарт REST

Реализованный в системе RESTful интерфейс управления услугами и абонентами соответствует стандарту REST API.

Дополнительные опции

Преобразования пароля перед отправкой в ответе API:

$conf{API_PASSWORD_ENCODE}='BASE64';

Возможные варианты:

1. BASE64 - Пароль без изменений кодируется в Base64 без переносов строки и возвращается как строка Base64.
2. HEX_STRING - Пароль преобразуется в шестнадцатеричную строку (hex) через unpack('H*', $password), где каждый байт представляется двумя hex-символами.
3. XOR - Каждый байт пароля XOR-ится с числовым ключом hex($conf{API_PASSWORD_ENCODE_KEY}) (например, значение 42 конвертируется в 0x42 = 66), после чего результат дополнительно кодируется в Base64 без переводов строки.