API Overview
The Proxima Invoice API is a RESTful JSON API built with Go and Gin.
Base URL
http://localhost:8081/api/v1
Production URL will be https://api-invoice.prxm.uz/api/v1.
Authentication
All endpoints except health checks and login require a JWT Bearer token:
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
http://localhost:8081/api/v1/invoices
See Authentication for login flow.
Response Format
Success (Single Item)
{
"data": { ... },
"error": null
}
Success (List with Pagination)
{
"data": [ ... ],
"meta": {
"total": 150,
"page": 1,
"per_page": 20
}
}
Error
{
"data": null,
"error": {
"code": "NOT_FOUND",
"message": "invoice not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
VALIDATION_ERROR | 400 | Invalid request body or parameters |
UNAUTHORIZED | 401 | Missing or invalid JWT token |
FORBIDDEN | 403 | Insufficient permissions |
NOT_FOUND | 404 | Resource not found |
CONFLICT | 409 | Invalid state transition or duplicate |
INTERNAL_ERROR | 500 | Unexpected server error |
Pagination
List endpoints support pagination via query parameters:
| Parameter | Default | Max | Description |
|---|---|---|---|
page | 1 | — | Page number (1-indexed) |
per_page | 20 | 100 | Items per page |
curl "http://localhost:8081/api/v1/invoices?page=2&per_page=50"
Request Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes* | Bearer {jwt_token} |
Content-Type | For POST/PATCH | application/json |
X-Request-ID | No | Custom request ID (auto-generated if absent) |
*Not required for /healthz, /readyz, /api/v1/auth/login.
Endpoint Summary
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /healthz | No | Liveness probe |
| GET | /readyz | No | Readiness probe |
| POST | /api/v1/auth/login | No | Get JWT token |
| GET | /api/v1/clients | Yes | List active clients |
| GET | /api/v1/clients/:key | Yes | Get client details |
| GET | /api/v1/clients/:key/worklogs | Yes | Get client worklogs |
| POST | /api/v1/invoices/prefill | Yes | Preview invoice (not saved) |
| POST | /api/v1/invoices/generate | Yes | Create draft invoice |
| POST | /api/v1/invoices/generate-bulk | Yes | Create drafts for all clients |
| GET | /api/v1/invoices | Yes | List invoices |
| GET | /api/v1/invoices/:id | Yes | Get invoice with line items |
| PATCH | /api/v1/invoices/:id | Yes | Update invoice fields |
| PATCH | /api/v1/invoices/:id/line-items | Yes | Add/update/remove line items |
| POST | /api/v1/invoices/:id/finalize | Yes | Finalize and generate PDF |
| PUT | /api/v1/invoices/:id/regenerate | Yes | Regenerate from fresh data |
| GET | /api/v1/invoices/:id/edit-history | Yes | Get edit history |
| GET | /api/v1/invoices/:id/pdf | Yes | Download PDF |