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

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


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


На данный момент работу по этому API поддерживают биллинги:
На данный момент работу по этому API поддерживают биллинги:
* [[uBilling]] v.0.7.2+ (версия API 1.2) v.0.8.0+ (версия API 1.4)  
* [[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)
* [[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|Carbon Billing]] v.5.15.06+ (версия API 1.2)
* [[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]]'''
Для взаимодействия используется модуль '''[[usm_billing]]'''


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


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


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


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


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


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


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


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_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_supported_method_list|get_supported_method_list]] - Поддерживаемые методы API
Строка 47: Строка 76:
[[API - usm_billing - get_tariff_list|get_tariff_list]] - Тарифные планы. Стандартные тарифы
[[API - usm_billing - get_tariff_list|get_tariff_list]] - Тарифные планы. Стандартные тарифы


[[API - usm_billing - get_city_list|get_city_list]] - Адреса. Населённые пункты
[[API - usm_billing - get_user_additional_data_type_list|get_user_additional_data_type_list]] - Типы дополнительных полей по абонентам


[[API - usm_billing - get_city_district_list|get_city_district_list]] - Адреса. Районы в населённых пунктах
[[API - usm_billing - get_user_group_list|get_user_group_list]] - Группы абонентов


[[API - usm_billing - get_street_list|get_street_list]] - Адреса. Улицы
[[API - usm_billing - get_user_history|get_user_history]] - История по абоненту


[[API - usm_billing - get_house_list|get_house_list]] - Адреса. Дома
[[API - usm_billing - get_user_list|get_user_list]] - Абоненты/клиенты


[[API - usm_billing - get_user_additional_data_type_list|get_user_additional_data_type_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_state_list|get_user_state_list]] - Типы статусов абонентов (конфигуратор статусов)


[[API - usm_billing - get_user_group_list|get_user_group_list]] - Группы абонентов
[[API - usm_billing - get_user_tags|get_user_tags]] - Метки для абонентов


[[API - usm_billing - get_user_list|get_user_list]] - Абоненты/клиенты


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


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


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


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


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


'''Абоненты'''
'''Абоненты'''
Строка 82: Строка 107:


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


  $billingSynergy[99] = array(
  $billingSynergy[99] = [
     'url' => 'http://mydomain.com/ubilling/?module=remoteapi&key=my_key&action=userside',
     'url' => 'http://mydomain.com/ubilling/?module=remoteapi&key=my_key&action=userside',
     'is_allow_change' => 1
     'is_allow_change' => 1
  );
  ];
   
   
  Где:
  Где:
Строка 98: Строка 123:


[[Файл:Bil1.png|thumb|800px|center]]
[[Файл: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

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