Универсальное API
Совместно с разработчиками ряда биллингов было создана структура универсального API, которое позволяет удобно и стандартизировано получать информацию из различных биллинговых систем.
Текущая версия: 1.4.1 от 14.01.2017 (см. историю изменений)
На данный момент работу по этому API поддерживают биллинги:
- uBilling v.0.7.2+ (версия API 1.2) v.0.8.0+ (версия API 1.4)
- MikBill v.2.8.16+ (версия API 1.2)
- Carbon Billing v.5.15.06+ (версия API 1.2)
- также в самой 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_supported_method_list - Поддерживаемые методы API
get_system_information - Системная информация
get_tariff_list - Тарифные планы. Стандартные тарифы
get_city_list - Адреса. Населённые пункты
get_city_district_list - Адреса. Районы в населённых пунктах
get_street_list - Адреса. Улицы
get_house_list - Адреса. Дома
get_user_additional_data_type_list - Типы дополнительных полей по абонентам
get_user_state_list - Типы статусов абонентов (конфигуратор статусов)
get_user_group_list - Группы абонентов
get_user_list - Абоненты/клиенты
get_user_tags - Метки для абонентов
get_services_list - Услуги/дополнительные услуги
get_user_messages - Сообщения абонентов
get_user_history - История по абоненту
get_supported_change_user_data_list - Поддерживаемые методы для изменения данных абонента через API
Изменение данных:
Используются POST или GET-запросы. Отдаётся только та информация, которая существует/используется
change_user_data - Изменение данных по абоненту
Возможные операции в биллинге (из-под UserSide)
Данный функционал поддерживается штатно в биллинге uBilling, начиная с версии v.0.8.0, либо может быть организован для своего самописного биллинга, согласно вышеуказанному универсальному API
Абоненты
- просмотр истории платежей по абоненту
- изменение ФИО/названия абонента
- изменение баланса абонента
Для работы с этим функционалом требуется выполнить следующие действия:
- в файле /main/config/config.php дописать блок
$billingSynergy[99] = array( '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