### Install pyubilling Python Package

Source: https://github.com/fenicu/ubillingwrapper/blob/master/README.md

Installs the pyubilling Python package from GitHub using either 'uv' or 'pip'. This is the primary method for adding the library to your project's dependencies.

```bash
uv add git+https://github.com/Fenicu/UbillingWrapper
```

```bash
pip install git+https://github.com/Fenicu/UbillingWrapper
```

--------------------------------

### Get User Information (Python)

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Shows how to retrieve detailed user account information using the `get_user_info` method. It returns a `UserInfo` model containing balance, tariff, traffic stats, and account status. The example demonstrates accessing various attributes of the returned user object.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        user = await client.get_user_info(login="john", password=password_md5)

        if user:
            print(f"Login: {user.billing_login}")
            print(f"Real Name: {user.realname}")
            print(f"Balance: {user.cash} {user.currency}")
            print(f"Tariff: {user.tariff_name}")
            print(f"IP Address: {user.ip}")
            print(f"Account State: {user.account_state}")
            print(f"Download Traffic: {user.traffic_download}")
            print(f"Upload Traffic: {user.traffic_upload}")
            print(f"Credit: {user.credit} (expires: {user.credit_expire})")

asyncio.run(main())
```

--------------------------------

### Initialize and Use UbillingClient Python

Source: https://github.com/fenicu/ubillingwrapper/blob/master/README.md

Demonstrates how to initialize the UbillingClient with authentication credentials (login and MD5 hashed password) and perform various API calls. It shows examples for fetching user info, payments, announcements, tickets, and more.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        # User info
        user = await client.get_user_info(login="john", password=password_md5)
        if user:
            print(user.billing_login, user.cash, user.tariff_name)

        # Payments & fee charges
        payments = await client.get_payments(login="john", password=password_md5)
        charges = await client.get_fee_charges(
            login="john", password=password_md5,
            date_from="2024-01-01", date_to="2024-12-31",
        )

        # Announcements
        announcements = await client.get_announcements(login="john", password=password_md5)
        await client.mark_announcements_read(login="john", password=password_md5)

        # Support tickets
        tickets = await client.get_tickets(login="john", password=password_md5)
        result = await client.create_ticket(
            login="john", password=password_md5,
            text="My internet is down",
        )

        # Payment systems & prepaid cards
        pay_systems = await client.get_payment_systems(login="john", password=password_md5)
        card_result = await client.use_pay_card(
            login="john", password=password_md5,
            card_number="2621506348983057",
        )

        # Credit
        credit_check = await client.check_credit(login="john", password=password_md5)
        credit = await client.get_credit(login="john", password=password_md5)

        # Contractor (agent) data
        agent = await client.get_agent_data(login="john", password=password_md5)

        # Tariffs & virtual services
        tariff_info = await client.get_tariff_vservices(login="john", password=password_md5)
        allowed = await client.get_allowed_tariffs(login="john", password=password_md5)
        all_tariffs = await client.get_active_tariffs_vservices(login="john", password=password_md5)

        # Freeze / unfreeze
        freeze_info = await client.get_freeze_data(login="john", password=password_md5)
        freeze_result = await client.freeze_user(login="john", password=password_md5)
        unfreeze_result = await client.unfreeze_user(login="john", password=password_md5)

        # Auth check & connection check
        is_valid = await client.check_auth(login="john", password=password_md5)
        is_alive = await client.check_connection()

asyncio.run(main())

```

--------------------------------

### Get Announcements

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves active system announcements for the user. Returns a list of announcement objects.

```APIDOC
## GET /billing/userstats/announcements

### Description
Retrieve active system announcements for the user. Returns a list of `Announcement` objects with title, text, and unique identifier.

### Method
GET

### Endpoint
/billing/userstats/announcements

### Parameters
#### Query Parameters
- **login** (string) - Required - The user's login name.
- **password** (string) - Required - The MD5 hash of the user's password.

### Request Example
```json
{
  "login": "john",
  "password": "<md5_hash>"
}
```

### Response
#### Success Response (200)
- **title** (string) - The title of the announcement.
- **text** (string) - The main content of the announcement.
- **unic** (string) - A unique identifier for the announcement.

#### Response Example
```json
[
  {
    "title": "Scheduled Maintenance",
    "text": "Network maintenance scheduled for Sunday 2-4 AM",
    "unic": "ann_20240115_001"
  }
]
```
```

--------------------------------

### Get Allowed Tariffs

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves a list of tariffs that the user is allowed to switch to. Requires tariff switching to be enabled in configuration.

```APIDOC
## Get Allowed Tariffs

### Description
Retrieve tariffs available for the user to switch to. Requires tariff switching to be enabled in userstats.ini.

### Method
POST

### Endpoint
/fenicu/ubillingwrapper/get_allowed_tariffs

### Parameters
#### Query Parameters
- **login** (string) - Required - User login.
- **password** (string) - Required - User password (MD5 hash).

### Request Example
```json
{
  "login": "john",
  "password": "d41d8cd98f00b204e9800998ecf8427e"
}
```

### Response
#### Success Response (200)
- **tariff** (string) - Name of an available tariff.

#### Response Example
```json
[
  {
    "tariff": "Unlimited 50Mbps"
  },
  {
    "tariff": "Unlimited 100Mbps"
  },
  {
    "tariff": "Unlimited 200Mbps"
  },
  {
    "tariff": "Business 500Mbps"
  }
]
```
```

--------------------------------

### Get Payment Systems

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieve available online payment systems (OpenPayz integration). Returns a list of PaymentSystem objects with name, URL, and description.

```APIDOC
## GET /api/paymentsystems

### Description
Retrieves a list of available online payment systems integrated with OpenPayz. The response includes details for each payment system, such as its name, URL, and a brief description.

### Method
GET

### Endpoint
`/api/paymentsystems`

### Parameters
#### Query Parameters
- **login** (string) - Required - The user's login.
- **password** (string) - Required - The user's password (MD5 hash).

### Request Example
```json
{
  "login": "john",
  "password": "5a105e8b9d40e1329780d62ea2265d8a"
}
```

### Response
#### Success Response (200)
- **payment_systems** (array) - A list of payment system objects.
  - **name** (string) - The name of the payment system.
  - **url** (string) - The URL for the payment system.
  - **description** (string) - A description of the payment system.

#### Response Example
```json
{
  "payment_systems": [
    {
      "name": "LiqPay",
      "url": "https://www.liqpay.ua/api/pay?...",
      "description": "Pay with credit card via LiqPay"
    },
    {
      "name": "Privat24",
      "url": "https://api.privatbank.ua/...",
      "description": "Pay via Privat24 terminal"
    }
  ]
}
```
```

--------------------------------

### Get Tariff and Virtual Services

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves the user's current tariff and associated virtual services. Returns a list of tariff and service details.

```APIDOC
## Get Tariff and Virtual Services

### Description
Retrieve the user's current tariff and associated virtual services. Returns a list of `TariffVService` objects.

### Method
POST

### Endpoint
/fenicu/ubillingwrapper/get_tariff_vservices

### Parameters
#### Query Parameters
- **login** (string) - Required - User login.
- **password** (string) - Required - User password (MD5 hash).

### Request Example
```json
{
  "login": "john",
  "password": "d41d8cd98f00b204e9800998ecf8427e"
}
```

### Response
#### Success Response (200)
- **is_tariff** (boolean) - True if the item is a tariff, false for a virtual service.
- **tariff_name** (string) - Name of the tariff (if `is_tariff` is true).
- **tariff_price** (number) - Price of the tariff (if `is_tariff` is true).
- **tariff_days_period** (integer) - Duration of the tariff period in days (if `is_tariff` is true).
- **vservice_name** (string) - Name of the virtual service (if `is_tariff` is false).
- **vservice_price** (number) - Price of the virtual service (if `is_tariff` is false).
- **vservice_days_period** (integer) - Duration of the virtual service period in days (if `is_tariff` is false).

#### Response Example
```json
[
  {
    "is_tariff": true,
    "tariff_name": "Unlimited 100Mbps",
    "tariff_price": 200.00,
    "tariff_days_period": 30
  },
  {
    "is_tariff": false,
    "vservice_name": "Static IP",
    "vservice_price": 50.00,
    "vservice_days_period": 30
  }
]
```
```

--------------------------------

### Get Payment History (Python)

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Demonstrates how to retrieve a user's payment history using the `get_payments` method. The method returns a list of `Payment` objects, each containing the date, amount, and resulting balance. The example shows iterating through the payments and printing key details.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        payments = await client.get_payments(login="john", password=password_md5)

        print(f"Total payments: {len(payments)}")
        for payment in payments[:5]:  # Show last 5 payments
            print(f"  {payment.date}: +{payment.summ} (balance: {payment.balance})")

asyncio.run(main())
```

--------------------------------

### Get Support Tickets

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves all support tickets and their replies for the user. Returns a list of ticket objects.

```APIDOC
## GET /billing/userstats/tickets

### Description
Retrieve all support tickets and their replies for the user. Returns a list of `Ticket` objects containing ticket details, status, and message text.

### Method
GET

### Endpoint
/billing/userstats/tickets

### Parameters
#### Query Parameters
- **login** (string) - Required - The user's login name.
- **password** (string) - Required - The MD5 hash of the user's password.

### Request Example
```json
{
  "login": "john",
  "password": "<md5_hash>"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the ticket or reply.
- **date** (string) - The date and time of the ticket or reply.
- **from_user** (string) - The user who sent the message (e.g., 'john', 'support').
- **to** (string) - The recipient of the message.
- **status** (integer) - The status of the ticket (e.g., 1 for open, 2 for closed).
- **text** (string) - The content of the ticket message or reply.
- **reply_id** (integer) - The ID of the ticket this message is a reply to (null if it's an original ticket).

#### Response Example
```json
[
  {
    "id": 123,
    "date": "2024-01-15 10:30:00",
    "from_user": "john",
    "to": "support",
    "status": 1,
    "text": "My internet connection is unstable...",
    "reply_id": null
  },
  {
    "id": 124,
    "date": "2024-01-15 11:00:00",
    "from_user": "support",
    "to": "john",
    "status": 2,
    "text": "We have identified the issue and are working on it...",
    "reply_id": 123
  }
]
```
```

--------------------------------

### Get Tariff and Virtual Services using Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Fetches the user's current tariff plan and any associated virtual services. It takes login credentials and returns a list of TariffVService objects, detailing each service's name, price, and duration. Requires pyubilling and asyncio.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        services = await client.get_tariff_vservices(login="john", password=password_md5)

        for service in services:
            if service.is_tariff:
                print(f"Tariff: {service.tariff_name}")
                print(f"  Price: {service.tariff_price}")
                print(f"  Period: {service.tariff_days_period} days")
            else:
                print(f"Virtual Service: {service.vservice_name}")
                print(f"  Price: {service.vservice_price}")
                print(f"  Period: {service.vservice_days_period} days")

asyncio.run(main())
```

--------------------------------

### Get Payment Systems via Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves a list of available online payment systems integrated with Ubilling, such as LiqPay and Privat24. Returns payment system details including name, URL, and description. Requires the pyubilling library and asyncio.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        pay_systems = await client.get_payment_systems(login="john", password=password_md5)

        print("Available payment methods:")
        for system in pay_systems:
            print(f"  {system.name}: {system.description}")
            print(f"    URL: {system.url}")

asyncio.run(main())
# Output:
# Available payment methods:
#   LiqPay: Pay with credit card via LiqPay
#     URL: https://www.liqpay.ua/api/pay?...
#   Privat24: Pay via Privat24 terminal
#     URL: https://api.privatbank.ua/...
```

--------------------------------

### Get User Information

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieve complete user account information including balance, tariff, traffic statistics, and account status. Returns a `UserInfo` model with all account details or `None` if the user is not found.

```APIDOC
## Get User Information

### Description
Retrieve complete user account information including balance, tariff, traffic statistics, and account status. Returns a `UserInfo` model with all account details or `None` if the user is not found.

### Method
`GET`

### Endpoint
`/billing/userstats` (Example base path)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        user = await client.get_user_info(login="john", password=password_md5)

        if user:
            print(f"Login: {user.billing_login}")
            print(f"Real Name: {user.realname}")
            print(f"Balance: {user.cash} {user.currency}")
            print(f"Tariff: {user.tariff_name}")
            print(f"IP Address: {user.ip}")
            print(f"Account State: {user.account_state}")
            print(f"Download Traffic: {user.traffic_download}")
            print(f"Upload Traffic: {user.traffic_upload}")
            print(f"Credit: {user.credit} (expires: {user.credit_expire})")

asyncio.run(main())
```

### Response
#### Success Response (200)
- **user_info** (`UserInfo` object) - Contains detailed user information.
- **None** - If the user is not found.

#### Response Example
```json
{
  "example": {
    "billing_login": "john",
    "realname": "John Doe",
    "cash": "150.50",
    "currency": "UAH",
    "tariff_name": "Unlimited 100Mbps",
    "ip": "192.168.1.100",
    "account_state": "Active",
    "traffic_download": "125.5 GB",
    "traffic_upload": "15.2 GB",
    "credit": "0",
    "credit_expire": null
  }
}
```
```

--------------------------------

### Get All Active Tariffs and Virtual Services

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves all active (non-archived) tariffs and virtual services available provider-wide. This endpoint is useful for displaying available services to users.

```APIDOC
## GET /billing/userstats/tariffs_vservices

### Description
Retrieve all active (non-archived) tariffs and virtual services available provider-wide.

### Method
GET

### Endpoint
/billing/userstats/tariffs_vservices

### Parameters
#### Query Parameters
- **login** (string) - Required - The username for authentication.
- **password** (string) - Required - The MD5 hash of the user's password for authentication.

### Request Example
```python
# Example using pyubilling library
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()
    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        all_services = await client.get_active_tariffs_vservices(login="john", password=password_md5)
        # Process all_services...
asyncio.run(main())
```

### Response
#### Success Response (200)
- **is_tariff** (boolean) - Indicates if the item is a tariff.
- **tariff_name** (string) - The name of the tariff.
- **tariff_price** (string) - The price of the tariff.
- **vservice_name** (string) - The name of the virtual service.
- **vservice_price** (string) - The price of the virtual service.

#### Response Example
```json
[
  {
    "is_tariff": true,
    "tariff_name": "Basic 10Mbps",
    "tariff_price": "100.00/period"
  },
  {
    "is_tariff": false,
    "vservice_name": "Static IP",
    "vservice_price": "50.00/period"
  }
]
```
```

--------------------------------

### Check Authentication (Python)

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Provides an example of how to verify user credentials using the `check_auth` method. This method is useful for login validation as it returns a boolean indicating whether the provided login and MD5-hashed password are correct, without fetching full user data.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        is_valid = await client.check_auth(login="john", password=password_md5)

        if is_valid:
            print("Authentication successful")
        else:
            print("Invalid credentials")

asyncio.run(main())
```

--------------------------------

### Get System Announcements with pyubilling

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves active system announcements for a user using the pyubilling client. Requires login credentials and returns a list of Announcement objects containing title, text, and unique identifier.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        announcements = await client.get_announcements(login="john", password=password_md5)

        for announcement in announcements:
            print(f"[{announcement.title}]")
            print(f"  {announcement.text}")
            print(f"  ID: {announcement.unic}")

asyncio.run(main())
```

--------------------------------

### Get Agent Data

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves contractor (agent) information assigned to the user. Returns detailed contact and legal information.

```APIDOC
## Get Agent Data

### Description
Retrieve contractor (agent) information assigned to the user. Returns an `AgentData` object with contact and legal details.

### Method
POST

### Endpoint
/fenicu/ubillingwrapper/get_agent_data

### Parameters
#### Query Parameters
- **login** (string) - Required - User login.
- **password** (string) - Required - User password (MD5 hash).

### Request Example
```json
{
  "login": "john",
  "password": "d41d8cd98f00b204e9800998ecf8427e"
}
```

### Response
#### Success Response (200)
- **contrname** (string) - Contractor name.
- **agnameabbr** (string) - Abbreviated agent name.
- **phone** (string) - Agent's phone number.
- **agmail** (string) - Agent's email address.
- **siteurl** (string) - Agent's website URL.
- **phisaddr** (string) - Agent's physical address.
- **bankname** (string) - Agent's bank name.

#### Response Example
```json
{
  "contrname": "Internet Provider LLC",
  "agnameabbr": "IP LLC",
  "phone": "+380441234567",
  "agmail": "support@provider.ua",
  "siteurl": "https://provider.ua",
  "phisaddr": "123 Main St, Kyiv",
  "bankname": "PrivatBank"
}
```
```

--------------------------------

### Get Payment History

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieve the user's payment history as a list of `Payment` objects containing date, amount, and balance after payment.

```APIDOC
## Get Payment History

### Description
Retrieve the user's payment history as a list of `Payment` objects containing date, amount, and balance after payment.

### Method
`GET`

### Endpoint
`/billing/userstats` (Example base path)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        payments = await client.get_payments(login="john", password=password_md5)

        print(f"Total payments: {len(payments)}")
        for payment in payments[:5]:  # Show last 5 payments
            print(f"  {payment.date}: +{payment.summ} (balance: {payment.balance})")

asyncio.run(main())
```

### Response
#### Success Response (200)
- **payments** (`list[Payment]` object) - A list of payment records.

#### Response Example
```json
{
  "example": [
    {
      "date": "2024-01-15 10:30:00",
      "summ": "100.00",
      "balance": "250.50"
    },
    {
      "date": "2024-01-01 09:15:00",
      "summ": "100.00",
      "balance": "150.50"
    },
    {
      "date": "2023-12-15 14:20:00",
      "summ": "50.00",
      "balance": "50.50"
    }
  ]
}
```
```

--------------------------------

### Get Fee Charges

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves fee charge (debit) history. Supports filtering by date range. Returns a list of fee charge objects.

```APIDOC
## GET /billing/userstats/fee_charges

### Description
Retrieve fee charge (debit) history with optional date filtering. Returns a list of `FeeCharge` objects with date, amount, balance, note, and type.

### Method
GET

### Endpoint
/billing/userstats/fee_charges

### Parameters
#### Query Parameters
- **login** (string) - Required - The user's login name.
- **password** (string) - Required - The MD5 hash of the user's password.
- **date_from** (string) - Optional - The start date for filtering fee charges (YYYY-MM-DD).
- **date_to** (string) - Optional - The end date for filtering fee charges (YYYY-MM-DD).

### Request Example
```json
{
  "login": "john",
  "password": "<md5_hash>",
  "date_from": "2024-01-01",
  "date_to": "2024-12-31"
}
```

### Response
#### Success Response (200)
- **date** (string) - The date of the fee charge.
- **amount** (number) - The amount of the fee charge.
- **balance** (number) - The user's balance after the charge.
- **note** (string) - A description or note for the fee charge.
- **type** (string) - The type of fee charge (e.g., 'tariff', 'vservice').

#### Response Example
```json
[
  {
    "date": "2024-01-31 00:00:00",
    "amount": 100.00,
    "balance": 500.00,
    "note": "Monthly fee",
    "type": "tariff"
  }
]
```
```

--------------------------------

### Get Active Tariffs and Virtual Services using Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves all active tariffs and virtual services from the ubilling API. It requires the pyubilling library and processes the response to separate tariffs from virtual services, printing the first few of each.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        all_services = await client.get_active_tariffs_vservices(login="john", password=password_md5)

        tariffs = [s for s in all_services if s.is_tariff]
        vservices = [s for s in all_services if not s.is_tariff]

        print(f"All tariffs ({len(tariffs)}):")
        for t in tariffs[:3]:
            print(f"  {t.tariff_name}: {t.tariff_price}/period")

        print(f"\nAll virtual services ({len(vservices)}):")
        for v in vservices[:3]:
            print(f"  {v.vservice_name}: {v.vservice_price}/period")

asyncio.run(main())
```

--------------------------------

### Get Allowed Tariffs using Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves a list of tariffs that the user is eligible to switch to. This functionality requires tariff switching to be enabled in the userstats.ini configuration. The function takes login credentials and returns a list of available tariff names. Dependencies include pyubilling and asyncio.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        allowed_tariffs = await client.get_allowed_tariffs(login="john", password=password_md5)

        print("Available tariffs for switching:")
        for tariff in allowed_tariffs:
            print(f"  - {tariff.tariff}")

asyncio.run(main())
```

--------------------------------

### Get Freeze Data

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves user freeze status and parameters, including available freeze days, pricing, and current freeze status. This is useful for users to check their account's freeze state.

```APIDOC
## GET /billing/userstats/freeze_data

### Description
Retrieve user freeze status and parameters including available freeze days, pricing, and current freeze status.

### Method
GET

### Endpoint
/billing/userstats/freeze_data

### Parameters
#### Query Parameters
- **login** (string) - Required - The username for authentication.
- **password** (string) - Required - The MD5 hash of the user's password for authentication.

### Request Example
```python
# Example using pyubilling library
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()
    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        freeze_data = await client.get_freeze_data(login="john", password=password_md5)
        # Process freeze_data...
asyncio.run(main())
```

### Response
#### Success Response (200)
- **freeze_self_available** (boolean) - Indicates if the user can initiate a freeze.
- **freeze_status** (string) - The current status of the account freeze (e.g., 'active', 'inactive').
- **user_balance** (string) - The current balance of the user's account.
- **user_tariff_freeze_price** (string) - The cost of freezing the user's current tariff.
- **freeze_days_available** (integer) - The number of freeze days available to the user.
- **freeze_days_used** (integer) - The number of freeze days already used by the user.
- **date_from** (string, optional) - The start date of the current freeze period (YYYY-MM-DD).
- **date_to** (string, optional) - The end date of the current freeze period (YYYY-MM-DD).

#### Response Example
```json
{
  "freeze_self_available": true,
  "freeze_status": "active",
  "user_balance": "150.50",
  "user_tariff_freeze_price": "5.00",
  "freeze_days_available": 30,
  "freeze_days_used": 5,
  "date_from": "2024-01-10",
  "date_to": "2024-02-05"
}
```
```

--------------------------------

### Get Support Tickets with pyubilling

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves all support tickets and their replies for a user using the pyubilling client. Requires login credentials and returns a list of Ticket objects with details, status, and message text.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        tickets = await client.get_tickets(login="john", password=password_md5)

        for ticket in tickets:
            ticket_type = "Reply" if ticket.reply_id else "Ticket"
            print(f"[{ticket_type} #{ticket.id}] {ticket.date}")
            print(f"  From: {ticket.from_user} -> To: {ticket.to}")
            print(f"  Status: {ticket.status}")
            print(f"  Text: {ticket.text[:100]}...")

asyncio.run(main())
```

--------------------------------

### Get User Freeze Data using Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Fetches the freeze status and parameters for a user account. This function requires the pyubilling library and returns details such as freeze availability, current status, user balance, and remaining freeze days.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        freeze_data = await client.get_freeze_data(login="john", password=password_md5)

        if freeze_data:
            print(f"Freeze available: {freeze_data.freeze_self_available}")
            print(f"Current status: {freeze_data.freeze_status}")
            print(f"User balance: {freeze_data.user_balance}")
            print(f"Tariff freeze price: {freeze_data.user_tariff_freeze_price}")
            print(f"Days available: {freeze_data.freeze_days_available}")
            print(f"Days used: {freeze_data.freeze_days_used}")
            if freeze_data.date_from:
                print(f"Frozen from: {freeze_data.date_from} to {freeze_data.date_to}")

asyncio.run(main())
```

--------------------------------

### Get Fee Charges History with pyubilling

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves fee charge (debit) history using the pyubilling client. Supports filtering by date range. Requires login credentials and returns a list of FeeCharge objects.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        # Get all fee charges
        all_charges = await client.get_fee_charges(login="john", password=password_md5)

        # Get fee charges for specific date range
        charges = await client.get_fee_charges(
            login="john",
            password=password_md5,
            date_from="2024-01-01",
            date_to="2024-12-31"
        )

        print(f"Charges in 2024: {len(charges)}")
        for charge in charges[:5]:
            print(f"  {charge.date}: -{charge.summ} ({charge.note}) [{charge.type}]")

asyncio.run(main())
```

--------------------------------

### Get Agent Data using Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Retrieves contractor (agent) information associated with a user. This function requires the user's login and hashed password, returning an AgentData object containing contact and legal details. Dependencies include pyubilling and asyncio.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        agent = await client.get_agent_data(login="john", password=password_md5)

        if agent:
            print(f"Contractor: {agent.contrname}")
            print(f"Abbreviated: {agent.agnameabbr}")
            print(f"Phone: {agent.phone}")
            print(f"Email: {agent.agmail}")
            print(f"Website: {agent.siteurl}")
            print(f"Address: {agent.phisaddr}")
            print(f"Bank: {agent.bankname}")

asyncio.run(main())
```

--------------------------------

### Initialize UbillingClient (Python)

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Demonstrates how to initialize the UbillingClient for both standard and extended authentication modes. It highlights the use of the async context manager for proper resource handling and optional timeout configuration. The `uber_key` parameter is used for extended authentication.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    # Standard authentication
    async with UbillingClient(
        "http://demo.ubilling.net.ua:9999/billing/userstats",
        timeout=10.0  # Optional timeout in seconds (default: 5.0)
    ) as client:
        # Use client methods here
        is_alive = await client.check_connection()
        print(f"API reachable: {is_alive}")

    # Extended authentication (when XMLAGENT_EXTENDED_AUTH_ON is enabled)
    serial_hash = hashlib.md5(b"your_serial_number").hexdigest()
    async with UbillingClient(
        "http://demo.ubilling.net.ua:9999/billing/userstats",
        uber_key=serial_hash
    ) as client:
        pass  # Use client methods here

asyncio.run(main())
```

--------------------------------

### Client Initialization

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Initialize the UbillingClient with the Ubilling userstats endpoint URL. Use the async context manager pattern for proper resource management. For servers with extended authentication enabled, provide the `uber_key` parameter.

```APIDOC
## Client Initialization

### Description
Initialize the UbillingClient with the Ubilling userstats endpoint URL. Use the async context manager pattern for proper resource management. For servers with extended authentication enabled, provide the `uber_key` parameter.

### Method
`__aenter__` / `__aexit__` (Context Manager)

### Endpoint
`http://demo.ubilling.net.ua:9999/billing/userstats` (Example)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    # Standard authentication
    async with UbillingClient(
        "http://demo.ubilling.net.ua:9999/billing/userstats",
        timeout=10.0  # Optional timeout in seconds (default: 5.0)
    ) as client:
        # Use client methods here
        is_alive = await client.check_connection()
        print(f"API reachable: {is_alive}")

    # Extended authentication (when XMLAGENT_EXTENDED_AUTH_ON is enabled)
    serial_hash = hashlib.md5(b"your_serial_number").hexdigest()
    async with UbillingClient(
        "http://demo.ubilling.net.ua:9999/billing/userstats",
        uber_key=serial_hash
    ) as client:
        pass  # Use client methods here

asyncio.run(main())
```

### Response
#### Success Response (200)
Client object is successfully initialized and ready for use.

#### Response Example
```json
{
  "example": "Client object ready"
}
```
```

--------------------------------

### Create Signup Request via Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Shows how to create a signup request for new ISP services using the UbillingClient. This function requires customer details like name, contact information, and desired connection date/IP. Requires the pyubilling library and asyncio.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        result = await client.create_signup_request(
            login="john",
            password=password_md5,
            date="2024-01-20 10:00:00",
            ip="192.168.1.100",
            street="Main Street, Kyiv",
            build="42",
            apt="15",
            realname="John Doe",
            phone="+380501234567",
            notes="Prefer morning installation"
        )

        if result and result.is_success:
            print(f"Signup request created! ID: {result.id}")
        else:
            print(f"Failed to create signup request")

asyncio.run(main())
# Output: Signup request created! ID: 127
```

--------------------------------

### Create Support Ticket and Reply via Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Demonstrates how to create a new support ticket and reply to an existing one using the UbillingClient. The text is BASE64 encoded before sending. Requires the pyubilling library and asyncio.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        # Create a new support ticket
        result = await client.create_ticket(
            login="john",
            password=password_md5,
            text="My internet connection has been slow since yesterday morning."
        )

        if result and result.is_success:
            print(f"Ticket created successfully! ID: {result.id}")

        # Reply to an existing ticket
        reply_result = await client.create_ticket(
            login="john",
            password=password_md5,
            text="The issue is still occurring. Please check my connection.",
            reply_id=result.id  # Original ticket ID (not a reply ID)
        )

        if reply_result and reply_result.is_success:
            print(f"Reply sent! ID: {reply_result.id}")

asyncio.run(main())
# Output:
# Ticket created successfully! ID: 125
# Reply sent! ID: 126
```

--------------------------------

### Initialize UbillingClient with Extended Authentication Python

Source: https://github.com/fenicu/ubillingwrapper/blob/master/README.md

Shows how to initialize the UbillingClient when extended authentication is enabled on the server. This requires passing an 'uber_key', which is the MD5 hash of the Ubilling instance serial number.

```python
async with UbillingClient(
    "http://demo.ubilling.net.ua:9999/billing/userstats",
    uber_key="md5_hash_of_serial_number",
) as client:
    ...

```

--------------------------------

### Create Signup Request

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Create a signup (new connection) request via POST. This is used when a potential customer wants to request ISP services.

```APIDOC
## POST /api/signup

### Description
Creates a new signup request for a potential customer requesting ISP services. This endpoint is used to initiate the process for a new internet connection.

### Method
POST

### Endpoint
`/api/signup`

### Parameters
#### Query Parameters
- **login** (string) - Required - The user's login.
- **password** (string) - Required - The user's password (MD5 hash).
- **date** (string) - Required - The desired date and time for the signup request (e.g., "YYYY-MM-DD HH:MM:SS").
- **ip** (string) - Required - The IP address associated with the request.
- **street** (string) - Required - The street address for the new connection.
- **build** (string) - Required - The building number.
- **apt** (string) - Required - The apartment number.
- **realname** (string) - Required - The full name of the customer.
- **phone** (string) - Required - The customer's phone number.
- **notes** (string) - Optional - Any additional notes or preferences for the signup.

### Request Example
```json
{
  "login": "john",
  "password": "5a105e8b9d40e1329780d62ea2265d8a",
  "date": "2024-01-20 10:00:00",
  "ip": "192.168.1.100",
  "street": "Main Street, Kyiv",
  "build": "42",
  "apt": "15",
  "realname": "John Doe",
  "phone": "+380501234567",
  "notes": "Prefer morning installation"
}
```

### Response
#### Success Response (200)
- **is_success** (boolean) - True if the signup request was created successfully.
- **id** (integer) - The ID of the created signup request.

#### Response Example
```json
{
  "is_success": true,
  "id": 127
}
```
```

--------------------------------

### Use Prepaid Card

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Activate a prepaid card to add funds to the user's balance. Returns a PayCardResult with success status and message.

```APIDOC
## POST /api/paycard

### Description
Activates a prepaid card to add funds to the user's account balance. The API returns a `PayCardResult` object indicating the success status and a corresponding message.

### Method
POST

### Endpoint
`/api/paycard`

### Parameters
#### Query Parameters
- **login** (string) - Required - The user's login.
- **password** (string) - Required - The user's password (MD5 hash).
- **card_number** (string) - Required - The number of the prepaid card to activate.

### Request Example
```json
{
  "login": "john",
  "password": "5a105e8b9d40e1329780d62ea2265d8a",
  "card_number": "2621506348983057"
}
```

### Response
#### Success Response (200)
- **is_success** (boolean) - True if the card was activated successfully.
- **message** (string) - A message indicating the result of the activation (e.g., amount added or error details).

#### Response Example
```json
{
  "is_success": true,
  "message": "50.00 UAH added to your balance"
}
```
```

--------------------------------

### Request Credit using Python

Source: https://context7.com/fenicu/ubillingwrapper/llms.txt

Requests a temporary balance extension for a user account. It requires the user's login and hashed password, returning a CreditInfo object with the status and details of the credit request. The pyubilling library and asyncio are necessary.

```python
import asyncio
import hashlib
from pyubilling import UbillingClient

async def main():
    password_md5 = hashlib.md5(b"user_password").hexdigest()

    async with UbillingClient("http://demo.ubilling.net.ua:9999/billing/userstats") as client:
        credit_result = await client.get_credit(login="john", password=password_md5)

        if credit_result:
            print(f"Status: {credit_result.status}")
            print(f"Message: {credit_result.message}")
            if credit_result.full_message:
                print(f"Details: {credit_result.full_message}")

asyncio.run(main())
```