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

Материал из WiKi - UserSide
Нет описания правки
Нет описания правки
 
(не показано 75 промежуточных версий 1 участника)
Строка 1: Строка 1:
[[Universal_API|en]] | [[Универсальное_API|ru]]
Совместно с разработчиками ряда биллингов было создана структура универсального API, которое позволяет удобно и стандартизировано получать информацию из различных биллинговых систем.
Совместно с разработчиками ряда биллингов было создана структура универсального API, которое позволяет удобно и стандартизировано получать информацию из различных биллинговых систем.


С документом можно ознакомится по ссылке
Текущая версия: 1.5 от 06.10.2017 (см. [[Универсальное API#История изменений|историю изменений]])
http://userside.eu/main/files/API_Billing_v1_2.docx
 
Текущая версия: 1.2 от 25.10.2015


На данный момент работу по этому API поддерживают биллинги:
На данный момент работу по этому API поддерживают биллинги:
* [[uBilling]] v.0.7.2+
* [[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+
* [[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
* также в самой ERP "UserSide" поддерживается вывод информации по требованиям этого API


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


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


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


2. Рабочая кодировка – UTF-8
2. Рабочая кодировка – UTF-8
Строка 22: Строка 24:
3. Формат данных с ответами – JSON
3. Формат данных с ответами – JSON


4. Дата выводится в формате «ГГГГ-ММ-ДД чч:мм:сс»
4. В качестве идентификации используется API-ключ
 
5. Дополнительно рекомендуется на уровне API биллинга настраивать и проверять IP-адрес хоста, откуда поступают запросы либо ограничивать доступ vlan`ами


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


6. Дополнительно рекомендуется на уровне API биллинга настраивать и проверять IP-адрес хоста, откуда поступают запросы либо ограничивать доступ vlan`ами
7. Текстовые поля, которые имеют пустое значение – рекомендуется не возвращать вовсе (для экономии трафика)


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


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]] - Тарифные планы. Стандартные тарифы


'''1. Используемая версия API'''
[[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.php?key=apikey&request=get_api_information
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_api_information


'''2. Поддерживаемые методы API'''
[[API - usm_billing - get_user_history|get_user_history]] - История по абоненту


Запрос:
[[API - usm_billing - get_user_list|get_user_list]] - Абоненты/клиенты
api.php?key=apikey&request=get_supported_method_list
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_supported_method_list


'''3. Системная информация'''
[[API - usm_billing - get_user_messages|get_user_messages]] - Сообщения абонентов


Запрос:
[[API - usm_billing - get_user_state_list|get_user_state_list]] - Типы статусов абонентов (конфигуратор статусов)
api.php?key=apikey&request=get_system_information
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_system_information


'''4. Тарифные планы. Стандартные тарифы'''
[[API - usm_billing - get_user_tags|get_user_tags]] - Метки для абонентов


Запрос:
api.php?key=apikey&request=get_tariff_list
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_tariff_list


'''5. Населённые пункты'''
'''Изменение данных:'''


Запрос:
Используются POST или GET-запросы. Отдаётся только та информация, которая существует/используется
?key=apikey&request=get_city_list
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_city_list


'''6. Районы в населённых пунктах''' ''(если есть)''
[[API - usm_billing - change_user_data|change_user_data]] - Изменение данных по абоненту


Запрос:
== Возможные операции в биллинге (из-под UserSide) ==
?key=apikey&request=get_city_district_list
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_city_district_list


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


Запрос:
'''Абоненты'''
?key=apikey&request=get_street_list
* просмотр истории платежей по абоненту
* изменение ФИО/названия абонента
Результат:
* изменение баланса абонента
http://userside.eu/userside/api.php?key=key&cat=module&request=get_street_list


'''8. Дома'''
Для работы с этим функционалом требуется выполнить следующие действия:
* в файле /userside3/main/config/config.php дописать блок


  Запрос:
  $billingSynergy[99] = [
?key=apikey&request=get_house_list
    'url' => 'http://mydomain.com/ubilling/?module=remoteapi&key=my_key&action=userside',
    'is_allow_change' => 1
];
   
   
  Результат:
  Где:
  http://userside.eu/userside/api.php?key=key&cat=module&request=get_house_list
  99 - номер биллинга (Настройка - Биллинги)
url - URL к биллингу
my_key - api-ключ биллинга
is_allow_change - флаг - разрешает изменение данных из-под UserSide в биллинге. Если не включен, то осуществляется лишь чтение данных
 
* при правильном заполнении, на странице "Настройка - Биллинги - нужный биллинг" будет видны результаты прямого опроса биллинга


'''9. Типы дополнительных полей по абонентам''' ''(если используется)''
[[Файл:Bil1.png|thumb|800px|center]]


Запрос:
== История изменений ==
?key=apikey&request=get_user_additional_data_type_list
Результат:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_user_additional_data_type_list


'''10. Типы статусов абонентов''' ''(не каждого конкретного абонента, а конфигуратор статусов))''
'''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'''
  ?key=apikey&request=get_user_state_list
  ''25.10.2015''
   
  В метод get_user_list добавлен элемент
Результат:
  'login' => Имя учетной записи абонента
http://userside.eu/userside/api.php?key=key&cat=module&request=get_user_state_list


'''11. Группы абонентов''' ''(если используется)''
'''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'''
  ?key=apikey&request=get_user_group_list
  ''03.01.2017''
   
  В метод get_user_list добавлена возможность выборки только конкретного абонента
  Результат:
  Добавлены методы:
http://userside.eu/userside/api.php?key=key&cat=module&request=get_user_group_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


'''12. Абоненты/клиенты'''
'''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'''
  ?key=apikey&request=get_user_list
  ''в разработке''
   
  Доработан метод
Результат:
  [[API - usm_billing - get_user_history|get_user_history]]
http://userside.eu/userside/api.php?key=key&cat=module&request=get_user_list
  - в вывод добавлена переменная "customer_id"
  - входным параметром можно подавать даты выборки "date_start", "date_finish"
  - входным параметром можно подавать тип действий "type", по которым требуется получить выборку

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

en | ru

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

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

На данный момент работу по этому 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", по которым требуется получить выборку