bill.php¶

Модуль управления биллингом и инвойсами: получение списков услуг, экспорт данных клиента в CSV, управление инвойсами и просмотр истории платежей

Методы API¶

Метод	Действие	Описание
`billing_list`	получение списка биллинговых записей для сервиса	Возвращает список всех платежных записей (биллингов), привязанных к конкретному сервису.
`customer_billings_export`	экспорт биллингов клиента в CSV	Генерирует CSV-файл со всеми платежными записями текущего авторизованного клиента.
`customer_billings_list`	получение списка биллингов клиента	Возвращает список всех платежных записей текущего авторизованного клиента.
`customer_invoice_billings`	получение биллингов по инвойсу	Возвращает список платежных записей, относящихся к конкретному инвойсу клиента.
`customer_prebill_invoice_ids`	получение ID инвойсов для пребиллинга	Возвращает список идентификаторов доступных инвойсов для текущего клиента.
`customer_services_get`	получение услуги	Возвращает детальную информацию о биллинговой записи, включая данные клиента и связанные серверы.
`customer_services_list`	получение списка услуг	Возвращает список биллинговых записей с поддержкой фильтрации, сортировки и пагинации.
`server_billings_list`	получение списка биллингов сервера	Возвращает список всех финансовых записей (биллингов), связанных с конкретным сервером.
`services_list`	получение списка доступных услуг	Возвращает список всех доступных типов услуг для выбора пользователем.

bill/billing_list¶

Возвращает список всех платежных записей (биллингов), привязанных к конкретному сервису.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `billing_list`
token	✅	string	Токен авторизации
service_id	✅	integer	ID сервиса для получения биллингов.
period_start	❌	string	Дата начала периода. Допустимые форматы: YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD или 'now'.
period_end	❌	string	Дата окончания периода. Допустимые форматы: YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD или 'now'.
start	❌	integer	Смещение (offset) для пагинации.
items	❌	integer	Количество записей на страницу.
sort_order	❌	string	Порядок сортировки. Допустимые значения: id, period_end, period_start, amount, invoice_id, invoice_paid.
sort_type	❌	string	Тип сортировки. Допустимые значения: ASC, DESC.

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=billing_list" \
--data "token=HOSTKEY_TOKEN" \
--data "service_id=123"

Пример успешного ответа

{
"result": "OK",
"action": "billing_list",
"data": {
"items": [
{
"id": 123,
"amount": 50.0,
"currency": "EUR",
"period_start": "2024-01-01 00:00:00",
"period_end": "2024-02-01 00:00:00",
"invoice_id": 5,
"status": "paid"
}
],
"total": 1
}
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: invalid param service_id"
}

bill/customer_billings_export¶

Генерирует CSV-файл со всеми платежными записями текущего авторизованного клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `customer_billings_export`
token	✅	string	Токен авторизации
customer_id	✅	integer	Идентификатор клиента для выгрузки биллинга
skip_filters	✅	string	Параметр `skip_filters`

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_billings_export" \
--data "token=HOSTKEY_TOKEN" \
--data "customer_id=12345" \
--data "skip_filters=true"

Пример успешного ответа

{
"result": "OK",
"action": "customer_billings_export",
"csv": "Date;Period Start;Period End;Service;Service Type;Entity ID;Region;Invoice;Status;Amount;Currency\n...",
"filename": "billing_export_2024-01-01_12-00-00.csv",
"records": 5,
"currency": "EUR"
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: customer_id is required"
}

bill/customer_billings_list¶

Возвращает список всех платежных записей текущего авторизованного клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `customer_billings_list`
token	✅	string	Токен авторизации
customer_id	✅	integer	Идентификатор клиента для получения списка биллингов

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_billings_list" \
--data "token=HOSTKEY_TOKEN" \
--data "customer_id=123"

Пример успешного ответа

{
"result": "OK",
"action": "customer_billings_list",
"data": [
{
"id": 1,
"amount": 25.0,
"currency": "USD",
"accrual_state": "paid"
}
],
"totals": {
"total_amount": 100.0,
"paid_amount": 75.0,
"unpaid_amount": 25.0,
"accrued_amount": 0.0,
"debt_amount": 0.0
},
"currency": "USD"
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: customer_id is required"
}

bill/customer_invoice_billings¶

Возвращает список платежных записей, относящихся к конкретному инвойсу клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `customer_invoice_billings`
token	✅	string	Токен авторизации
invoice_id	✅	integer	Идентификатор инвойса.

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_invoice_billings" \
--data "token=HOSTKEY_TOKEN" \
--data "invoice_id=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "customer_invoice_billings",
"data": [
{
"id": 10,
"amount": 5.0,
"currency": "EUR"
}
]
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: invoice_id is required"
}

bill/customer_prebill_invoice_ids¶

Возвращает список идентификаторов доступных инвойсов для текущего клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `customer_prebill_invoice_ids`
token	✅	string	Токен авторизации

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_prebill_invoice_ids" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "customer_prebill_invoice_ids",
"invoice_ids": [
101,
102,
103
]
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: customer_id is required"
}

bill/services_list¶

Возвращает список всех доступных типов услуг для выбора пользователем.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `services_list`
token	✅	string	Авторизационный токен пользователя для доступа к API.

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=services_list" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "services_list",
"data": [
{
"id": 1,
"name": "VPS KVM",
"price": {
"EUR": 10.0,
"RUB": 950.0
}
},
{
"id": 2,
"name": "Dedicated Server",
"price": {
"EUR": 50.0,
"RUB": 4750.0
}
}
]
}

Примеры ошибок

{
"code": -2,
"message": "Authentication required"
}

bill/server_billings_list¶

Возвращает список всех финансовых записей (биллингов), связанных с конкретным сервером.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `server_billings_list`
token	✅	string	Токен авторизации
id	❌	integer	ID сервера (если передан в GET/POST)
entity_id	✅	integer	Идентификатор сущности (сервера) для фильтрации.
scope_customer_id	❌	integer	Параметр scope_customer_id

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=server_billings_list" \
--data "token=HOSTKEY_TOKEN" \
--data "entity_id=123"

Пример успешного ответа

{
"result": "OK",
"action": "server_billings_list",
"data": [
{
"id": 105,
"amount": 49.99,
"currency": "EUR",
"status": "paid",
"period_start": "2023-10-01 00:00:00",
"period_end": "2023-11-01 00:00:00"
}
]
}

Примеры ошибок

{
"code": -1,
"message": "$module/$action: entity_id is required"
}

bill/customer_services_get¶

Возвращает детальную информацию о биллинговой записи, включая данные клиента и связанные серверы.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `customer_services_get`
token	✅	string	Токен авторизации
id	❌	integer	ID биллинговой записи. (используется в качестве идентификатора)
customer_id	❌	integer	ID клиента. В prebill-режиме подставляется автоматически.
service_ident	❌	string	Уникальный 10-значный шестнадцатеричный ключ услуги. Допустимые значения: [a-f0-9]{10}
email	✅	string	Параметр `email`

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_services_get" \
--data "token=HOSTKEY_TOKEN" \
--data "email=user@example.com"

Пример успешного ответа

{
"result": "OK",
"action": "customer_services_get",
"service": {
"id": 123,
"customer_id": 45,
"entity_id": 789,
"status": "active",
"server_data": {
"id": 789,
"name": "web-server-01",
"ip": "1.2.3.4"
}
},
"customer": {
"id": 45,
"email": "user@example.com",
"name": "John Doe"
}
}

Примеры ошибок

{
"code": -1,
"message": "$module/customer_services_get: invalid params array"
}

bill/customer_services_list¶

Возвращает список биллинговых записей с поддержкой фильтрации, сортировки и пагинации.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `customer_services_list`
token	✅	string	Токен авторизации
id	❌	integer	ID записи (используется для фильтрации). Должен быть больше 0.
email	❌	string	Email клиента. Автоматически преобразуется в customer_id.
service_list_id	❌	integer	ID списка услуг для фильтрации. Должен быть больше 0.
period_end	❌	string	Конец периода (дата). Формат: Y-m-d.
period_start	❌	string	Начало периода (дата). Формат: Y-m-d.
service_ident	❌	string	Уникальный 10-значный шестнадцатеричный ключ услуги. Допустимые значения: [a-f0-9]{10}
start	❌	integer	Смещение (offset) для пагинации. Должен быть больше 0.
items	❌	integer	Количество элементов на страницу. Должен быть больше 0.
sort_order	❌	string	Поле для сортировки. Допустимые значения: id, customer_id, period_end, period_start, service_ident, service_list_id.
sort_type	❌	string	Направление сортировки. Допустимые значения: ASC, DESC.
key	❌	string	Биллинговый ключ услуги. Допустимые значения: [a-f0-9]{10}
date_from	❌	string	Дата начала фильтрации. Формат: Y-m-d.
date_to	❌	string	Дата окончания фильтрации. Формат: Y-m-d.

Пример запроса

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_services_list" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "customer_services_list",
"items": 50,
"total": 1,
"start": 0
}

Примеры ошибок

{
"code": -1,
"message": "$module/customer_services_list: invalid params array"
}