78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# Billing Endpoints
|
|
|
|
## Purpose
|
|
Detail billing API endpoints for invoices, payments, credit packages, transactions, payment methods, and credit balance/usage.
|
|
|
|
## Code Locations (exact paths)
|
|
- Routing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
|
|
- Views: `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/modules/billing/views.py`
|
|
- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
|
|
|
|
## High-Level Responsibilities
|
|
- Expose billing resources (invoices, payments, credit packages, payment methods, credit transactions).
|
|
- Provide credit balance/usage/limits endpoints.
|
|
- Support manual payment submission and available payment methods lookup.
|
|
|
|
## Detailed Behavior
|
|
- Base paths:
|
|
- `/api/v1/billing/` (business billing views via router)
|
|
- `/api/v1/admin/` (admin billing URLs)
|
|
- `/api/v1/billing/credits/...` (balance/usage/transactions aliases)
|
|
- Invoice endpoints (`InvoiceViewSet`):
|
|
- `GET /invoices/` list account invoices (status filter optional).
|
|
- `GET /invoices/{id}/` invoice detail.
|
|
- `GET /invoices/{id}/download_pdf/` returns PDF bytes (placeholder).
|
|
- Payment endpoints (`PaymentViewSet`):
|
|
- `GET /payments/` list payments (status filter optional).
|
|
- `GET /payment-methods/available/` returns available methods (country/config driven).
|
|
- `POST /payments/manual/` submit manual payment for an invoice (requires invoice_id, payment_method, transaction_reference; rejects already paid).
|
|
- Account payment methods (`AccountPaymentMethodViewSet`):
|
|
- CRUD at `/payment-methods/`; `POST /payment-methods/{id}/set_default/` toggles default for the account.
|
|
- Credit packages (`CreditPackageViewSet`):
|
|
- `GET /credit-packages/` list active packages.
|
|
- `POST /credit-packages/{id}/purchase/` creates invoice and returns next_action (Stripe/PayPal placeholders; manual fallback returns invoice info).
|
|
- Credit transactions (`CreditTransactionViewSet`):
|
|
- `GET /transactions/` ledger of credit changes; also registered under `/credits/transactions/`.
|
|
- Credit balance/usage/limits (`modules/billing/views.py`):
|
|
- `GET /credits/balance/` returns credits, plan monthly credits, month-to-date credits used.
|
|
- `GET /credits/usage/` returns paginated usage logs with filters; `GET /credits/usage/summary/` aggregates by operation/model and totals; `GET /credits/usage/limits/` returns plan/account limits and usage counts.
|
|
- Permissions/tenancy: authenticated users; account-scoped querysets; viewsets rely on `request.account` or `request.user.account`.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `Invoice`, `Payment`, `CreditPackage`, `CreditTransaction`, `AccountPaymentMethod`, `PaymentMethodConfig`, `CreditUsageLog`, `CreditCostConfig`, `Account`, `Plan`.
|
|
|
|
## Execution Flow
|
|
- Router dispatch → viewset → service calls (invoice/payment/credit) → DB updates → unified responses. Balance/usage endpoints compute aggregates on demand.
|
|
|
|
## Cross-Module Interactions
|
|
- Credit costs/checks used by writer/automation AI flows; balances/usage reflect those deductions.
|
|
- Plan limits surfaced in limits endpoint relate to account management in auth/account domains.
|
|
|
|
## State Transitions
|
|
- Invoices: draft/pending/paid/void/uncollectible; Payments: pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled; Credits balance changes via transactions.
|
|
|
|
## Error Handling
|
|
- Manual payment: 400 on missing fields or already-paid invoice.
|
|
- Credit operations: 402 returned by upstream callers on `InsufficientCreditsError`.
|
|
- Balance/usage: returns zeros/empty when account/plan missing.
|
|
|
|
## Tenancy Rules
|
|
- All billing data filtered by account; no cross-tenant access. Default viewsets inherit account scoping from base classes.
|
|
|
|
## Billing Rules
|
|
- Credit costs come from `CreditCostConfig` or constants; deductions recorded in ledger + usage logs.
|
|
- Available methods and packages are filtered by active flags/config.
|
|
|
|
## Background Tasks / Schedulers
|
|
- None specific; Stripe/PayPal integrations are placeholders; any future webhooks should update invoices/payments/credits accordingly.
|
|
|
|
## Key Design Considerations
|
|
- Ledger + usage logs kept in sync via `CreditService`.
|
|
- Manual payment flow avoids storing sensitive data; account payment methods store metadata only.
|
|
|
|
## How Developers Should Work With This Module
|
|
- Use `CreditService` for credit math; do not mutate balances directly.
|
|
- Implement Stripe/PayPal flows in `PaymentService` if adding gateways; wire webhooks to update models.
|
|
- Keep account scoping on all queries; reuse existing viewsets for new billing features.
|
|
|