API счетов на оплату
Эндпоинты для управления счетами на оплату в системе.
Получение списка счетов
Получение полного списка счетов на оплату.
Запрос
GET /api/payment-invoices
Заголовки
Название | Тип | Описание |
---|---|---|
X-API-Key | string | Обязательный. API ключ |
Параметры запроса
Название | Тип | Описание |
---|---|---|
is_paid | boolean | Необязательный. Фильтр по статусу оплаты |
user_id | integer | Необязательный. Фильтр по ID пользователя |
page | integer | Необязательный. Номер страницы |
per_page | integer | Необязательный. Количество записей на странице |
Ответ
{
"payment_invoices": [
{
"id": 1,
"user_id": 123,
"gateway": "paypal",
"transaction_id": "1AB23456CD789012E",
"amount": 100.00,
"original_amount": 100.00,
"currency_id": 1,
"currency": "USD",
"is_paid": true,
"paid_at": "2023-01-01T01:00:00Z",
"created_at": "2023-01-01T00:00:00Z"
},
{
"id": 2,
"user_id": 124,
"gateway": "stripe",
"transaction_id": null,
"amount": 50.00,
"original_amount": 75.00,
"promo_code_id": 3,
"promo_code": "SALE25",
"currency_id": 2,
"currency": "EUR",
"is_paid": false,
"paid_at": null,
"created_at": "2023-01-02T00:00:00Z"
}
],
"pagination": {
"total": 50,
"per_page": 10,
"current_page": 1,
"last_page": 5
}
}
Поля ответа
Поле | Тип | Описание |
---|---|---|
payment_invoices | array | Массив счетов на оплату |
id | integer | ID счета |
user_id | integer | ID пользователя |
gateway | string | Ключ платежного шлюза |
transaction_id | string | ID транзакции (может быть null) |
amount | number | Сумма платежа |
original_amount | number | Исходная сумма (до скидок) |
promo_code_id | integer | ID промокода (если применен) |
promo_code | string | Код промокода (если применен) |
currency_id | integer | ID валюты |
currency | string | Код валюты |
is_paid | boolean | Статус оплаты |
paid_at | string | Дата оплаты (может быть null) |
created_at | string | Дата создания |
pagination | object | Информация о пагинации |
Коды ответов
Код | Описание |
---|---|
200 | Успешный запрос |
401 | Неверный API ключ или отсутствует |
403 | Недостаточно прав для выполнения запроса |
Получение данных счета
Получение детальной информации о конкретном счете на оплату.
Запрос
GET /api/payment-invoices/{id}
Параметры пути
Название | Тип | Описание |
---|---|---|
id | integer | ID счета на оплату |
Заголовки
Название | Тип | Описание |
---|---|---|
X-API-Key | string | Обязательный. API ключ |
Ответ
{
"payment_invoice": {
"id": 1,
"user_id": 123,
"user": {
"id": 123,
"name": "John Doe",
"email": "[email protected]"
},
"gateway": "paypal",
"transaction_id": "1AB23456CD789012E",
"amount": 100.00,
"original_amount": 100.00,
"currency_id": 1,
"currency": "USD",
"is_paid": true,
"paid_at": "2023-01-01T01:00:00Z",
"created_at": "2023-01-01T00:00:00Z"
}
}
Поля ответа
Поле | Тип | Описание |
---|---|---|
payment_invoice | object | Объект счета на оплату |
id | integer | ID счета |
user_id | integer | ID пользователя |
user | object | Информация о пользователе |
gateway | string | Ключ платежного шлюза |
transaction_id | string | ID транзакции (может быть null) |
amount | number | Сумма платежа |
original_amount | number | Исходная сумма (до скидок) |
promo_code_id | integer | ID промокода (если применен) |
promo_code | object | Информация о промокоде (если применен) |
currency_id | integer | ID валюты |
currency | object | Информация о валюте |
is_paid | boolean | Статус оплаты |
paid_at | string | Дата оплаты (может быть null) |
created_at | string | Дата создания |
Коды ответов
Код | Описание |
---|---|
200 | Успешный запрос |
401 | Неверный API ключ или отсутствует |
403 | Недостаточно прав для выполнения запроса |
404 | Счет на оплату не найден |
Создание счета на оплату
Создание нового счета на оплату в системе.
Запрос
POST /api/payment-invoices
Заголовки
Название | Тип | Описание |
---|---|---|
X-API-Key | string | Обязательный. API ключ |
Content-Type | string | Обязательный. application/json |
Тело запроса
{
"user_id": 123,
"gateway": "stripe",
"amount": 75.50,
"currency_id": 1,
"promo_code": "DISCOUNT10"
}
Параметры тела запроса
Название | Тип | Описание |
---|---|---|
user_id | integer | Обязательный. ID пользователя |
gateway | string | Обязательный. Ключ платежного шлюза |
amount | number | Обязательный. Сумма платежа |
currency_id | integer | Обязательный. ID валюты |
promo_code | string | Необязательный. Промокод для скидки |
Ответ
{
"message": "Payment invoice created successfully",
"payment_invoice": {
"id": 3,
"user_id": 123,
"gateway": "stripe",
"transaction_id": null,
"amount": 67.95,
"original_amount": 75.50,
"promo_code_id": 5,
"promo_code": "DISCOUNT10",
"currency_id": 1,
"currency": "USD",
"is_paid": false,
"paid_at": null,
"created_at": "2023-03-15T12:00:00Z"
}
}
Коды ответов
Код | Описание |
---|---|
201 | Счет на оплату успешно создан |
401 | Неверный API ключ или отсутствует |
403 | Недостаточно прав для выполнения запроса |
404 | Пользователь, валюта или промокод не найдены |
422 | Неверные параметры запроса |
Обновление статуса счета на оплату
Обновление статуса существующего счета на оплату.
Запрос
PUT /api/payment-invoices/{id}/status
Параметры пути
Название | Тип | Описание |
---|---|---|
id | integer | ID счета на оплату |
Заголовки
Название | Тип | Описание |
---|---|---|
X-API-Key | string | Обязательный. API ключ |
Content-Type | string | Обязательный. application/json |
Тело запроса
{
"is_paid": true,
"transaction_id": "XYZ987654321"
}
Параметры тела запроса
Название | Тип | Описание |
---|---|---|
is_paid | boolean | Обязательный. Статус оплаты |
transaction_id | string | Необязательный. ID транзакции |
Ответ
{
"message": "Payment invoice status updated successfully",
"payment_invoice": {
"id": 3,
"user_id": 123,
"gateway": "stripe",
"transaction_id": "XYZ987654321",
"amount": 67.95,
"original_amount": 75.50,
"promo_code_id": 5,
"promo_code": "DISCOUNT10",
"currency_id": 1,
"currency": "USD",
"is_paid": true,
"paid_at": "2023-03-15T12:30:00Z",
"created_at": "2023-03-15T12:00:00Z"
}
}
Коды ответов
Код | Описание |
---|---|
200 | Статус счета успешно обновлен |
401 | Неверный API ключ или отсутствует |
403 | Недостаточно прав для выполнения запроса |
404 | Счет на оплату не найден |
422 | Неверные параметры запроса |
Удаление счета на оплату
Удаление счета на оплату из системы (только для неоплаченных счетов).
Запрос
DELETE /api/payment-invoices/{id}
Параметры пути
Название | Тип | Описание |
---|---|---|
id | integer | ID счета на оплату |
Заголовки
Название | Тип | Описание |
---|---|---|
X-API-Key | string | Обязательный. API ключ |
Ответ
{
"message": "Payment invoice deleted successfully"
}
Коды ответов
Код | Описание |
---|---|
200 | Счет на оплату успешно удален |
401 | Неверный API ключ или отсутствует |
403 | Недостаточно прав для выполнения запроса |
404 | Счет на оплату не найден |
422 | Невозможно удалить оплаченный счет |
Получение статистики по платежам
Получение статистики по платежам за определенный период.
Запрос
GET /api/payment-invoices/stats
Заголовки
Название | Тип | Описание |
---|---|---|
X-API-Key | string | Обязательный. API ключ |
Параметры запроса
Название | Тип | Описание |
---|---|---|
start_date | string | Необязательный. Начальная дата (YYYY-MM-DD) |
end_date | string | Необязательный. Конечная дата (YYYY-MM-DD) |
currency_id | integer | Необязательный. Фильтр по ID валюты |
Ответ
{
"stats": {
"total_amount": 1250.75,
"total_count": 45,
"completed_amount": 980.50,
"completed_count": 35,
"pending_amount": 220.25,
"pending_count": 8,
"failed_amount": 50.00,
"failed_count": 2,
"by_gateway": [
{
"gateway_id": 1,
"gateway_name": "PayPal",
"amount": 750.50,
"count": 25
},
{
"gateway_id": 2,
"gateway_name": "Stripe",
"amount": 500.25,
"count": 20
}
],
"by_day": [
{
"date": "2023-06-10",
"amount": 250.75,
"count": 10
},
{
"date": "2023-06-11",
"amount": 300.50,
"count": 12
}
]
}
}
Поля ответа
Поле | Тип | Описание |
---|---|---|
stats | object | Объект со статистикой |
total_amount | number | Общая сумма платежей |
total_count | integer | Общее количество платежей |
completed_amount | number | Сумма завершенных платежей |
completed_count | integer | Количество завершенных платежей |
pending_amount | number | Сумма ожидающих платежей |
pending_count | integer | Количество ожидающих платежей |
failed_amount | number | Сумма неудавшихся платежей |
failed_count | integer | Количество неудавшихся платежей |
by_gateway | array | Статистика по платежным шлюзам |
by_day | array | Статистика по дням |
Коды ответов
Код | Описание |
---|---|
200 | Успешный запрос |
401 | Неверный API ключ или отсутствует |
403 | Недостаточно прав для выполнения запроса |