Ubilling Wiki

Користувальницькькі налаштування

Налаштування сайту

Відвідано: • xmlagent

Сайдбар

Розділи

Загальний опис
Історія змін
Рекомендації до оновлення
Плани на майбутнє
Відомі проблеми
Онлайн демо
Допомога проекту
Люди
Трохи про безпеку

FAQ



Редагувати сайдбар

xmlagent

Зміст

XMLAgent

Для зовнішніх програм, що взаємодіють з кабінетом користувача, підтримується окреме 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 

?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84

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

ERROR_WRONG_UBERAUTH

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

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

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

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

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

Трохи про "сесуріті"

Невелика порція рекомендацій, які “і так всі знають” - але хрін хто виконує, да. Більшість з них мають починатись зі слів, на кшталт “Завжди пам'ятайте ….”, або “Майте на увазі: ….”, чи “Не забувайте, що ….” - але ми їх опустимо, бо, погодьтеся, читати їх в кожному рядку - те ще задволення, враховуючи який непосильний труд для більшості людей читати доку взагалі…

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

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

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

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true
<?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>


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

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84
<?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>


Інформація про попередні платежі користувача

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&payments=true
<?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>

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

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


Списання коштів з рахунку користувача

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&feecharges=true

Цей виклик підтримує фільтрацію по даті з - по. Для цього треба передати відповідні параметри:

  • datefrom=2024-01-11 - дата з
  • dateto=2024-01-21 - дата по

Ці параметри абсолютно незалежні один від і одного і передавати можна будь-який з них окремо. Відповідно, отримаємо всі записи від “Різдва Христова”(тобто від появи користувача в біллінгу) до dateto, або ж від datefrom до поточної дати.
Також варто зазначити, що в полях note та type для віртуальних сервісів будуть вказані Найменування віртуального сервісу(тобто - найменування тегу) та virtualsrv відповідно. 

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


Активні оголошення кабінету користувача

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&announcements=true
<?xml version="1.0" encoding="utf-8"?>
<data>
<message unic="1" title="Ми всі помремо">це точно</message>
</data>


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

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&tickets=true
<?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>


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

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

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

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


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

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&ticketcreate=true&tickettype=signup_request

ВАЖЛИВО
Це єдиний на даний момент запит, який має відправлятися методом POST і “мати при собі” RAW POST data у форматі 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"
}

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

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


Платіжні системи OpenPayz

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&opayz=true
<?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>


Кредитування

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

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

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

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

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

Або наприклад, якщо користувач вже використовував кредит у поточному місяці: 

<?xml version="1.0" encoding="utf-8"?>
<data>
	<status>9</status>
	<message>already used in this month</message>
</data>

Або як приклад, те саме але в JSON: 

http://demo.ubilling.net.ua:9999/billing/userstats/?module=creditor&agentcredit=true&json=true

Відповідь: 

{"status":2,"message":"wrong day"}

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

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

Можливі коди помилок:

  • 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 істотно розширено: 

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

А саме крім результату в status і message з текстом того, що відбувається, тепер також повертаються:

  • fullmessage - повне повідомлення про успіх чи помилку в локалі кабінету за замовчуванням
  • minday - початковий день можливості надання послуги кредитування
  • maxday - кінцевий день можливості надання послуги кредитування
  • creditterm - кількість днів на які буде надано кредит
  • creditprice - вартість послуги кредитування
  • currency - валюта кабінету користувача
  • creditintro - короткий опис послуги в локалі кабінету за замовчуванням


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

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

Якщо все пройшло успішно: 

<?xml version="1.0" encoding="utf-8"?>
<data>
	<result>true</result>
	<message>Card is successfully used</message>
</data>

У разі невдачі: 

<?xml version="1.0" encoding="utf-8"?>
<data>
	<result>false</result>
	<message>Invalid card</message>
</data>

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

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


Асоційований з користувачем контрагент

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&agentassigned=true
<?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>


Поточний тариф та всі віртуальні сервіси користувача

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&tariffvservices=true
<?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>


Всі поточні активні тарифи та віртуальні сервіси провайдеру

http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&activetariffsvservices=true

Є важливий нюанс щодо цього виклику. Оскільки мова йде про “поточні активні(актуальні) тарифи та віртуальні сервіси”, то цей виклик ігнорує всі тарифи, які додані в список “непопулярних” та всі віртуальні сервіси, які позначено як “архівні”. Отож - аби цей виклик не вивалював вам абсолютно ВСІ наявні тарифи та віртуальні сервіси, а тільки саме ті, які ви хочете, так сказать, представити “публічно” - потурбуйтесь про додавання тарифів, які не треба “світити” до “непопулярних”(так, той самий спеціальний модуль з піктограмою овечки у сайдбарі), а такі ж віртуальні сервіси позначити як “архівні”. 

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


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

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

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

Ввімкнення

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

 UBA_ENABLED=1
xmlagent.txt · Востаннє змінено: 2024/04/06 01:33 повз bobr

Налаштування сторінки

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki