Огляд 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.