Перейти к содержанию

bill.php

В этой статье

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

Методы API

Метод Действие Описание
billing_add ручное добавление платежа Создание новой записи о биллинге (платежом) вручную.
billing_del удаление записи биллинга Удаляет запись о начислении (billing record) по её идентификатору. Удаление невозможно, если запись уже привязана к выставленному счету.
billing_list получение списка биллинговых записей для сервиса Возвращает список всех платежных записей (биллингов), привязанных к конкретному сервису.
customer_billings_export экспорт биллингов клиента в CSV Генерирует CSV-файл со всеми платежными записями текущего авторизованного клиента.
customer_billings_list получение списка биллингов клиента Возвращает список всех платежных записей текущего авторизованного клиента.
customer_invoice_billings получение биллингов по инвойсу Возвращает список платежных записей, связанных с конкретным инвойсом клиента.
customer_prebill_invoice_ids получение ID инвойсов для пребиллинга Возвращает список идентификаторов доступных инвойсов для текущего клиента.
customer_service_add добавление услуги клиенту Регистрация новой услуги для клиента с указанием параметров тарификации.
customer_services_del удаление услуги клиента Удаляет услугу клиента. Невозможно удалить, если по ней есть активные платежные записи.
customer_services_get получение услуги Возвращает детальную информацию о биллинговой записи, включая данные клиента и связанные серверы.
customer_services_list получение списка услуг Возвращает список биллинговых записей с поддержкой фильтрации, сортировки и пагинации.
server_billings_list получение списка биллингов сервера Возвращает список всех финансовых записей (биллингов), связанных с конкретным сервером.
server_service_data получение данных сервисов сервера Возвращает список активных пребил-сервисов для конкретного сервера.
services_list получение списка доступных услуг Возвращает список всех доступных типов услуг для выбора пользователем.

bill/billing_add

Создание новой записи о биллинге (платежом) вручную.

HTTP-метод: POST

Параметры:

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

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

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=billing_add" \
--data "token=HOSTKEY_TOKEN"
Пример успешного ответа 
{
"result": "OK",
"module": "bill",
"action": "billing_add",
"id": 998
}
Примеры ошибок 
{
"-1": [
{
"code": -1,
"message": "$module/$action: invalid params array"
},
{
"code": -1,
"message": "$module/$action: service record not found"
},
{
"code": -1,
"message": "$module/$action: invalid amount value"
},
{
"code": -1,
"message": "$module/$action: $key should be over zero"
},
{
"code": -1,
"message": "$module/$action: invalid $key date. Accepted formats: YYYY-MM-DD [HH:MM:SS]."
}
]
}

bill/billing_del

Удаляет запись о начислении (billing record) по её идентификатору. Удаление невозможно, если запись уже привязана к выставленному счету.

HTTP-метод: POST

Параметры:

action ✅ string Идентификатор метода: billing_del
id ✅ integer Уникальный идентификатор записи биллинга для удаления.
invoice_id ✅ int Параметр invoice_id
token ❌ string Уникальный токен для авторизации или проверки подлинности запроса.

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

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=billing_del" \
--data "id=12345" \
--data "invoice_id=67890"
Пример успешного ответа 
{
"result": "OK",
"action": "billing_del",
"id": 12345
}
Примеры ошибок 
{
"code": -1,
"message": "invalid id"
}

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 Токен авторизации
id ❌ integer ID инвойса (если передан в корне)
params[invoice_id] ✅ integer Идентификатор инвойса для получения биллингов.
invoice_id ✅ int Параметр invoice_id

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

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_invoice_billings" \
--data "token=HOSTKEY_TOKEN" \
--data "params[invoice_id]=555" \
--data "invoice_id=555"
Пример успешного ответа 
{
"result": "OK",
"action": "customer_invoice_billings",
"data": [
{
"billing_date": "2024-05-20 12:30:00",
"period_start": "2024-05-20 00:00:00",
"period_end": "2024-06-20 00:00:00",
"product": "VPS Hosting Plan",
"service_type": "Virtual Server",
"entity_id": 123,
"region": "NL",
"invoice_id": 555,
"status": "paid",
"amount": "49.99",
"currency": "EUR"
}
]
}
Примеры ошибок 
{
"code": -1,
"message": "$module/$action: customer_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/customer_service_add

Регистрация новой услуги для клиента с указанием параметров тарификации.

HTTP-метод: POST

Параметры:

action ✅ string Идентификатор метода: customer_service_add
token ✅ string Токен авторизации
option_id ❌ integer Идентификатор опции или услуги в системе.

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

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_service_add" \
--data "token=HOSTKEY_TOKEN" \
--data "option_id=123"
Пример успешного ответа 
{
"result": "OK",
"module": "bill",
"action": "customer_service_add",
"id": 501
}
Примеры ошибок 
{
"-2": "Authentication required / Invalid token",
"-1": "$module/$action: invalid params array / invalid param $key / invalid server id... / mandatory key '$key' is missing for a new record / start time is after commit time... / start time is after start time / commit time is after finish time..."
}

bill/customer_services_del

Удаляет услугу клиента. Невозможно удалить, если по ней есть активные платежные записи.

HTTP-метод: POST

Параметры:

Параметр Обязательный Тип Описание
action ✅ string Идентификатор метода: customer_services_del
token ✅ string Токен авторизации
params[id] ✅ integer ID услуги для удаления

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

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=customer_services_del" \
--data "token=HOSTKEY_TOKEN" \
--data "params[id]=123"
Пример успешного ответа 
{
"result": "OK",
"module": "bill",
"action": "customer_services_del",
"id": 123
}
Примеры ошибок 
{
"errors": [
{
"code": -1,
"message": "bill/customer_services_del: service record not found"
},
{
"code": -1,
"message": "bill/customer_services_del: service record has billing ticks, remoce it first "
}
]
}

bill/server_service_data

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

HTTP-метод: POST

Параметры:

Параметр Обязательный Тип Описание
action ✅ string Идентификатор метода: server_service_data
token ✅ string Токен авторизации
params[entity_id] ✅ integer ID сервера (передается в params или как id).

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

curl -s "https://invapi.hostkey.ru/bill.php" -X POST \
--data "action=server_service_data" \
--data "token=HOSTKEY_TOKEN" \
--data "params[entity_id]=123"
Пример успешного ответа 
{
"result": "OK",
"module": "bill",
"action": "server_service_data",
"services": [
{
"service_id": 1,
"customer_id": 50,
"entity_id": 123,
"product": "VPS",
"region": "EU",
"description": "Standard VPS",
"period_start": "2023-01-01 00:00:00",
"period_end": "2024-01-01 00:00:00",
"next_commit_date": "2024-01-01 00:00:00",
"billing_status": "active",
"currency": "EUR",
"eu_withdrawal": 0,
"period": "monthly",
"vat_percent": 20.0,
"subtotal_amount": 10.0,
"total_amount": 12.0,
"tax_amount": 2.0,
"rate_total": 12.0,
"next_due_date": "2024-01-01",
"accrual": null,
"period_change": {
"available": false,
"reason": "check_failed",
"periods": [],
"pending": null
}
}
],
"service": {
"service_id": 1,
"customer_id": 50,
"entity_id": 123,
"product": "VPS",
"region": "EU",
"description": "Standard VPS",
"period_start": "2023-01-01 00:00:00",
"period_end": "2024-01-01 00:00:00",
"next_commit_date": "2024-01-01 00:00:00",
"billing_status": "active",
"currency": "EUR",
"eu_withdrawal": 0,
"period": "monthly",
"vat_percent": 20.0,
"subtotal_amount": 10.0,
"total_amount": 12.0,
"tax_amount": 2.0,
"rate_total": 12.0,
"next_due_date": "2024-01-01",
"accrual": null,
"period_change": {
"available": false,
"reason": "check_failed",
"periods": [],
"pending": null
}
},
"is_prebill": true,
"upgrade_allowed": true
}
Примеры ошибок 
{
"-1": {
"message": "$module/$action: no active prebilling service found for this server"
}
}

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"
}
question_mark
Я могу вам чем-то помочь?
question_mark
ИИ Помощник ×