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

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

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

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

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

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

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

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

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

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

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

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

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

   BASH
   Подробнее

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

   • out=xml — формат ответа

   • func=auth — функция авторизации
   • username=имя_пользователя — имя пользователя в BILLmanager
   • password=пароль — пароль пользователя
2. Получите XML-ответ:

   Общий вид ответа:

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

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

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

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

   BASH

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

Уровень доступа пользователя должен быть достаточным для выполнения операций. Если уровень доступа ниже требуемого, то операция завершится с ошибкой либо вернёт неполные данные. Подробнее об уровнях доступа см. в статье Сотрудники, отделы, права доступа.

Авторизация с использованием функции 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

   CODE

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

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

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

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

   BASH
   Подробнее

   • 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

   BASH
   Подробнее

   • 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';

  SQL

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

Формат запросов к 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>

Запросы на удаление возвращают код ответа 200, даже если запись не найдена. Чтобы проверить, что запись удалена, вы можете отправить запрос на редактирование записи. Если запись удалена, запрос вернёт сообщение об ошибке.

Запросы на редактирование платежа, привязанного к услуге, возвращают код ответа 200. Параметры платежа при этом не меняются.

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

Возвращает описание ошибки при некорректном запросе. 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

   BASH

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='

   BASH

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

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

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

   BASH
   Подробнее

   • 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

      BASH

Получение данных из 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)

Может быть полезно

Связанные статьи:

• Сотрудники, отделы, права доступа
• Конфигурационный файл
• Настройки авторизации
• Перечень API-функций
• Утилита mgrctl