ABillS
Space shortcuts
Child pages
  • RESTful JSON API
4 more child pages

Versions Compared

Old Version 13

changes.mady.by.user Пасічник Василь

Saved on

compared with

New Version Current

changes.mady.by.user Юрій Андрусяк

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
  • RESTfull JSON API
    • RESTfull JSON API

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

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

    Table of Contents
    maxLevel3

    Children Display
    sortcreation


    Warning

    В данный момент находиться находится в процессе активной разработки

    API может (и будет) дополняться и изменяться в будущем

    Warning
    titleВерсия

    Доступно с версии 0.84 и вышепостоянно расширяется и изменяется, следите за новыми версиями

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

    Подключение

    Code Block
    $conf{API_ENABLE} = 1;

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

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

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

    1. Параметр $conf{API_FILDS_CAMELIZE} в конфигурационном файле
    2. Задать в заголовках запроса CAMELIZE в соответствующие значение (имеет приоритет над значением в конфигурационном файле)параметрах snakeCase=1 в GET или в POST "snakeCase": "1"
    ЗначениеРезультат
    1Все ключи превращаются в camelCase
    0Ключи в исходном виде, как в базе данных (snake_case)


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

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

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


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

    Code Block
    $conf{API_CONF_LANGUAGE} = 1;

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

    Code Block
    $conf{API_DEBUG} = 1;


    Авторизация

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

    • Авторизация администратора выполняется через API_KEY (можно задать в веб-интерфейсе). Ключ нужно передать в заголовке запроса KEY в значении APIзначении API_KEY.
      Для получения API_KEY нужно его задать через веб-интерфейс       Настройки > Администраторы, поле API_KEY.
    • Пользователям нужно использовать идентификатор сессии (sid), передавая его значение в заголовке USERSID. Для заголовке USERSID. 
      Для получения sid можно
      воспользоваться авторизацией через API используя маршрут авторизация путь авторизация абонента (/usersuser/login).
    AnchorAPI администратораAPI администратора Open API (Swagger) Integration for Confluence AnchorAPI пользователяAPI пользователя Open API (Swagger) Integration for Confluence{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Abills user API" }, "host": "demo.abills.net.ua:9443", "basePath": "/api.cgi", "tags": [ { "name": "user", "description": "Работа с пользователем" } ], "schemes": [ "https" ], "paths": { "/user/{UID}": { "get": { "tags": [ "user" ], "summary": "Информация о пользователе", "operationId": "userInfo", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/User" } } }, "security": [ { "USER_SID": [] } ] } }, "/user/{UID}/pi": { "get": { "tags": [ "user" ], "summary": "Персональная информация пользователя", "operationId": "userPersonalInfo", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/UserPi" } } }, "security": [ { "USER_SID": [] } ] } }, "/user/{UID}/credit": { "post": { "tags": [ "user" ], "summary": "Установка кредита пользователю", "operationId": "userSetCredit", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/UserCredit" } } }, "security": [ { "USER_SID": [] } ] } }, "/user/{UID}/internet": { "get": { "tags": [ "user" ], "summary": "Информация об интернет услугах пользователя", "operationId": "userInternetInfo", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/UserInternet" } } }, "security": [ { "USER_SID": [] } ] } }, "/user/{UID}/internet/{ID}/holdup": { "post": { "tags": [ "user" ], "summary": "Приостановление услуги Интернет", "operationId": "userInternetHoldup", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" }, { "name": "ID", "in": "path", "description": "ID услуги Интернет", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/body" } } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/HoldupReply" } } }, "security": [ { "USER_SID": [] } ] }, "delete": { "tags": [ "user" ], "summary": "Удаление рассписания на приостановление услуги Интернет", "operationId": "userDeleteInternetHoldup", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" }, { "name": "ID", "in": "path", "description": "ID услуги Интернет", "required": true, "type": "string" } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/HoldupReply" } } }, "security": [ { "USER_SID": [] } ] } }, "/user/{UID}/internet/{ID}/tariffs": { "get": { "tags": [ "user" ], "summary": "Доступные для изменения ТП", "operationId": "userInternetAvailableToChangeTariffs", "produces": [ "application/json" ], "parameters": [ { "name": "UID", "in": "path", "description": "UID пользователя", "required": true, "type": "string" }, { "name": "ID", "in": "path", "description": "ID услуги", "required": true, "type": "string" } ], "responses": { "200": { "description": "Успешное выполнение", "schema": { "$ref": "#/definitions/UserAvailableTariffs" } } }, "security": [ { "USER_SID": [] } ] } } }, "securityDefinitions": { "USER_SID": { "type": "apiKey", "name": "USERSID", "in": "header" } }, "definitions": { "User": { "properties": { "login": { "type": "string", "example": "3433" }, "deposit": { "type": "integer", "example": 1600 }, "credit": { "type": "integer", "example": 100 }, "creditDate": { "type": "string", "example": "2021-08-13" }, "billId": { "type": "integer", "example": 12 }, "gid": { "type": "integer", "example": 57 }, "disable": { "type": "integer", "example": 0 }, "deleted": { "type": "integer", "example": 0 } } }, "UserPi": { "properties": { "fio": { "type": "string", "example": "Иванов Иван Иванович" }, "addressFull": { "type": "string", "example": "ул.Адамца, 121, 3" }, "age": { "type": "integer", "example": 33 }, "locationId": { "type": "integer", "example": 1444 }, "contractId": { "type": "string", "example": "575493" }, "email": { "type": "array", "items": { "type": "string", "example": "test@gmail.com" } }, "phone": { "type": "array", "items": { "type": "string", "example": "380976574568" } } } }, "UserInternet": { "type": "array", "items": { "$ref": "#/definitions/UserInternet_inner" } }, "UserCredit": { "properties": { "creditSum": { "type": "integer", "example": 500 }, "creditChangePrice": { "type": "integer", "example": 100 }, "uid": { "type": "integer", "example": 11135 }, "creditDays": { "type": "string", "example": "3" }, "creditMonthChanges": { "type": "string", "example": "1" } } }, "UserAvailableTariffs": { "type": "array", "items": { "$ref": "#/definitions/UserAvailableTariffs_inner" } }, "HoldupReply": { "properties": { "success": { "type": "integer", "example": 1 }, "msg": { "type": "string" } } }, "body": { "properties": { "from_date": { "type": "string", "example": "2021-08-14" }, "to_date": { "type": "string", "example": "2021-08-17" } } }, "UserInternet_inner": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "tpName": { "type": "string", "example": "Премиум до 100м" }, "tpId": { "type": "integer", "example": 41 }, "internetStatus": { "type": "integer", "example": 0 }, "cid": { "type": "string", "example": "14:11:11:11:11:c1" }, "monthFee": { "type": "integer", "example": 250 }, "dayFee": { "type": "integer", "example": 0 } } }, "UserAvailableTariffs_inner": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Премиум до 100м" }, "tpId": { "type": "integer", "example": 41 }, "monthFee": { "type": "integer", "example": 250 }, "dayFee": { "type": "integer", "example": 0 }, "comments": { "type": "string" } } } } }


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

    Code Block
    $conf{API_ADMIN_AUTH_LOGIN} = 1;


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

    Code Block
    $conf{API_ADMIN_AUTH_LOGIN_RETURN_API_KEY} = 1;


    Запуск на nginx

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


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

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

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

    Code Block
    $conf{BOT_APIS}='127.0.0.1';

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

    Code Block
    $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 админа в боте


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

    1) Прямо с API

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

    Code Block
    $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.