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

Текущая версия от 14:51, 13 июля 2023

Этот раздел описывает возможности использования встроенного API в ERP "UserSide", что позволяет использовать встроенный функционал в собственных проектах.

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

Принцип работы

За взаимодействие отвечает файл /api.php

Можно использовать и GET и POST запросы.

Входящие параметры:
Обязательные:
 key - ключ API
 cat - категория запроса
Необязательные:
 skip_internal_api - флаг - не включать внутренние триггеры системы (разумно использовать, когда ваш метод API и есть реакция на какой-то триггер и в итоге при обычной работе он же сам и зацикливает свою работу)
Прочие дополнительные параметры, в зависимости от категории (см. ниже в соответствующих категориях). Например:
 customer_id - id абонента
 is_potential - флаг. Может принимать значение 1 или 0. Большинство флагов имеют префикс is.

Пример запроса:
api.php?key=apikey&cat=abon&action=msg&usercode=1

Возвращаемые данные:
 Если запрос предполагает какое-то действие или возврат информации, то в формате JSON будет возвращена информация:
  array(
   [Result] => OK / ERROR
   [ErrorText] => В случае ошибки - текст ошибки
  )

Также разумно проверять HTTP-код ответа. В случае возникновения ошибок/некорректных запросов - HTTP-код будет отличаться от 200

Основная настройка

Настройте API-ключ.

Категории

address - Адреса
attach - Прикрепляемые файлы
additional_data - Дополнительные поля/данные для объектов
advertising - Рекламные кампании
billing - Биллинги
cable_route - Кабельные трассы и каналы
call - Звонки
commutation - Коммутация объектов
cross - ODF/Кроссы
customer - Абоненты. Большинство действий актуально для ручных биллингов
device - Оборудование
employee - Сотрудники (с 3.16dev2)
fiber - Кабельные линии
gps - GPS-трекеры
inventory - Склад
key - Ключи
map - Карты покрытия
module - Внешние запросы от модулей
newin - Заявка на подключение
node - Сооружения связи (узлы связи, муфты, опоры, колодцы)
notepad - Блокнот
operator - Операторы системы (до 3.16dev2)
owner - Собственники объектов
redirect - Переадресация на карточку объекта по какому-то признаку
service - Дополнительные услуги
setting - Настройка
sms - SMS-сообщения
splitter - Делители/уплотнители
staff - Сотрудники (до 3.16dev2)
system - Системная информация и операции
tariff - Тарифы
task - Задания
trader - Поставщики
vehicle - Автотранспорт
vlan - Vlan

@@ Строка 1: / Строка 1: @@
-Этот раздел описывает возможности использования встроенного API в САП "UserSide", что позволяет использовать встроенный функционал в собственных проектах.
+[[API_EN|en]] | [[API|ru]]
+Этот раздел описывает возможности использования встроенного API в ERP "UserSide", что позволяет использовать встроенный функционал в собственных проектах.
 API охватывает на данный момент не весь функционал и постепенно дорабатывается, так что данная страница будет иметь частые изменения и дополнения.
@@ Строка 6: / Строка 8: @@
 За взаимодействие отвечает файл /api.php
+Можно использовать и GET и POST запросы.
   Входящие параметры:
   Обязательные:
-   api - ключ API
+   key - ключ API
-   kat - категория запроса
+   cat - категория запроса
-  Возможные:
+  Необязательные:
-   cp - кодировка ''(возможное значение: cp1251)''. По-умолчанию данные возвращаются в кодировке utf8.
+   skip_internal_api - флаг - не включать внутренние триггеры системы ''(разумно использовать, когда ваш метод API и есть реакция на какой-то триггер и в итоге при обычной работе он же сам и зацикливает свою работу)''
-  gz - возврат данных в сжатом формате ''(возможное значение: disable)''. По-умолчанию данные возвращаются в сжатом формате.
+ Прочие дополнительные параметры, в зависимости от категории ''(см. ниже в соответствующих категориях)''. Например:
-  subkat - подкатегория запроса
+  customer_id - id абонента
-  sort_desc - обратная сортировка результата запроса ''(Возможное значение: 1)''
+  is_potential - флаг. Может принимать значение 1 или 0. Большинство флагов имеют префикс '''is'''.
-  Прочие дополнительные параметры, в зависимости от категории ''(см. ниже в соответствующих категориях)''. Например:
-   usercode - код абонента ''(tbl_base.CODE)''
   Пример запроса:
-  api.php?api=key&kat=abon&subkat=msg&usercode=1
+  api.php?key=apikey&cat=abon&action=msg&usercode=1
   Возвращаемые данные:
@@ Строка 28: / Строка 30: @@
      [ErrorText] => В случае ошибки - текст ошибки
     )
+ Также разумно проверять HTTP-код ответа. В случае возникновения ошибок/некорректных запросов - HTTP-код будет отличаться от 200
 == Основная настройка ==
-В основном файле конфигурации ''main/config/config.php'' добавьте ''(или настройте)'' переменную $zapikey, где укажите свой произвольный API-ключ.
+Настройте [[UserSide API Key|API-ключ]].
-= Категории =
-=== redirect ===
-Переадресация на карточку объекта по какому-то признаку
- Дополнительные параметры:
- subkat - тип объекта ''(возможное значение: abon)''
- typer - тип анализируемых данных ''(возможное значение: tel)''
- value - данные ''(текстовое значение)''
- Пример запроса:
- api.php?api=key&kat=redirect&subkat=abon&typer=tel&value=380971234567
-=== newin ===
-Форма заявки на подключение
-Пример реализации: http://userside.ua/userside/script/newin/sample.php
- Дополнительные параметры:
- subkat - подкатегория запроса ''(возможное значение: new (пустое значение этого параметра равняется new))''
- citycode - ID населенного пункта ''(tbl_adr_city.CODE)'', по которому подаётся заявка. Будет открыт выбор улиц. Если пусто - будет открыт выбор населенного пункта.
- map - флаг ''(1/0)'' - открывать ли окно выбора карты. Населенный пункт должен быть указан на карте - тогда будет понятно какую карту открывать и где её центровать.
- Пример запроса:
- api.php?api=key&kat=newin&map=1
-=== abon ===
-----
-Действия с абонентами. Большинство действий актуально для [[Поддерживаемые биллинги|ручных биллингов]].
- Дополнительные параметры:
- subkat - подкатегория запроса ''(возможное значение: см.ниже)''
- typer - тип анализируемых данных ''(возможное значение: tel)''
- value - данные ''(текстовое значение)''
- Пример запроса:
- api.php?api=key&kat=redirect&subkat=abon&typer=tel&value=380971234567
-==== abon_hist ====
- '''Подкатегория: abon_hist'''
- Описание: Вывод операций с абонентом (финансовые и прочие)
- Обязательные параметры:
-  usercode - ID абонента ''(tbl_base.CODE)''
- Дополнительно возвращаемые данные:
-  перечень тарифов
-  array(
-   [Id] - ID_ТИП операции
-   [DateDo] - дата операции
-   [OperID] - ID оператора (tbl_oper.CODE)
-   [BalansBefore] - баланс абонента до операции
-   [Amount] - сумма операции
-   [PKO] - номер приходного кассового ордера
-   [Comment] - описание операции
-   [BillingDopData] - дополнительные данные по операции из биллинга (используется при импорте данных из сторонних биллингов)
-  )
-==== input_msg ====
- '''Подкатегория: input_msg'''
- Описание: Запись сообщения от абонента
- Обязательные параметры:
-  usercode - ID абонента ''(tbl_base.CODE)''
-  msgtext - текст сообщения
- Дополнительно возвращаемые данные:
-  array(
-   [MsgId] => В случае успеха - ID сообщения (tbl_trouble.CODE)
-  )
-==== list_tarif_available ====
- '''Подкатегория: list_tarif_available'''
- Описание: Список тарифов, доступных абоненту для смены
- Обязательные параметры:
-  usercode - ID абонента ''(tbl_base.CODE)''
- Дополнительно возвращаемые данные:
-  перечень тарифов
-  array(
-   [TarifList] => array(
-    [Id] - ID тарифа (tbl_group.CODE)
-    [Name] - Название тарифа
-    [Price] - Стоимость тарифа
-    [IsDayPrice] - Флаг - ежедневная ли стоимость
-   )
-  )
-==== msg ====
- '''Подкатегория: msg'''
- Описание: Вывод переписки с абонентом
- Обязательные параметры:
-  usercode - ID абонента ''(tbl_base.CODE)''
- Дополнительно возвращаемые данные:
-  перечень тарифов
-  array(
-   [Id] - ID сообщения (tbl_trouble.CODE)
-   [DateMsg] - дата сообщения
-   [MsgTyper] - (OperMsg/UserMsg) - тип сообщения. Сообщения от абонента или от оператора
-   [Text] - текст сообщения
-   [Attach] = array( - массив с прикрепленными файлами
-    [Id] - ID файла (tbl_attach.CODE)
-    [FilePath] - URL к файлу
-    [RealName] - изначальное имя файла
-   )
-  )
-==== pass_change ====
- '''Подкатегория: pass_change'''
- Описание: Смена пароля на вход в ЛК
- Обязательные параметры:
-  usercode - ID абонента ''(tbl_base.CODE)''
-  pass_old - текущий пароль
-  pass_new - новый пароль
-==== tarif_change ====
+== Категории ==
- '''Подкатегория: tarif_change'''
+* [[API address|address]] - Адреса
- Описание: Смена тарифа абоненту
+* [[API attach|attach]] - Прикрепляемые файлы
- Обязательные параметры:
+* [[API additional_data|additional_data]] - Дополнительные поля/данные для объектов
-  usercode - ID абонента ''(tbl_base.CODE)''
+* [[API advertising|advertising]] - Рекламные кампании
-  tarif - ID нового тарифа ''(tbl_group.CODE)''
+* [[API billing|billing]] - Биллинги
+* [[API cable_route|cable_route]] - Кабельные трассы и каналы
+* [[API call|call]] - Звонки
+* [[API commutation|commutation]] - Коммутация объектов
+* [[API cross|cross]] - ODF/Кроссы
+* [[API customer|customer]] - Абоненты. Большинство действий актуально для [[Поддерживаемые биллинги|ручных биллингов]]
+* [[API device|device]] - Оборудование
+* [[API employee|employee]] - Сотрудники ''(с 3.16dev2)''
+* [[API fiber|fiber]] - Кабельные линии
+* [[API gps|gps]] - GPS-трекеры
+* [[API inventory|inventory]] - Склад
+* [[API key|key]] - Ключи
+* [[API map|map]] - Карты покрытия
+* [[API module|module]] - Внешние запросы от модулей
+* [[API newin|newin]] - Заявка на подключение
+* [[API node|node]] - Сооружения связи ''(узлы связи, муфты, опоры, колодцы)''
+* [[API notepad|notepad]] - Блокнот
+* [[API operator|operator]] - Операторы системы ''(до 3.16dev2)''
+* [[API owner|owner]] - Собственники объектов
+* [[API redirect|redirect]] - Переадресация на карточку объекта по какому-то признаку
+* [[API service|service]] - Дополнительные услуги
+* [[API setting|setting]] - Настройка
+* [[API sms|sms]] - SMS-сообщения
+* [[API splitter|splitter]] - Делители/уплотнители
+* [[API staff|staff]] - Сотрудники ''(до 3.16dev2)''
+* [[API system|system]] - Системная информация и операции
+* [[API tariff|tariff]] - Тарифы
+* [[API task|task]] - Задания
+* [[API trader|trader]] - Поставщики
+* [[API vehicle|vehicle]] - Автотранспорт
+* [[API vlan|vlan]] - Vlan