Загальний опис
Історія змін
Рекомендації щодо оновлення
Плани на майбутнє
Відомі проблеми
Онлайн демо
Люди
Трохи про безпеку
FAQ
Це стара версія документу!
Для зовнішніх програм, що взаємодіють з кабінетом користувача, підтримується окреме REST API.
Починаючи з релізу 1.4.5 XMLAgent REST API тепер винесено у окремий клас і додано багацько нових викликів.
Приклади URL для створення запитів до XMLAgent REST API (детальніше дивіться в описі кожного запиту нижче):
За замовчуванням, відповіді XMLAgent, історично, будуть повернуті у вигляді XML-документу.
Для отримання даних у вигляді JSON-документу просто додайте GET параметр json=true.
У випадку, якщо ви не хочете покладатися на примусову авторизацію користувачів за їх IP, наприклад використовуючи ваш додаток поза мережею, ви можете використовувати примусову авторизацію конкретного користувача прямим вказанням логіну та MD5 хешу паролю для всіх запитів у вигляді наступних GET змінних:
І як приклад авторизації користувача з логіном gen_vj7iyagnzj та паролем codr52mv
?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84
Починаючи з релізу 1.4.7 доступний додатковий базовий рівень так званої “розширеної” аутентифікації, яка використовує MD5 хеш серійного номеру вашого інстансу UB як додатковий аутентифікаційний токен, на кшталт RemoteAPI. Стан ввімкненості розширеної аутентифікації керується опцією userstats.ini - XMLAGENT_EXTENDED_AUTH_ON. Аутентифікаційний токен передається відповідним GET-параметром uberkey.
Виглядає це все загалом якось так:
?xmlagent=true&uberlogin=gen_vj7iyagnzj&uberpassword=614e8c88061bc45a75fdc1b2eefe1e84&uberkey=6fde545feaaba6952d9cdba84ad26475
Так, як бачимо авторизація за логіном/паролем користувача та розширена аутентифікація доволі чудово собі співіснують в рамках одного запиту.
Слід лише мати на увазі, що авторизація за логіном/паролем користувача є дещо опціональною і її вимагають далеко не всі запити - на відміну від розширеної аутентифікації, ввімкнення якої зобов'язує вас використовувати аутентифікаційний токен абсолютно для кожного запиту.
У разі помилки авторизації, ви отримаєте відповідь у вигляді прямого рядка
ERROR_WRONG_UBERAUTH
з HTTP кодом 401 (починаючи з релізу Ubilling 1.2.7)
Примусова авторизація має пріоритет перед усіма стандартними типами авторизації, такими як ip,login,both.
Також ви можете автоматично авторизувати користувача у вашому Telegram-боті, використовуючи посилання вигляду
https://t.me/yourbot/?start=логін_користувача-md5_хеш_паролю
Так, розділювач - символ “-”. Вони можуть автоматично генеруватися кабінетом.
Невелика порція рекомендацій, які “і так всі знають” - але хрін хто виконує, да. Більшість з них мають починатись зі слів, на кшталт “Завжди пам'ятайте ….”, або “Майте на увазі: ….”, чи “Не забувайте, що ….” - але ми їх опустимо, бо, погодьтеся, читати їх в кожному рядку - те ще задволення, враховуючи який непосильний труд для більшості людей читати доку взагалі…
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>
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
Цей виклик підтримує фільтрацію по даті з - по. Для цього треба передати відповідні параметри:
Ці параметри абсолютно незалежні один від і одного і передавати можна будь-який з них окремо. Відповідно, отримаємо всі записи від “Різдва Христова”(тобто від появи користувача в біллінгу) до 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>
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>
http://demo.ubilling.net.ua:9999/billing/userstats/?xmlagent=true&ticketcreate=true&tickettype=support_request&reply_id=6&tickettext=U29tZSB0aWNrZXQgdGV4dCBmb3Igc3VwcG9ydCB0ZWFt
Все теж саме, що й у минулому запиті, крім додаткового параметру reply_id=6, що має містити ID тікета, на який дається відповідь.
Слід мати на увазі, що reply_id має буть саме IDшкою тікету, а не IDшкою якогось вже існуючого реплаю. Тобто, в такого запису в БД поле replyid має бути нуль/NULL/пустим.
Цей запит повертає created = success та ID створеної support-заявки разі успіху або created = error та ID = 0 у разі невдачі.
<?xml version="1.0" encoding="utf-8"?> <data> <created>success</created> <id>9</id> </data>
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>
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
Можливі коди помилок:
Починаючи з релізу 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 з текстом того, що відбувається, тепер також повертаються:
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&tarifftoswitchallowed=true
Потребує ввімкненого функціоналу самостійної зміни тарифу в особистому кабінеті користувача.
Так-так: оті всі опції TC_* з userstats.ini + tariffmatrix.ini.
Виклик повертає дані опції TC_TARIFFSALLOWED, якщо тариф користувача міститься в списку TC_TARIFFENABLEDFROM або відповідні дані з tariffmatrix.ini (знову ж таки, якщо його поточний тариф там фігурує). У всіх інших випадках виклик повертає нічого.
<?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>
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>
У цьому випадку ми отримуємо помилку вигляду
<?xml version="1.0" encoding="utf-8"?> <error> <reason>disabled</reason> </error>
Потрібно включити відповідну опцію userstats.ini
UBA_ENABLED=1
