Tổng quan API
Tài liệu tham khảo cho 25+ REST API endpoints của Haravan Invoice MVP, bao gồm authentication, request/response format, và examples.
Tóm tắt
Haravan Invoice API xây dựng trên Hono framework, chạy trên Cloudflare Workers. Tất cả endpoints yêu cầu Bearer token authentication (trừ health và login). Base URL: /api/v1.
Base URL
Development: http://localhost:8787/api/v1
Production: https://your-worker.workers.dev/api/v1Authentication
Tất cả endpoints (trừ /health và /auth/login) yêu cầu Bearer token:
Authorization: Bearer <jwt_token>Lấy token từ POST /auth/login.
Response Format
Success response
json
{
"success": true,
"data": { ... }
}Paginated response
json
{
"success": true,
"data": {
"items": [...],
"total": 100,
"page": 1,
"pageSize": 20,
"totalPages": 5
}
}Error response
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Tên người mua không được để trống"
}
}Endpoints Summary
| Resource | Endpoints | Tài liệu |
|---|---|---|
| Auth | POST /login | Auth |
| Invoices | POST, GET, GET/:id, POST/:id/replace, POST/:id/adjust, POST/:id/one-click | Invoices |
| GET /:id/pdf | ||
| Audit | GET /:id/audit | Invoices |
| Customers | GET, GET/:id, GET/:id/analytics | Customers |
| Products | GET | Products |
| Reports | GET /summary, GET /monthly | Reports |
| Analytics | GET /channels, /top-customers, /top-skus | Analytics |
| Settings | GET/PATCH /templates, /automation, GET /plan | Settings |
| Notifications | GET, PATCH/:id/read, POST /read-all, GET /unread-count | Notifications |
| Aggregate | GET | Aggregate |
| MST Lookup | GET /lookup | MST Lookup |
| Config | GET, PATCH | Health & Config |
| Health | GET / | Health & Config |
Idempotency
Hỗ trợ idempotency key cho POST requests:
X-Idempotency-Key: unique-key-hereKey được cache trong KV với TTL 24 giờ.