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

Материал из WiKi - UserSide
 
(не показано 66 промежуточных версий 4 участников)
Строка 1: Строка 1:
Этот раздел описывает возможности использования встроенного API в ERP "UserSide", что позволяет использовать встроенный функционал в собственных проектах.
[[API_EN|en]] | [[API|ru]]
 
Этот раздел описывает возможности использования встроенного API в ERP "UserSide", что позволяет использовать встроенный функционал в собственных проектах.  


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


За взаимодействие отвечает файл /api.php
За взаимодействие отвечает файл /api.php
Можно использовать и GET и POST запросы.


  Входящие параметры:
  Входящие параметры:
Строка 11: Строка 15:
   key - ключ API
   key - ключ API
   cat - категория запроса
   cat - категория запроса
  Возможные:
  Необязательные:
   cp - кодировка ''(возможное значение: cp1251)''. По-умолчанию данные возвращаются в кодировке utf8.
   skip_internal_api - флаг - не включать внутренние триггеры системы ''(разумно использовать, когда ваш метод API и есть реакция на какой-то триггер и в итоге при обычной работе он же сам и зацикливает свою работу)''
  gz - возврат данных в сжатом формате ''(возможное значение: disable)''. По-умолчанию данные возвращаются в сжатом формате.
Прочие дополнительные параметры, в зависимости от категории ''(см. ниже в соответствующих категориях)''. Например:
  subcat - подкатегория запроса
  customer_id - id абонента
  sort_desc - обратная сортировка результата запроса ''(Возможное значение: 1)''
  is_potential - флаг. Может принимать значение 1 или 0. Большинство флагов имеют префикс '''is'''.
  Прочие дополнительные параметры, в зависимости от категории ''(см. ниже в соответствующих категориях)''. Например:
  usercode - код абонента ''(tbl_base.CODE)''
   
   
  Пример запроса:
  Пример запроса:
  api.php?key=apikey&cat=abon&subcat=msg&usercode=1
  api.php?key=apikey&cat=abon&action=msg&usercode=1


  Возвращаемые данные:
  Возвращаемые данные:
Строка 28: Строка 30:
     [ErrorText] => В случае ошибки - текст ошибки
     [ErrorText] => В случае ошибки - текст ошибки
   )
   )
Также разумно проверять HTTP-код ответа. В случае возникновения ошибок/некорректных запросов - HTTP-код будет отличаться от 200


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


В основном файле конфигурации ''main/config/config.php'' добавьте ''(или настройте)'' переменную $zapikey, где укажите свой произвольный API-ключ.
Настройте [[UserSide API Key|API-ключ]].
 
= Категории =
=== address ===
----
 
Действия с адресами.
 
Дополнительные параметры:
action - подкатегория запроса ''(возможное значение: см.ниже)''
 
==== add_city ====
Описание: Добавление населенного пункта
Обязательные параметры:
  name - Наименование населенного пункта
Дополнительно возвращаемые данные:
  array(
  [Id] => ID нового абонента в случае успеха
  )
 
=== abon ===
----
 
Действия с абонентами. Большинство действий актуально для [[Поддерживаемые биллинги|ручных биллингов]].
 
Дополнительные параметры:
subcat - подкатегория запроса ''(возможное значение: см.ниже)''
 
==== abon_add ====
'''Подкатегория: abon_add'''
Описание: Добавление абонента
Обязательные параметры:
  codeti - ID абонента по версии биллинга
  fio - ФИО абонента
Дополнительно возвращаемые данные:
  array(
  [Id] => ID нового абонента в случае успеха
  )
 
==== abon_hist ====
'''Подкатегория: abon_hist'''
Описание: Вывод операций с абонентом (финансовые и прочие)
Обязательные параметры:
  usercode - ID абонента ''(tbl_base.CODE)''
Дополнительно возвращаемые данные:
  перечень тарифов
  array(
  [Id] - ID_ТИП операции
  [DateDo] - дата операции
  [OperID] - ID оператора (tbl_oper.CODE)
  [BalansBefore] - баланс абонента до операции
  [Amount] - сумма операции
  [PKO] - номер приходного кассового ордера
  [Comment] - описание операции
  [BillingDopData] - дополнительные данные по операции из биллинга (используется при импорте данных из сторонних биллингов)
  )
 
==== get_abon_id ====
'''Подкатегория: get_abon_id'''
Описание: Получение ID абонента по входящим данным
Обязательные параметры:
  data_typer - тип данных, которые проверяем (Возможные значения: codeti, dognumber, ip)
  data_value - значение
Дополнительно возвращаемые данные:
  array(
  [Id] => ID абонента в случае успеха
  )
 
==== 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'''
Описание: Смена тарифа абоненту
Обязательные параметры:
  usercode - ID абонента ''(tbl_base.CODE)''
  tarif - ID нового тарифа ''(tbl_group.CODE)''
 
 
=== newin ===
----
Форма заявки на подключение
 
Пример реализации: http://userside.ua/userside/script/newin/sample.php
 
Дополнительные параметры:
subcat - подкатегория запроса ''(возможное значение: new (пустое значение этого параметра равняется new))''
citycode - ID населенного пункта ''(tbl_adr_city.CODE)'', по которому подаётся заявка. Будет открыт выбор улиц. Если пусто - будет открыт выбор населенного пункта.
cityignore - ID населенных пунктов ''(tbl_adr_city.CODE)'', которые требуется игнорировать и не предлагать в выборе. Несколько населенных пунктов - через запятую.
map - флаг ''(1/0)'' - открывать ли окно выбора карты. Населенный пункт должен быть указан на карте - тогда будет понятно какую карту открывать и где её центровать.
Пример запроса:
api.php?key=apikey&cat=newin&map=1
 
=== redirect ===
----
Переадресация на карточку объекта по какому-то признаку
 
Дополнительные параметры:
subcat - тип объекта ''(возможное значение: abon, switch)''
typer - тип анализируемых данных ''(возможное значение: для abon: tel, ip, dognumber; для switch: ip)''
value - данные ''(текстовое значение)''
Пример запроса:
api.php?key=apikey&cat=redirect&subcat=abon&typer=tel&value=380971234567
 
=== work ===
----
 
Работа с заданиями.
 
Дополнительные параметры:
subcat - подкатегория запроса ''(возможное значение: см.ниже)''
 
==== add ====
'''Подкатегория: add'''
Описание: Создание задания
Обязательные параметры:
  work_typer - ID ТИПА задания (tbl_conf_journal.TYPER)
  work_datedo - дата на которую назначено выполнение задания (в формате ГГГГ-ММ-ДД чч:мм:сс)
Необязательные параметры:
  usercode - ID абонента (tbl_base.CODE)
  uzelcode - ID узла связи/муфты/опоры/колодца (tbl_uzel.CODE)
  housecode - ID дома (tbl_house.CODE). Если не указан, то берётся из данных по абоненту - usercode, либо из данных по узлу связи - uzelcode
  citycode - ID населенного пункта (tbl_adr_city.CODE). Если не указан, то берётся из данных по дому housecode
  apart - номер квартиры
  fio - ФИО клиента (имеется в виду, что "клиент" еще не является абонентом)
  opis - заметки к заданию
  dopf_N - значение дополнительного поля для поля ID N (tbl_conf_attr.CODE)


Дополнительно возвращаемые данные:
== Категории ==
  array(
* [[API address|address]] - Адреса
  [Id] => ID созданного задания (tbl_journal.CODE)
* [[API attach|attach]] - Прикрепляемые файлы
  )
* [[API additional_data|additional_data]] - Дополнительные поля/данные для объектов
* [[API advertising|advertising]] - Рекламные кампании
* [[API billing|billing]] - Биллинги
* [[API cable_route|cable_route]] - Кабельные трассы и каналы
* [[API call|call]] - Звонки
* [[API commutation|commutation]] - Коммутация объектов
* [[API cross|cross]] - ODF/Кроссы
* [[API customer|customer]] - Абоненты. Большинство действий актуально для [[Поддерживаемые биллинги|ручных биллингов]]
* [[API cwdm|cwdm]] - CWDM
* [[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

Текущая версия от 14:38, 16 августа 2024

en | ru

Этот раздел описывает возможности использования встроенного 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 - Абоненты. Большинство действий актуально для ручных биллингов
  • cwdm - CWDM
  • 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
Источник — https://wiki.userside.eu/index.php?title=API&oldid=19370