Универсальное API: различия между версиями

Текущая версия от 17:57, 4 июля 2023

Совместно с разработчиками ряда биллингов было создана структура универсального API, которое позволяет удобно и стандартизировано получать информацию из различных биллинговых систем.

Текущая версия: 1.5 от 06.10.2017 (см. историю изменений)

На данный момент работу по этому API поддерживают биллинги:

uBilling v.0.7.2+ (версия API 1.2) v.0.8.0+ (версия API 1.4) (https://wiki.ubilling.net.ua/doku.php?id=usersideapi)
MikBill v.2.8.16+ (версия API 1.2) v.2.12.7+ (версия API 1.4) (https://wiki.mikbill.pro/billing/configuration/api/userside)
Carbon Billing v.5.15.06+ (версия API 1.2) (https://docs.carbonsoft.ru/display/CarbonBilling/UserSide)
ABillS (при наличии модуля Userside) (http://abills.net.ua/wiki/doku.php/abills:docs:modules:userside:ru)
также в самой ERP "UserSide" поддерживается вывод информации по требованиям этого API

Для взаимодействия используется модуль usm_billing

ВАЖНО: "Универсальное API" - это очень удобный инструмент для работы с самописными биллингами или теми биллингами, которые мы не поддерживаем на данный момент. Администратору/программисту достаточно обеспечить вывод данных в требуемом формате из своего биллинга и это будет достаточно чтобы наш (бесплатный) модуль взаимодействия usm_billing их стандартно обработал.

Вводные

1. Всё взаимодействие построено на API запросах

2. Рабочая кодировка – UTF-8

3. Формат данных с ответами – JSON

4. В качестве идентификации используется API-ключ

5. Дополнительно рекомендуется на уровне API биллинга настраивать и проверять IP-адрес хоста, откуда поступают запросы либо ограничивать доступ vlan`ами

6. На не поддерживаемые методы (или методы без необходимых параметров) необходимо отвечать HTTP-400 статусом через header. В тексте 400-ответа можно расширенно отвечать о характере ошибки.

7. Текстовые поля, которые имеют пустое значение – рекомендуется не возвращать вовсе (для экономии трафика)

8. Данные используются в формате:

Дата - «YYYY-MM-DD hh:nn:ss» - например "2012-12-28 13:59:59"
IP-адрес - long-формат inet_aton() - например 3232235521 для "192.168.0.1"
MAC-адреса - 12 символов в нижнем регистре без разделителей - например "0012b3а78912" для "00:12:B3:A7:89:12"

Поддерживаемые методы

Получение данных:

Используются GET-запросы для получения данных. Отдаётся только та информация, которая существует/используется

get_api_information - Используемая версия API

get_city_district_list - Адреса. Районы в населённых пунктах

get_city_list - Адреса. Населённые пункты

get_connect_list - Коммутация объектов (абонентов/оборудования) между собой

get_device_list - Оборудование. Список устройств

get_device_model - Оборудование. Модели устройств

get_device_type - Оборудование. Типы устройств

get_house_list - Адреса. Дома

get_services_list - Услуги/дополнительные услуги

get_street_list - Адреса. Улицы

get_supported_change_user_data_list - Поддерживаемые методы для изменения данных абонента через API

get_supported_change_user_state - Поддерживаемые статусы для изменения статуса работы абонента через API

get_supported_change_user_tariff - Поддерживаемые тарифные планы для изменения тарифа у абонента через API

get_supported_method_list - Поддерживаемые методы API

get_system_information - Системная информация

get_tariff_list - Тарифные планы. Стандартные тарифы

get_user_additional_data_type_list - Типы дополнительных полей по абонентам

get_user_group_list - Группы абонентов

get_user_history - История по абоненту

get_user_list - Абоненты/клиенты

get_user_messages - Сообщения абонентов

get_user_state_list - Типы статусов абонентов (конфигуратор статусов)

get_user_tags - Метки для абонентов

Изменение данных:

Используются POST или GET-запросы. Отдаётся только та информация, которая существует/используется

change_user_data - Изменение данных по абоненту

Возможные операции в биллинге (из-под UserSide)

Данный функционал поддерживается штатно в биллинге uBilling, начиная с версии v.0.8.0 и в MikBill, начиная с версии v.2.12.7, либо может быть организован для своего самописного биллинга, согласно вышеуказанному универсальному API

Абоненты

просмотр истории платежей по абоненту
изменение ФИО/названия абонента
изменение баланса абонента

Для работы с этим функционалом требуется выполнить следующие действия:

в файле /userside3/main/config/config.php дописать блок

$billingSynergy[99] = [
   'url' => 'http://mydomain.com/ubilling/?module=remoteapi&key=my_key&action=userside',
   'is_allow_change' => 1
];

Где:
99 - номер биллинга (Настройка - Биллинги)
url - URL к биллингу
my_key - api-ключ биллинга
is_allow_change - флаг - разрешает изменение данных из-под UserSide в биллинге. Если не включен, то осуществляется лишь чтение данных

при правильном заполнении, на странице "Настройка - Биллинги - нужный биллинг" будет видны результаты прямого опроса биллинга

История изменений

v. 1.1
17.10.2015
Добавлены методы:
 get_supported_method_list
 get_api_information
 get_system_information
В методе get_house_list убран элемент
 'city_id' => Идентификатор населённого пункта
В методе get_house_list добавлены элементы
 'street2_id' => Идентификатор вторичной улицы (для угловых домов)
 'number2' => Номер на вторичной улице (цифровой. Если есть)
 'block2' => Блок/Здание/Корпус/Строение на вторичной улице (текстовый. Если есть)

v. 1.2
25.10.2015
В метод get_user_list добавлен элемент
 'login' => Имя учетной записи абонента

v. 1.3
12.10.2016
Добавлены методы:
 get_user_tags
 get_services_list
В метод get_tariff_list добавлен элемент
 'service_type' => Тип тарифа
В метод get_house_list добавлен элемент
 'floor' => Количество этажей
 'entrance' => Количество подъездов
 'coordinates' => Координаты точек полигона дома (массив)
В метод get_user_list добавлены элементы
 'tag' => Метки абонента (текстовые)
 'mark' => Метки абонента (булевые)
 'service' => Услуги абонента
 'password' => Пароль абонента

v. 1.4
03.01.2017
В метод get_user_list добавлена возможность выборки только конкретного абонента
Добавлены методы:
 get_user_messages
 get_user_history
 get_supported_change_user_data_list
 change_user_data
 get_supported_change_user_state
 get_supported_change_user_tariff

v. 1.5
06.10.2017
Добавлены методы:
 get_device_type
 get_device_model
 get_device_list
 get_connect_list

v. 1.5.1
в разработке
Доработан метод
 get_user_history
 - в вывод добавлена переменная "customer_id"
 - входным параметром можно подавать даты выборки "date_start", "date_finish"
 - входным параметром можно подавать тип действий "type", по которым требуется получить выборку