Обзор API

В FlySIP есть XML-RPC API для всего, что вы делаете в панели: клиенты, аккаунты, вендоры, тарифы, маршрутизация, DID, платежи, CDR. Используйте его, чтобы создавать объекты из своей биллинговой системы или CRM, продавать с веб-сайта и забирать записи о звонках в свою отчётность. Каждый вызов выполняется от имени одного клиента и видит только то, что этот клиент видит в панели.

Включение доступа к API

Вызовы API аутентифицируются по Web Login (веб-логин) клиента и отдельному API Password (пароль API).

1. Откройте My Preferences (мои настройки), чтобы пользоваться API от своего имени, или откройте клиента в My Customers → Customers, чтобы дать доступ реселлеру.
2. Введите API Password и отметьте Allow API Calls (разрешить вызовы API).
3. Нажмите Save.

Эти поля видны, только когда ваш логин имеет права на управление API. Клиент без Allow API Calls получает ошибку аутентификации на каждый вызов.

Осторожно

Пароль API даёт всё, что клиент может делать в панели, включая платежи и удаление аккаунтов. Используйте отдельного реселлера только с теми объектами, которые нужны интеграции, и не храните пароль в коде, который выполняется в браузере.

Endpoint и аутентификация

https://<your-panel-host>/xmlapi/xmlapi

• Транспорт: HTTPS POST с Content-Type: text/xml.
• Аутентификация: HTTP Digest. Имя пользователя - Web Login клиента, пароль - API Password. Basic-аутентификация не принимается.
• Область действия: аутентифицированный клиент. Методы работают с его собственными объектами и его субклиентами; объекты других клиентов возвращаются как не найденные.

Проверьте учётные данные с помощью curl. Рабочий вызов возвращает до пяти ваших аккаунтов:

curl --digest -u acme-web:API-PASSWORD -H 'Content-Type: text/xml' \
  --data '<?xml version="1.0"?><methodCall><methodName>listAccounts</methodName><params><param><value><struct><member><name>limit</name><value><int>5</int></value></member></struct></value></param></params></methodCall>' \
  https://panel.example.com/xmlapi/xmlapi

Trusted mode

Вызовы от самого коммутатора и от хостов, которым коммутатор доверяет, принимаются без digest-аутентификации. Такой вызов не определяет клиента, поэтому методы с поддержкой trusted mode принимают дополнительный параметр с клиентом, от имени которого действовать: обычно i_customer, а для некоторых методов i_wholesaler. Страницы методов упоминают это там, где оно применяется. Внешние интеграции всегда используют digest-аутентификацию и никогда не нуждаются в этих параметрах.

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

Каждый метод принимает ровно один параметр типа struct и возвращает struct. Имена параметров чувствительны к регистру и записываются в snake_case; внутренние ID начинаются с i_, например i_account, i_customer, i_tariff. Большинство методов также принимают l10n_lang - двухбуквенный код языка, например en или ru, который задаёт язык сообщений об ошибках.

<?xml version="1.0"?>
<methodCall>
  <methodName>getAccountInfo</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>i_account</name>
            <value><int>3092</int></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Параметр типа array - это список значений внутри <array><data>:

<member>
  <name>target_hosts</name>
  <value><array><data>
    <value><string>192.0.2.10</string></value>
    <value><string>192.0.2.11</string></value>
  </data></array></value>
</member>

Чтобы отправить несколько вызовов одним HTTP-запросом, используйте system.multicall. См. Batch calls with multicall.

Формат ответа

Успешный вызов возвращает struct, в котором result равен OK, и собственные поля метода. Несколько методов отличаются: одни возвращают status вместо result, другие - только свои данные без этих полей; их страницы об этом говорят. Типичный ответ:

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member><name>result</name><value><string>OK</string></value></member>
          <member><name>i_account</name><value><int>3092</int></value></member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>

Пустые значения могут возвращаться как <nil/>. Убедитесь, что ваша клиентская библиотека их принимает: в Apache XML-RPC для Java вызовите setEnabledForExtensions(true) в конфигурации клиента.

Fault-ошибки

Неудачный вызов возвращает XML-RPC fault вместо результата. faultString - понятное сообщение для журнала; faultCode указывает класс проблемы.

<?xml version="1.0"?>
<methodResponse>
  <fault>
    <value>
      <struct>
        <member><name>faultCode</name><value><int>401</int></value></member>
        <member><name>faultString</name><value><string>Wrong i_tariff</string></value></member>
      </struct>
    </value>
  </fault>
</methodResponse>

faultCode	Значение
400	Не хватает обязательного параметра, параметры противоречат друг другу, или объект нельзя изменить таким образом
401	Параметр имеет неверное значение, клиенту не разрешено вызывать метод, или объект не найден
402	Неверные входные данные: не хватает поля, неизвестное значение, неверная дата
403, 404	Объект не существует или принадлежит другому клиенту
408	Операция превысила время ожидания на коммутаторе
410	В некоторых методах не хватает обязательного параметра, или сервис временно недоступен; страница метода поясняет, что именно
500	Внутренняя ошибка; повторите позже и сообщите, если она не исчезает

Коды не уникальны для каждой ошибки, а старые методы часто возвращают 401 для «не найдено», поэтому записывайте faultString в журнал и не стройте логику на тонких различиях между кодами. HTTP-ответ 401, а не fault, означает, что digest-учётные данные отклонены.

Осторожно

Не повторяйте вслепую неудачный вызов createCustomer, createAccount или платёжного метода. Сначала проверьте, не создан ли объект или платёж, например через getAccountInfo по username, чтобы избежать дубликатов.

Типы данных

Тип XML-RPC	Для чего
int	ID (i_*), счётчики, перечисления
double	Деньги и ставки, например balance, credit_limit, price_1
string	Названия, номера, пароли, регулярные выражения
boolean	Флаги. Многие старые методы также принимают int 0 / 1 для флагов
dateTime.iso8601	Даты и время, всегда в UTC, без часового пояса: 20260115T13:30:00
array, struct	Списки и вложенные объекты
base64	Двоичные данные, например запись разговора

Коды стран - ISO 3166 (TR или TUR), коды валют - ISO 4217 (USD, EUR, TRY). Балансы указываются в валюте клиента или аккаунта.

Вызов API из Python

Стандартный модуль xmlrpc.client не поддерживает digest-аутентификацию, поэтому примеры на этих страницах используют эту вспомогательную функцию на основе requests:

flysip_api.py

import xmlrpc.client

import requests
from requests.auth import HTTPDigestAuth

URL = "https://panel.example.com/xmlapi/xmlapi"
AUTH = HTTPDigestAuth("acme-web", "API-PASSWORD")


def call(method: str, params: dict) -> dict:
    """Call one API method; raises xmlrpc.client.Fault on a fault."""
    body = xmlrpc.client.dumps((params,), method, allow_none=True)
    resp = requests.post(URL, data=body.encode(), auth=AUTH,
                         headers={"Content-Type": "text/xml"}, timeout=30)
    resp.raise_for_status()
    return xmlrpc.client.loads(resp.content, use_builtin_types=True)[0][0]


print(call("getAccountInfo", {"username": "1001"}))

xmlrpc.client отправляет Python-типы int, float, str, bool, datetime, list и dict как соответствующие типы XML-RPC. Если у панели самоподписанный сертификат, передайте файл её CA в requests.post(..., verify="flysip-ca.pem"), а не отключайте проверку. Более длинный пример - в Python client.

Заметка

Apache XML-RPC для Java не выполняет digest-аутентификацию со стандартным транспортом java.net.URLConnection. Используйте транспорт на основе Apache HttpClient.

Методы

Группа	Чем вы управляете
Accounts	Аккаунты и их правила аутентификации, доверенные номера, follow-me, hot dial, smart dial, транки, входящие маршруты
Customers	Клиенты и реселлеры, их вход и блокировка
Vendors	Вендоры, их подключения и балансы
Tariffs	Тарифы и их ставки
CDRs	Записи о звонках аккаунтов, клиентов и вендоров, поиск звонков с диагностикой, записи разговоров
Reports	Сводные отчёты по аккаунтам, клиентам, вендорам и DID, а также предварительно агрегированная статистика
Payments	Платежи, возвраты, ваучеры, сохранённые карты, предупреждения о низком балансе
Environments	Среды мультитенантного коммутатора
Other methods	DID, наборы направлений, группы маршрутизации, IVR, активные звонки, сертификаты, правила фаервола, политики паролей, системные настройки

Массовая загрузка ставок и маршрутов выполняется через binary upload. Для простых HTTP GET-интеграций без XML-RPC см. Simple API.