Универсальное API: различия между версиями
Admin (обсуждение | вклад) Нет описания правки |
Нет описания правки |
||
(не показана 91 промежуточная версия 1 участника) | |||
Строка 1: | Строка 1: | ||
[[Universal_API|en]] | [[Универсальное_API|ru]] | |||
Совместно с разработчиками ряда биллингов было создана структура универсального API, которое позволяет удобно и стандартизировано получать информацию из различных биллинговых систем. | Совместно с разработчиками ряда биллингов было создана структура универсального API, которое позволяет удобно и стандартизировано получать информацию из различных биллинговых систем. | ||
Текущая версия: 1.5 от 06.10.2017 (см. [[Универсальное API#История изменений|историю изменений]]) | |||
http://userside. | |||
На данный момент работу по этому 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-запросы для получения данных. Отдаётся только та информация, которая существует/используется | |||
[[API - usm_billing - get_api_information|get_api_information]] - Используемая версия API | |||
[[API - usm_billing - get_city_district_list|get_city_district_list]] - Адреса. Районы в населённых пунктах | |||
[[API - usm_billing - get_city_list|get_city_list]] - Адреса. Населённые пункты | |||
[[API - usm_billing - get_connect_list|get_connect_list]] - Коммутация объектов ''(абонентов/оборудования)'' между собой | |||
[[API - usm_billing - get_device_list|get_device_list]] - Оборудование. Список устройств | |||
[[API - usm_billing - get_device_model|get_device_model]] - Оборудование. Модели устройств | |||
[[API - usm_billing - get_device_type|get_device_type]] - Оборудование. Типы устройств | |||
[[API - usm_billing - get_house_list|get_house_list]] - Адреса. Дома | |||
[[API - usm_billing - get_services_list|get_services_list]] - Услуги/дополнительные услуги | |||
[[API - usm_billing - get_street_list|get_street_list]] - Адреса. Улицы | |||
[[API - usm_billing - get_supported_change_user_data_list|get_supported_change_user_data_list]] - Поддерживаемые методы для изменения данных абонента через API | |||
[[API - usm_billing - get_supported_change_user_state|get_supported_change_user_state]] - Поддерживаемые статусы для изменения статуса работы абонента через API | |||
[[API - usm_billing - get_supported_change_user_tariff|get_supported_change_user_tariff]] - Поддерживаемые тарифные планы для изменения тарифа у абонента через API | |||
[[API - usm_billing - get_supported_method_list|get_supported_method_list]] - Поддерживаемые методы API | |||
[[API - usm_billing - get_system_information|get_system_information]] - Системная информация | |||
[[API - usm_billing - get_tariff_list|get_tariff_list]] - Тарифные планы. Стандартные тарифы | |||
[[API - usm_billing - get_user_additional_data_type_list|get_user_additional_data_type_list]] - Типы дополнительных полей по абонентам | |||
[[API - usm_billing - get_user_group_list|get_user_group_list]] - Группы абонентов | |||
[[API - usm_billing - get_user_history|get_user_history]] - История по абоненту | |||
[[API - usm_billing - get_user_list|get_user_list]] - Абоненты/клиенты | |||
[[API - usm_billing - get_user_messages|get_user_messages]] - Сообщения абонентов | |||
[[API - usm_billing - get_user_state_list|get_user_state_list]] - Типы статусов абонентов (конфигуратор статусов) | |||
[[API - usm_billing - get_user_tags|get_user_tags]] - Метки для абонентов | |||
'''Изменение данных:''' | |||
Используются POST или GET-запросы. Отдаётся только та информация, которая существует/используется | |||
[[API - usm_billing - change_user_data|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 в биллинге. Если не включен, то осуществляется лишь чтение данных | |||
* при правильном заполнении, на странице "Настройка - Биллинги - нужный биллинг" будет видны результаты прямого опроса биллинга | |||
[[Файл:Bil1.png|thumb|800px|center]] | |||
== История изменений == | |||
'''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'' | |||
Добавлены методы: | |||
[[API - usm_billing - get_device_type|get_device_type]] | |||
[[API - usm_billing - get_device_model|get_device_model]] | |||
[[API - usm_billing - get_device_list|get_device_list]] | |||
[[API - usm_billing - get_connect_list|get_connect_list]] | |||
'''v. 1.5.1''' | |||
''в разработке'' | |||
Доработан метод | |||
[[API - usm_billing - get_user_history|get_user_history]] | |||
- в вывод добавлена переменная "customer_id" | |||
- входным параметром можно подавать даты выборки "date_start", "date_finish" | |||
- входным параметром можно подавать тип действий "type", по которым требуется получить выборку |
Текущая версия от 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", по которым требуется получить выборку