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

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

<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>
\\

===== Створення 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&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>
\\

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