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

Материал из WiKi - UserSide
Строка 52: Строка 52:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_supported_method_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_supported_method_list


'''3. Системная информация'''
'''3. Системная информация'''
Строка 60: Строка 60:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_system_information
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_system_information


'''4. Тарифные планы. Стандартные тарифы'''
'''4. Тарифные планы. Стандартные тарифы'''
Строка 68: Строка 68:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_tariff_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_tariff_list


'''5. Населённые пункты'''
'''5. Населённые пункты'''
Строка 76: Строка 76:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_city_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_city_list


'''6. Районы в населённых пунктах''' ''(если есть)''
'''6. Районы в населённых пунктах''' ''(если есть)''
Строка 84: Строка 84:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_city_district_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_city_district_list


'''7. Улицы'''
'''7. Улицы'''
Строка 92: Строка 92:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_street_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_street_list


'''8. Дома'''
'''8. Дома'''
Строка 100: Строка 100:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_house_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_house_list


'''9. Типы дополнительных полей по абонентам''' ''(если используется)''
'''9. Типы дополнительных полей по абонентам''' ''(если используется)''
Строка 108: Строка 108:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_user_additional_data_type_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_additional_data_type_list


'''10. Типы статусов абонентов''' ''(не каждого конкретного абонента, а конфигуратор статусов))''
'''10. Типы статусов абонентов''' ''(не каждого конкретного абонента, а конфигуратор статусов))''
Строка 116: Строка 116:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_user_state_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_state_list


'''11. Группы абонентов''' ''(если используется)''
'''11. Группы абонентов''' ''(если используется)''
Строка 124: Строка 124:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_user_group_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_group_list


'''12. Абоненты/клиенты'''
'''12. Абоненты/клиенты'''
Строка 132: Строка 132:
   
   
  Результат:
  Результат:
  http://userside.eu/userside/api.php?key=keyus&cat=module&request=get_user_list
  http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_list


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

Версия от 21:34, 3 января 2017

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

С документом можно ознакомится по ссылке http://userside.eu/main/files/API_Billing_v1_4.docx

Текущая версия: 1.4 от 03.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)
  • также в самой ERP "UserSide" поддерживается вывод информации по требованиям этого API

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


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

Вводные

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

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

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

4. Дата выводится в формате «ГГГГ-ММ-ДД чч:мм:сс»

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

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

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

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

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

(с полным описанием можно ознакомиться в документе по ссылке выше. Здесь же представлены некоторые методы лишь для общего информирования и с примерами)

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

Запрос:
api.php?key=apikey&request=get_api_information

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_api_information

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

Запрос:
api.php?key=apikey&request=get_supported_method_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_supported_method_list

3. Системная информация

Запрос:
api.php?key=apikey&request=get_system_information

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_system_information

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

Запрос:
api.php?key=apikey&request=get_tariff_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_tariff_list

5. Населённые пункты

Запрос:
?key=apikey&request=get_city_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_city_list

6. Районы в населённых пунктах (если есть)

Запрос:
?key=apikey&request=get_city_district_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_city_district_list

7. Улицы

Запрос:
?key=apikey&request=get_street_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_street_list

8. Дома

Запрос:
?key=apikey&request=get_house_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_house_list

9. Типы дополнительных полей по абонентам (если используется)

Запрос:
?key=apikey&request=get_user_additional_data_type_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_additional_data_type_list

10. Типы статусов абонентов (не каждого конкретного абонента, а конфигуратор статусов))

Запрос:
?key=apikey&request=get_user_state_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_state_list

11. Группы абонентов (если используется)

Запрос:
?key=apikey&request=get_user_group_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_group_list

12. Абоненты/клиенты

Запрос:
?key=apikey&request=get_user_list

Результат:
http://demo.userside.eu/api.php?key=keyus&cat=module&request=get_user_list

Возможные операции в биллинге (из-под 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 в биллинге. Если не включен, то осуществляется лишь чтение данных
  • при правильном заполнении, на странице "Настройка - Биллинги - нужный биллинг" будет видны результаты прямого опроса биллинга