Взаимодействие через API

API (Application Programming Interface) —  интерфейс, позволяющий программам взаимодействовать друг с другом. API BILLmanager позволяет управлять платформой программно, вызывая её функции через HTTP-запросы. С помощью API можно получать данные, выполнять действия от имени пользователей, интегрироваться с внешними системами и автоматизировать задачи биллинговой платформы.

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

Управление авторизацией

Авторизация обязательна перед вызовом функций платформы.

Вы можете авторизоваться одним из методов:

• сессионная авторизация;
• авторизация с использованием функции authinfo;
• сквозная авторизация по ключу.

Сессионная авторизация

Используйте метод:

• для скриптов, которые выполняют несколько запросов к платформе;
• для обращения к платформе через браузер.

1. Отправьте GET-запрос:
   Общий вид запроса:

   https://IP-адрес:1500/billmgr?out=xml&func=auth&username=имя_пользователя&password=пароль

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой
   • out=xml — формат ответа
   • func=auth — функция авторизации
   • username=имя_пользователя — имя пользователя в BILLmanager
   • password=пароль — пароль пользователя
2. Получите XML-ответ:
   Общий вид ответа:

   <doc>
       <auth id="номер сессии" level="уровень доступа">номер сессии</auth>
   ...
   </doc>

3. Используйте полученный идентификатор в последующих запросах:
   Общий вид запроса:

   https://IP-адрес:1500/billmgr?auth=номер_сессии&out=xml&func=функция&параметр1=значение&параметр2=значение...

Сессия действует один час с момента последнего запроса. Если в течение часа не было запросов, авторизация становится недействительной — пройдите авторизацию повторно.

Авторизация с использованием функции authinfo

Используйте метод:

• для разовых запросов к платформе;
• при удалённом доступе к платформе без необходимости поддержания сессии.

Отправьте GET-запрос:

https://IP-адрес:1500/billmgr?authinfo=admin1:mypasswd&out=xml&func=функция&параметр1=значение&параметр2=значение...

Особенности метода:

• метод авторизации является разовым — передавайте параметр authinfo в каждом запросе к платформе. Сессия не создаётся и не поддерживается;
• авторизацию через authinfo можно ограничить определёнными IP-адресами и сетями.  Для этого настройте "белый список" доверенных сетей:
  • через параметры RestrictAuthinfoRange и Option RestrictAuthinfo конфигурационного файла;
  • через настройки авторизации.

Сквозная авторизация по ключу

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

Если клиент идентифицирован внешним скриптом, например, билинговой платформой, и его нужно перенаправить в BILLmanager, минуя шаг авторизации:

1. Сгенерируйте секретный ключ. Длина ключа должна быть не менее 16 символов:

   Команда для генерации секретного ключа

   pwgen -s 16 1

   Пример полученного ключа: 1234567890qwertyuiop

2. Выполните запрос:

   Общий вид запроса:

   https://IP-адрес:1500/billmgr?out=xml&authinfo=root:secret&func=session.newkey&username=alex&key=1234567890qwertyuiop

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой
   • authinfo=root:secret — учётные данные администратора BILLmanager
   • func=session.newkey — функция создания сквозного ключа авторизации
   • username=alex — логин пользователя, который будет авторизован
   • key=1234567890qwertyuiop — сгенерированный ключ
3. Получите ответ. Если ответ ok, операция успешна. В случае ошибки проверьте права администратора и корректность параметров.
4. Если ответ ok, перенаправьте пользователя на авторизацию по ключу:
   
   Общий вид запроса:

   https://IP-адрес:1500/billmgr?func=auth&username=alex&key=1234567890qwertyuiop&checkcookie=no

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой
   • func=auth — функция авторизации
   • username=alex — логин пользователя
   • key=1234567890qwertyuiop — ранее сгенерированный ключ
   • checkcookie=no — отключение проверки cookies

После перехода по URL пользователь будет автоматически авторизован в платформе, а использованный ключ удалён.

Ключ является одноразовым. Установить ключ можно с любого IP-адреса. При использовании метода для пользователя действуют ограничения на вход по IP-адресу. Авторизоваться с неразрешенного IP, используя ключ, нельзя.

Завершение сессии пользователя

Принудительное завершение сессии применяется для:

• обеспечения безопасности — при обнаружении несанкционированного или подозрительного доступа к платформе;
• административного управления — когда требуется немедленно прекратить активную сессию пользователя. Например:
  • после отзыва доступа;
  • при блокировке учётной записи;
• отладки и тестирования — при разработке интеграций или внешних модулей, где необходимо контролировать состояние сессий.

Чтобы завершить сессию пользователя, выполните API-запрос:

https://IP-адрес:1500/billmgr?func=session.delete&elid=`номер сессии`&sok=ok

Вы можете просмотреть текущие активные сессии одним из способов:

• в веб-интерфейсе платформы перейдите в раздел Состояние системы → Активные сессии;
• в базе данных платформы выполните запрос к таблице core_session:
  

  SELECT * FROM core_session WHERE status = 'active';

Формат запросов и результатов

Формат запросов к API BILLmanager

Для отправки API-запросов к BILLmanager используйте HTTP-методы GET и POST.

Запрос состоит из следующих частей:

• функция — имя функции, которое необходимо передать в параметре func запроса. Например, pricelist, auth, session.delete;
• параметры — список параметров в формате параметр=значение. Например, elid=12345.

https://IP-адрес:1500/billmgr?func=имя_функции&параметр1=значение1&параметр2=значение2...

В зависимости от типа функции существует несколько видов результата:

• список элементов (таблица);
• список параметров объекта (форма);
• успешное выполнение операции (действие);
• сообщение об ошибке.

Формат вывода результатов

Вы можете получить вывод функции в формате XML, текстовом формате и в формате JSON. Чтобы задать формат получения результатов, укажите в запросе параметр out=имя_формата.

Поддерживаемые значения параметра out:

Если параметр out не указан, платформа возвращает ответ в формате HTML, предназначенном для отображения в браузере.

Список элементов (таблица)

Возвращает таблицу объектов — например, список пользователей или тарифов. XML-документ имеет вид:

<doc>
    <elem>параметры элемента в списке</elem>
    <elem>параметры элемента в списке</elem>
    ...
    <elem>параметры элемента в списке</elem>
</doc>

В результате функции описываются только те параметры элемента списка, которые могут различаться между элементами. Каждый параметр представлен одним или несколькими XML-узлами — с атрибутами и значениями. Всё остальное, что одинаково для всех элементов, в описание не включается — оно подразумевается общим для всей структуры. Например:

<doc>
    <elem>
        <elid>5001</elid>
        <date>2024-04-10</date>
        <sum>1500.00</sum>
        <currency>RUB</currency>
        <status>processed</status>
        <account>1024</account>
        <paymethod>bank_transfer</paymethod>
    </elem>
    <elem>
        <elid>5002</elid>
        <date>2024-04-12</date>
        <sum>750.50</sum>
        <currency>RUB</currency>
        <status>pending</status>
        <account>1025</account>
        <paymethod>credit_card</paymethod>
    </elem>
</doc>

Ответ содержит поля <date>, <currency> и другие, содержащиеся внутри <elem>, но не содержит поля, одинаковые для всех элементов списка.

Cписок параметров объекта (форма)

Возвращает данные одного объекта — например, при редактировании. XML-документ имеет вид:

<doc>
    <elid>уникальный идентификатор объекта</elid>
    параметры объекта
</doc>

В качестве результата функции описываются только параметры объекта. Параметры объекта представляют собой один или несколько XML-узлов с возможными атрибутами и значениями, описывающие свойства данного объекта. Например:

<doc>
    <elid>1024</elid>
    <username>jackblack</username>
    <<email>client567@example.com</email>
    <project>2,3,1</project>
    <client_lang>ru</client_lang>
    <country>182</country>
    <state></state>
    <realname>Иван Петров</realname>
    <employee>1</employee>
    <note></note>
    <notify>off</notify>
    <recovery>off</recovery>
    <status>active</status>
    <created>2024-04-15</created>
</doc>

Успешное выполнение операции (действие)

Подтверждает, что действие выполнено. Результат выдаётся при создании, изменении, удалении, включении или выключении объекта. XML-документ имеет вид:

<doc>
    <ok/>
</doc>

Сообщение об ошибке

Возвращает описание ошибки при некорректном запросе. XML-документ имеет вид:

<doc>
  <error type="exists" object="user" lang="ru">
    <param name="object" type="msg" msg="Пользователь">user</param>
    <param name="value">ben</param>
    <stack>
      <action level="30" user="jen">admin.edit</action>
    </stack>
    <group>__object__ со значением '__value__' уже существует</group>
    <msg>Пользователь со значением 'ben' уже существует</msg>
  </error>
</doc>

Способы формирования API-запроса

Список функций и параметров

Вы можете посмотреть полный список функций платформы и их параметров см. в статье Перечень API-функций. Также актуальная информация доступна на сервере с платформой.

Чтобы получить полный список функций BILLmanager, используйте команду:

/usr/local/mgr5/sbin/mgrctl -m billmgr -i

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

/usr/local/mgr5/sbin/mgrctl -m billmgr -i user lang=ru

Также вы можете определить нужную функцию через API-запрос или URL.

Составление API-запроса по логу

Чтобы составить API-запрос, выполните действие в интерфейсе BILLmanager и посмотрите функцию и параметры в логе:

1. Откройте лог-файл панели с помощью команды tail:

   Команда открытия лога

   tail -f /usr/local/mgr5/var/billmgr.log | grep Request

2. Выполните нужное действие в интерфейсе BILLmanager. В открытом лог-файле будет видна выполняемая функция и её параметры (начинается с INFO Request).
   Например, создание доменного имени (DNS) в логе BILLmanager выглядит следующим образом:

   Пример информации в лог-файле

   Feb  6 08:08:07 [2346:23826] core_module INFO Request [188.120.252.33][root] 'clicked_button=ok&email_inaccess=&func=domain.edit&ip=8.8.8.8&ip_existing=&maildomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&operafake=1486357687433&owner=www%2Droot&owner_admins=off&progressid=false&reversezone=&sfrom=ajax&sok=ok&web_inaccess=&webdomain=off&zoom-ip=&zoom-ns='

3. Составьте API-запрос на основе функции, полученной в логе функции. Подробнее см. раздел этой статьи Формат запросов к API BILLmanager .

   Формат API-запроса

   https://IP-адрес:1500/billmgr??func=<функция>&<параметр 1>=<значение>&<параметр 2>=<значение>...

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой

   Чтобы получить API-запрос, исключите из запроса:

   1. необязательные параметры:

      1. sfrom.
      2. progressid.
   2. параметры, равные знаку *. Обычно данные, которые не должны отображаться в логе. Например,  если в запросе есть password=*, заменить * на нужное значение.

   3. параметры с пустыми значениями.

      Пример запроса

      https://123.123.123.123:443/billmgr?auth=a4b9816e498e&func=domain.edit&ip=8.8.8.8&maildomain=off&webdomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&owner=www%2Droot&sok=ok&out=xml

Получение данных из URL

Чтобы получить нужную функцию и значения её параметров, изучите URL-адрес формы в биллинговой платформе.

Например, чтобы определить URL-адрес для конкретного платежа, перейдите в раздел Клиенты → Клиенты → выберите клиента → кнопка Платежи → выберите платёж → кнопка Изменить. URL-адрес формы изменения платежа будет иметь вид:

https://IP-адрес:1500/billmgr?func=payment.edit&elid=1256&elname=pfx%2F1256&plid=334

Чтобы получить ссылку, нажмите значок  рядом с заголовком раздела.

Особенности работы

Вызов функций с правами другого пользователя

Чтобы обратиться к функции BILLmanager от имени другого пользователя, добавьте к запросу параметр su=логин_пользователя.

Права доступа:

• администратор платформы — может вызывать функции с правами любого пользователя платформы;
• клиент с полными правами — может вызывать функции только с правами своих клиентов;
• остальные роли — не имеют права использовать параметр su.

https://IP-адрес:1500/billmgr?auth=токен&func=user.info&su=целевой_пользователь&out=xml

Получение результатов на на определённом языке

Чтобы получить результат выполнения функции или сообщение об ошибке на определённом языке, добавьте к запросу параметр:  lang=код_языка. Например lang=ru или lang=en. Если указан несуществующий или неподдерживаемый код языка, будет использован язык по умолчанию.

Локальные обращения к платформе

Чтобы выполнять API-запросы к платформе локально — из скриптов или shell  — рекомендуется использовать утилиту mgrctl. Преимущества mgrctl:

• прямое обращение к ядру платформы — минует веб-сервер, не зависит от его состояния и настроек;
• автоматическая авторизация — запросы выполняются от имени пользователя, запустившего команду. Хранить пароли не требуется. Чтобы выполнить действия от имени другого пользователя используйте параметр su=логин сотрудника. Подробнее см. раздел Вызов функций с правами другого пользователя;
• встроенная справка — описание всех функций и их параметров, актуальное для используемого сервера.

Подробнее см. в статье Утилита mgrctl.

Подтверждение операции

Чтобы применить изменения, переданные в запросе, добавьте к запросу параметр sok=ok. Параметр sok=ok в запросе эмулирует нажатие на кнопку подтверждения в веб-интерфейсе — Ок, Применить, В корзину и т.д.

Отправка запроса без параметра sok=ok равносильна простому открытию формы. Запрос возвращает форму для редактирования или текущие значения параметров — изменения не применяются. 

Параметр не требуется:

• в запросах на чтение данных. Например, получение текущих значений, просмотр объекта;
• в функциях, которые не реализованы как формы. Например, массовые операции.

https://IP-адрес:1500/billmgr?func=invoice.generate&company=12&gentype=all&fromdate=2025-03-31&todate=2025-09-30&sok=ok

Переадресация

Чтобы после выполнения запроса — обычно это запрос авторизации или регистрации, который содержит sok=ok — осуществлялась переадресация на другую форму, добавьте к запросу параметр redirect=startform=some.form, где some.form — API-функция нужной формы. Подробнее см. Перечень API-функций.

Параметр redirect применяется:

• после успешного выполнения запроса, обычно содержащего sok=ok;
• в первичных запросах, где sok=ok не используется. Например, func=register (регистрация) и func=logon (авторизация). 

Значение параметра startform=some.form должно быть URL-encoded, то есть специальные символы (пробел, =, & и т.д.) должны быть заменены на последовательность вида %XX, где XX — шестнадцатеричный код символа. Например, startform=some.form должно быть заменено на startform%3Dsome.form. 

https://IP-адрес:1500/billmgr?func=modifying.action&sok=ok&redirect=startform%3Dsome.form

Примеры получения списка тарифов

В качестве примера рассматривается получение списка тарифов. Остальные функции можно вызывать аналогичным образом. Замените IP-адрес сервера, логин и пароль, указанные в примерах, на реальные данные.

Утилита curl

curl -k -s "https://IP-адрес:1500/billmgr?authinfo=логин:пароль&out=xml&func=pricelist"

Утилита mgrctl

/usr/local/mgr5/sbin/mgrctl -m billmgr pricelist

Язык Perl

Для обращения по URL из Perl необходимо установить библиотеку LWP. Для работы с XML-документами требуется библиотека XML::LibXML.

#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";

use LWP::UserAgent;
use XML::LibXML;

my $result;

# Создадим псевдобраузер, который будет "притворяться" MSIE и отправим запрос
$ua = LWP::UserAgent->new;
$ua->agent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
my $req = HTTP::Request->new(POST => 'https://IP-адрес:1500/billmgr');

$req->content("authinfo=логин:пароль&out=xml&func=pricelist");

my $res = $ua->request($req);

# Проверим результат
if ($res->is_success) {
    $result = $res->content;
} else {
    die $res->status_line."\n";
}

# После этого переменная $result будет содержать XML-документ со списком тарифов, либо сообщение об ошибке

my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();

# Получим список имён тарифов
my @tariffs = ();
for( $root->findnodes( "elem/name" ) ){
    push @tariffs, $_->textContent;
}

# Выведем результат на экран
for( sort @tariffs ){
    print $_."<br>\n";
}

Язык PHP

Язык PHP предоставляет возможность работы с URL как со стандартными файлами. Для обработки XML-документов используется библиотека DOM XML.

<?php
   $result = "";
   $fh = fopen( "http://IP-ADDR:1500/billmgr?authinfo=логин:пароль&out=xml&func=pricelist", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );

   // После этого переменная $result будет содержать XML-документ со списком тарифов,
   // либо сообщение об ошибке

   $doc = new DOMDocument();
   if( $doc -> loadXML( $result ) ){
       $root = $doc->documentElement;
       foreach ( $root->childNodes as $elem ){
           foreach ($elem->childNodes as $node){
               if( $node->tagName == "name" ){
                   echo $node->nodeValue;
                   echo "\n";
               }
           }
       }
   }
?>

Язык Python

Для обращения по URL из Python используется библиотека urllib2. Для работы с XML-документами — библиотека xml.dom.minidom.

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from urllib2 import urlopen
from xml.dom import minidom

print "Content-type: text/html\n\n"
res = urlopen('http://IP-ADDR:1500/billmgr?authinfo=логин:пароль&func=pricelist&out=xml')

# После этого переменная res будет содержать XML-документ со списком тарифов,
# либо сообщение об ошибке

xmldoc = minidom.parse(res)

# Получим список имён тарифов и выводим его результат на экран

for node in xmldoc.getElementsByTagName('elem'):
        for name in node.getElementsByTagName('name'):
                print ('%s<br>' % name.firstChild.nodeValue)