====== XMLAgent ======

Для зовнішніх програм, що взаємодіють з [[userstats|кабінетом користувача]], підтримується окреме REST API. \\
Починаючи з релізу 1.4.5 **XMLAgent REST API** тепер винесено у окремий клас і додано багацько нових викликів.

Приклади URL для створення запитів до **XMLAgent REST API** (детальніше дивіться в описі кожного запиту нижче):

  * **?xmlagent=true** - нутрощі користувача
  * **?xmlagent=true&payments=true** - попередні оплати користувача
  * **?xmlagent=true&announcements=true** - активні(публічні) оголошення кабінету користувача
  * **?xmlagent=true&tickets=true** - всі тікети користувача та відповіді на них
  * **?xmlagent=true&opayz=true** - доступні користувачу онлайнові платіжні засоби
  * **?xmlagent=true&agentassigned=true** - дані контрагента, асоційованого з користувачем 
  * **?module=creditor&agentcredit=true&justcheck=true** - просто перевірити можливість встановлення кредиту
  * **?module=creditor&agentcredit=true** - попросити кредит на декілька днів
  * **?module=paycards&agentpaycards=true&paycard=cardnumber** - поповнити рахунок карткою поповнення з номером cardnumber


За замовчуванням, відповіді XMLAgent, історично, будуть повернуті у вигляді **XML-документу**. \\
Для отримання даних у вигляді **JSON-документу** просто додайте GET параметр **json=true**.


====== Авторизація ======

У випадку, якщо ви не хочете покладатися на примусову авторизацію користувачів за їх IP, наприклад використовуючи ваш додаток поза мережею, ви можете використовувати примусову авторизацію конкретного користувача прямим вказанням логіну та MD5 хешу паролю для всіх запитів у вигляді наступних GET змінних:

  * **uberlogin**
  * **uberpassword**


І як приклад авторизації користувача з логіном //gen_vj7iyagnzj// та паролем //codr52mv//

<code>
?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84
</code> 

Починаючи з релізу 1.4.7 доступний додатковий базовий рівень так званої "розширеної" аутентифікації, яка використовує **MD5 хеш серійного номеру вашого інстансу UB** як додатковий аутентифікаційний токен, на кшталт [[remoteapi|RemoteAPI]]. Стан ввімкненості розширеної аутентифікації керується опцією [[userstats|userstats.ini]] - [[userstats#xmlagent_extended_auth_on|XMLAGENT_EXTENDED_AUTH_ON]]. \\
Аутентифікаційний токен передається відповідним GET-параметром **uberkey**. \\
Виглядає це все загалом якось так:
<code>
?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84&uberkey=6fde545feaaba6952d9cdba84ad26475
</code> 
Так, як бачимо авторизація за логіном/паролем користувача та розширена аутентифікація доволі чудово собі співіснують в рамках одного запиту. \\
Слід лише мати на увазі, що **авторизація за логіном/паролем користувача** є дещо опціональною і її вимагають далеко не всі запити - на відміну від **розширеної аутентифікації**, ввімкнення якої **зобов'язує** вас використовувати аутентифікаційний токен абсолютно для кожного запиту.

У разі помилки авторизації, ви отримаєте відповідь у вигляді прямого рядка

<code>
ERROR_WRONG_UBERAUTH
</code>

з HTTP кодом 401 (починаючи з релізу Ubilling 1.2.7)

Примусова авторизація має пріоритет перед усіма стандартними типами авторизації, такими як ip,login,both.

Також ви можете автоматично авторизувати користувача у [[wolfdispatcher|вашому Telegram-боті]], використовуючи посилання вигляду

<code>
https://t.me/yourbot/?start=логін_користувача-md5_хеш_паролю
</code>

Так, розділювач - символ "-". Вони можуть автоматично генеруватися кабінетом.

====== Трохи про "сесуріті" ======
Невелика порція рекомендацій, які "і так всі знають" - але хрін хто виконує, да. Більшість з них мають починатись зі слів, на кшталт "Завжди пам'ятайте ....", або "Майте на увазі: ....", чи "Не забувайте, що ...." - але ми їх опустимо, бо, погодьтеся, читати їх в кожному рядку - те ще задволення, враховуючи який непосильний труд для більшості людей читати доку взагалі...
  * не треба вмикати XMLAgent "просто так" і забувати про нього - потренувались?, більше не треба? - вимкніть 
  * поточне REST API може працювати без авторизаці, а значить, теоретично, доступ до певних даних вашої БД може отримати будь-хто
  * не треба занадто самовпевнено думати, що "тааа - мій **userstats** за NATом - шо там мені загрожує?" - бо це не так
  * ніколи не відкривайте XMLAgent "просто в світ" - як мінімум - налаштуйте allowed хости/IP на своєму веб сервері та/або фаєрволі, з яких буде дозволено робити запити до вашого XMLAgent. Можна ще й **reverse-proxy** заюзати - лишнім не буде

====== Приклади запитів та відповідей ======

===== Загальні дані користувача =====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true</code>

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<userdata>
	<address>Зловісненськ Шевченка 56/1</address>
	<realname>Федір Крюгер</realname>
	<login>zlo_hev11ap8_0nt6</login>
	<cash>315</cash>
	<ip>172.30.0.2</ip>
	<phone>26666</phone>
	<mobile>0506661488</mobile>
	<email>fred@ourisp.ua</email>
	<credit>0</credit>
	<creditexpire>No</creditexpire>
	<payid>2887647234</payid>
	<contract>666</contract>
	<tariff>Unlim-100</tariff>
	<tariffnm>No</tariffnm>
	<traffdownload>0 b</traffdownload>
	<traffupload>0 b</traffupload>
	<trafftotal>0 b</trafftotal>
	<accountstate>active</accountstate>
	<accountexpire>102</accountexpire>
	<currency>UAH</currency>
	<version>1</version>
</userdata>

</code>
\\

===== Загальні дані користувача але з примусовою авторизацією =====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84</code>

<code xml> 
<?xml version="1.0" encoding="utf-8"?>
<userdata>
  <address>Зловісненськ В`язів 56/36</address>
  <realname>Герасим Герасименко</realname>
  <login>gen_vj7iyagnzj</login>
  <cash>0</cash>
  <ip>172.30.0.37</ip>
  <phone>866270</phone>
  <mobile>3808268045</mobile>
  <email/>
  <credit>0</credit>
  <creditexpire>No</creditexpire>
  <payid>3055434878</payid>
  <contract/>
  <tariff>Unlim-100</tariff>
  <tariffalias>Unlim-100</tariffalias>
  <tariffnm>No</tariffnm>
  <traffdownload>0 b</traffdownload>
  <traffupload>0 b</traffupload>
  <trafftotal>0 b</trafftotal>
  <accountstate>active</accountstate>
  <accountexpire>No</accountexpire>
  <currency>UAH</currency>
  <version>1</version>
</userdata>

</code>
\\

===== Інформація про попередні платежі користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&payments=true</code>

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
<payment>
	<date>2020-01-13 13:26:11</date>
	<summ>50</summ>
	<balance>265</balance>
</payment>
<payment>
	<date>2017-05-25 12:28:43</date>
	<summ>45</summ>
	<balance>265</balance>
</payment>
<payment>
	<date>2015-06-05 15:59:00</date>
	<summ>10</summ>
	<balance>255</balance>
</payment>
<payment>
	<date>2015-03-30 13:41:25</date>
	<summ>100</summ>
	<balance>155</balance>
</payment>
<payment>
	<date>2014-06-24 18:17:59</date>
	<summ>50</summ>
	<balance>105</balance>
</payment>
<payment>
	<date>2011-10-08 16:03:25</date>
	<summ>50</summ>
	<balance>55</balance>
</payment>
<payment>
	<date>2011-09-30 18:58:21</date>
	<summ>5</summ>
	<balance>50</balance>
</payment>
<payment>
	<date>2011-09-03 20:50:30</date>
	<summ>50</summ>
	<balance>0</balance>
</payment>
</data>
</code>

===== Платежі користувача, але у вигляді JSON =====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&payments=true&json=true</code>
\\

===== Списання коштів з рахунку користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&feecharges=true</code>
Цей виклик підтримує фільтрацію по даті **з - по**. Для цього треба передати відповідні параметри:
  * **datefrom=2024-01-11** - дата **з**
  * **dateto=2024-01-21**   - дата **по**
Ці параметри абсолютно незалежні один від і одного і передавати можна будь-який з них окремо. Відповідно, отримаємо всі записи від "Різдва Христова"(тобто від появи користувача в біллінгу) до **dateto**, або ж від **datefrom** до поточної дати. \\
Також варто зазначити, що в полях **note** та **type** для віртуальних сервісів будуть вказані **Найменування віртуального сервісу**(тобто - найменування тегу) та **virtualsrv** відповідно.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
    <feecharge>
        <date>2024-02-28 00:00:00</date>
        <summ>-9.137931</summ>
        <balance>111.985539</balance>
        <note/>
        <type>mainsrv</type>
    </feecharge>
    <feecharge>
        <date>2024-02-29 00:00:00</date>
        <summ>-9.137931</summ>
        <balance>102.847608</balance>
        <note/>
        <type>mainsrv</type>
    </feecharge>
    <feecharge>
        <date>2024-03-01 00:00:01</date>
        <summ>-8.548387</summ>
        <balance>93.709677</balance>
        <note/>
        <type>mainsrv</type>
    </feecharge>
    <feecharge>
        <date>2024-03-01 01:40:00</date>
        <summ>-30</summ>
        <balance>85.16129</balance>
        <note>Virtual service Name (tag name)</note>
        <type>virtualsrv</type>
    </feecharge>
</data>
</code>
\\

===== Активні оголошення кабінету користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&announcements=true</code>

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
<message unic="1" title="Ми всі помремо">це точно</message>
</data>
</code>
\\

===== Усі тікети користувача =====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&tickets=true</code>

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
<ticket>
	<id>3</id>
	<date>2020-09-22 15:37:53</date>
	<from>_he12ap1_rkh2</from>
	<to></to>
	<replyid>1</replyid>
	<status>0</status>
	<text>user reply</text>
</ticket>
<ticket>
	<id>2</id>
	<date>2020-09-22 15:36:50</date>
	<from>NULL</from>
	<to>_he12ap1_rkh2</to>
	<replyid>1</replyid>
	<status>0</status>
	<text>admin reply</text>
</ticket>
<ticket>
	<id>1</id>
	<date>2020-09-22 15:36:36</date>
	<from>_he12ap1_rkh2</from>
	<to></to>
	<replyid></replyid>
	<status>1</status>
	<text>my ticket</text>
</ticket>
</data>

</code>
\\

===== Створення support-тікету (тобто запиту в техпідтримку) =====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&ticketcreate=true&tickettype=support_request&tickettext=U29tZSB0aWNrZXQgdGV4dCBmb3Igc3VwcG9ydCB0ZWFt</code>

Так, ви все правильно здогадалися: параметр **tickettext** має містити текст тікету закодований у **BASE64**. \\
Цей запит повертає **created = success** та **ID** створеної support-заявки разі успіху або **created = error** та **ID = 0** у разі невдачі.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<created>success</created>
	<id>9</id>
</data>
</code>

==== Відповідь на support-тікет ====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&ticketcreate=true&tickettype=support_request&reply_id=6&tickettext=U29tZSB0aWNrZXQgdGV4dCBmb3Igc3VwcG9ydCB0ZWFt</code>

Все теж саме, що й у минулому запиті, крім додаткового параметру **reply_id=6**, що має містити **ID** тікета, на який дається відповідь. \\
**Слід мати на увазі**, що **reply_id** має буть саме IDшкою тікету, а не IDшкою якогось вже існуючого реплаю. Тобто, в такого запису в БД поле **replyid** має бути **нуль/NULL/пустим**. \\
Цей запит повертає **created = success** та **ID** створеної support-заявки разі успіху або **created = error** та **ID = 0** у разі невдачі.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<created>success</created>
	<id>9</id>
</data>
</code>
\\

===== Створення signup-тікету (тобто заявки на підключення)=====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&ticketcreate=true&tickettype=signup_request</code>
**ВАЖЛИВО** \\
Це єдиний на даний момент запит, який має відправлятися методом **POST** і "мати при собі" **RAW POST data** у форматі **JSON** наступної структури:
<code json>
{
    "date": "2024-02-29 19:57:50",
    "state": 0,
    "ip": "app_IP_addr",
    "street": "Some_City Some_Street",
    "build": "111",
    "apt": "222",
    "realname": "FirstName LastName",
    "phone": "0551234567",
    "service": "Internet",
    "notes": "Some important notes here"
}
</code>

Варто зазначити, що поля **state** та **service** - статичні і їх значення міняти **НЕ треба**. \\
Цей запит повертає **created = success** та **ID** створеної заявки на підключення у разі успіху або **created = error** та **ID = 0** у разі невдачі.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<created>success</created>
	<id>9</id>
</data>
</code>
\\

===== Платіжні системи OpenPayz =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&opayz=true</code>

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
<paysys>
	<name>easypay</name>
	<url>http://op.ourisp.com/backend/easypay/?customer_id=3232235528</url>
	<description>VISA, MasterCard</description>
</paysys>
<paysys>
	<name>mypayprivat</name>
	<url>http://op.ourisp.com/backend/mypayprivat/?customer_id=3232235528</url>
	<description>VISA, MasterCard</description>
</paysys>
</data>
</code>
\\

===== Кредитування =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?module=creditor&agentcredit=true</code>

У разі успіху ми маємо отримати  **status 0**:

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<status>0</status>
	<message>success</message>
</data>

</code>

У разі виникнення помилки, отримаємо не нульовий ерроркод із поясненням причини. Наприклад такий, якщо функціонал кредитування відключений у кабінеті користувача зовсім.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<status>1</status>
	<message>disabled</message>
</data>
</code>

Або наприклад, якщо користувач вже використовував кредит у поточному місяці:
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<status>9</status>
	<message>already used in this month</message>
</data>
</code>

Або як приклад, те саме але в JSON:
<code>
http://demo.ubilling.net.ua:9999/billing/userstats/?module=creditor&agentcredit=true&json=true
</code>

Відповідь: 

<code json>
{"status":2,"message":"wrong day"}
</code>

Також ви можете здійснити перевірку "тупо можливості" встановлення кредиту, без власне установки його. Існує додатковий параметр **justcheck=true**. Відповіді, що повертаються - ті ж. Використовуватися це повинно як:

<code>
http://demo.ubilling.net.ua:9999/billing/userstats/?module=creditor&agentcredit=true&justcheck=true
</code>

Можливі коди помилок:
   * 0 - все пройшло успішно (success)
   * 1 - кредитування вимкнено конфігурацією (disabled)
   * 2 - неприпустимий день для кредитування (wrong day)
   * 3 - кредит вже встановлений (already have a credit)
   * 4 - акаунт заморожений (account frozen)
   * 5 - грошей на рахунку достатньо, щоб жити без кредиту (too much money)
   * 6 - занадто мало грошей на рахунку для того, щоб жити в кредит (not enough money)
   * 7 - несподівана помилка (unexpected error)
   * 8 - кредитування не доступне на поточному тарифі (not allowed on this tariff)
   * 9 - вже користувалися кредитуванням у поточному місяці (already used in this month)
   * 10 - не погасили попередній борг (not paid previous)


Починаючи з релізу Ubilling 1.2.0 набір полів, що повертаються на виклики **agentcredit** істотно розширено:


<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<status>2</status>
	<message>wrong day</message>
	<fullmessage>Ви можете скористатись цією послугою тільки між 1 та 3 днями місяця</fullmessage>
	<minday>1</minday>
	<maxday>3</maxday>
	<creditterm>3</creditterm>
	<creditprice>5</creditprice>
	<currency>UAH</currency>
	<creditintro>Якщо так сталось і ви не змогли оплатити послугу вчасно, ви можете отримати кредит терміном на  3 доби. Вартість цієї послуги становить: 5 UAH. Також ви зобов`язуєтесь оплатити послуги за поточний місяць у повному обсязі, відповідно до вашого тарифного плану. Додаткові послуги не підлягають кредитуванню.</creditintro>
</data>

</code>


А саме крім результату в status і message з текстом того, що відбувається, тепер також повертаються:
   * fullmessage - повне повідомлення про успіх чи помилку в локалі кабінету за замовчуванням
   * minday - початковий день можливості надання послуги кредитування
   * maxday - кінцевий день можливості надання послуги кредитування
   * creditterm - кількість днів на які буде надано кредит
   * creditprice - вартість послуги кредитування
   * currency - валюта кабінету користувача
   * creditintro - короткий опис послуги в локалі кабінету за замовчуванням
\\

===== Картки поповнення =====

<code>http://demo.ubilling.net.ua:9999/billing/userstats/?module=paycards&agentpaycards=true&paycard=2621506348983057</code>

Якщо все пройшло успішно:
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<result>true</result>
	<message>Card is successfully used</message>
</data>
</code>

У разі невдачі:
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<result>false</result>
	<message>Invalid card</message>
</data>

</code>

Варто також зауважити, що параметр **paycard** може бути переданий як GET так і як змінна POST. Якщо він не був отриманий, ні в якому вигляді ми отримаємо наступний результат:

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
	<result>false</result>
	<message>No card number provided</message>
</data>

</code>
\\

===== Асоційований з користувачем контрагент =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&agentassigned=true</code>
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
<agentdata>
	<id>1</id>
	<bankacc>UA1549686521125763214747854</bankacc>
	<bankname>iBank</bankname>
	<bankcode>456522</bankcode>
	<edrpo>2564325</edrpo>
	<ipn>6546456456465</ipn>
	<licensenum>11213231</licensenum>
	<juraddr>Some city, Some street</juraddr>
	<phisaddr>Another city, Another street</phisaddr>
	<phone>+380501234567</phone>
	<contrname>ФОП Пупкин</contrname>
	<agnameabbr>Пуп</agnameabbr>
	<agsignatory>Пуп1</agsignatory>
	<agsignatory2>Пуп2</agsignatory2>
	<agbasis>Just because</agbasis>
	<agmail>some.mail@gmail.com</agmail>
	<siteurl>https://ubilling.net.ua</siteurl>
</agentdata>
</data>
</code>
\\

===== Поточний тариф та всі віртуальні сервіси користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&tariffvservices=true</code>
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
    <tariffvservices>
        <tariffname>Some_Cool_tariff</tariffname>
        <tariffprice>265</tariffprice>
        <tariffdaysperiod>month</tariffdaysperiod>
    </tariffvservices>
    <tariffvservices>
        <vsrvname>Reminder</vsrvname>
        <vsrvprice>1</vsrvprice>
        <vsrvdaysperiod>0</vsrvdaysperiod>
    </tariffvservices>
    <tariffvservices>
        <vsrvname>Some cool vservice</vsrvname>
        <vsrvprice>30</vsrvprice>
        <vsrvdaysperiod>30</vsrvdaysperiod>
    </tariffvservices>
</data>
</code>
\\

===== Тарифи, на які користувач може перейти в особистому кабінеті =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&tarifftoswitchallowed=true</code>
Потребує ввімкненого функціоналу самостійної зміни тарифу в особистому кабінеті користувача. \\
Так-так: оті всі опції **TC_*** з [[userstats|userstats.ini]] + [[tariffmatrix|tariffmatrix.ini]]. \\
Виклик повертає дані опції **TC_TARIFFSALLOWED**, якщо тариф користувача міститься в списку **TC_TARIFFENABLEDFROM** або відповідні дані з **tariffmatrix.ini** (знову ж таки, якщо його поточний тариф там фігурує). У всіх інших випадках виклик повертає **нічого**.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
    <tarifftoswitchallowed>
        <tariff>30M_50grn_FREE</tariff>
    </tarifftoswitchallowed>
    <tarifftoswitchallowed>
        <tariff>30M_70grn_Sale</tariff>
    </tarifftoswitchallowed>
    <tarifftoswitchallowed>
        <tariff>40M_Pon_150grn_N</tariff>
    </tarifftoswitchallowed>
    <tarifftoswitchallowed>
        <tariff>Mur_100M_150grn</tariff>
    </tarifftoswitchallowed>
</data>
</code>
\\


===== Всі поточні активні тарифи та віртуальні сервіси провайдеру =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&activetariffsvservices=true</code>
Є важливий нюанс щодо цього виклику. Оскільки мова йде про "поточні **активні(актуальні)** тарифи та віртуальні сервіси", то цей виклик ігнорує всі тарифи, які додані в список **"непопулярних"** та всі віртуальні сервіси, які позначено як **"архівні"**. Отож - аби цей виклик не вивалював вам абсолютно **ВСІ** наявні тарифи та віртуальні сервіси, а тільки саме ті, які ви хочете, так сказать, представити "публічно" - потурбуйтесь про додавання тарифів, які не треба "світити" до "непопулярних"(так, той самий спеціальний модуль з піктограмою овечки у сайдбарі), а такі ж віртуальні сервіси позначити як "архівні".

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<data>
        <activetariffsvservices>
            <tariffname>MyCoolTarriff1</tariffname>
            <tariffprice>265</tariffprice>
            <tariffdaysperiod>month</tariffdaysperiod>
        </activetariffsvservices>
        <activetariffsvservices>
            <tariffname>MyCoolTarriff2</tariffname>
            <tariffprice>15</tariffprice>
            <tariffdaysperiod>day</tariffdaysperiod>
        </activetariffsvservices>
        <activetariffsvservices>
            <tariffname>MyCoolTarriff3</tariffname>
            <tariffprice>200</tariffprice>
            <tariffdaysperiod>month</tariffdaysperiod>
        </activetariffsvservices>
        <activetariffsvservices>
            <vsrvname>SomeVservice</vsrvname>
            <vsrvprice>5</vsrvprice>
            <vsrvdaysperiod>14</vsrvdaysperiod>
        </activetariffsvservices>
        <activetariffsvservices>
            <vsrvname>Reminder</vsrvname>
            <vsrvprice>1</vsrvprice>
            <vsrvdaysperiod>0</vsrvdaysperiod>
        </activetariffsvservices>
</data>
</code>
\\

====== Заморозка/розморозка користувача ======
===== Отримання даних про стан замороженості користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&freezedata=true</code>
<code xml>
<freezedata>
    <result>Success</result>
    <message/>
    <freezeSelfAvailable>1</freezeSelfAvailable>
    <activationCost>13</activationCost>
    <tariffsAllowedList>Unlim-5,NEW_40_150_grn</tariffsAllowedList>
    <tariffAllowedAny>1</tariffAllowedAny>
    <negativeBalanceFreezeAllowed/>
    <userBalance>-180.677419</userBalance>
    <userTariff>10M_200grn</userTariff>
    <userTariffFreezePrice>30</userTariffFreezePrice>
    <freezeStatus>frozen</freezeStatus>
    <dateFrom>2025-02-25 17:30:34</dateFrom>
    <dateTo>2025-03-23 17:03:34</dateTo>
    <freezeDaysChargeActive>1</freezeDaysChargeActive>
    <freezeDaysTotal>365</freezeDaysTotal>
    <freezeDaysRestore>120</freezeDaysRestore>
    <freezeDaysUsed>26</freezeDaysUsed>
    <freezeDaysAvailable>339</freezeDaysAvailable>
    <freezeDaysWorked>0</freezeDaysWorked>
    <freezeDaysLeftToWork>120</freezeDaysLeftToWork>
</freezedata>
</code>

===== Заморозка користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&dofreeze=true</code>
Тут все доволі просто: може вертати повідомлення або про успішність операції:
<code xml>
<dofreeze>
    <result>Success</result>
    <message>User 'SomeUserLogin' has been frozen</message>
</dofreeze>
</code>

або про те, що користувач вже заморожений:
<code xml>
<dofreeze>
    <result>Failure</result>
    <message>User 'SomeUserLogin' is already frozen</message>
</dofreeze>
</code>

===== Розморозка користувача =====
<code>http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&dounfreeze=true</code>
Повністю ідентична по своїй суті процедура до попередньої - тільки рівно з протилежним результатом. Але є важливі нюанси:
  * щоби цей виклик в принципі працював опція XMLAGENT_SELF_UNFREEZE_ALLOWED в userstats.ini має бути ввімкненою
  * майте на увазі, що ця операція виконується "as is" - без усіляких додаткових перевірок(так, просто в тупу міняється статус користувача) і дозволяє доволі боляче вистрілити собі в ногу. Так що - використовуйте сугубо на власний розсуд.

Успішне виконання поверне ось такий месседж:
<code xml>
<dofreeze>
    <result>Success</result>
    <message>User 'SomeUserLogin' has been UNfrozen</message>
</dofreeze>
</code>

якщо ж користувач НЕ заморожений - поверне отаке:
<code xml>
<dofreeze>
    <result>Failure</result>
    <message>User 'SomeUserLogin' is already UNfrozen</message>
</dofreeze>
</code>
\\

====== XMLAgent вимкнено конфігурацією ======

У цьому випадку ми отримуємо помилку вигляду

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<error>
	<reason>disabled</reason>
</error>
</code>


====== Ввімкнення ======

Потрібно включити відповідну опцію [[userstats|userstats.ini]]

<code ini>
 UBA_ENABLED=1
</code>