This document defines the exact JSON contract between frontend and backend APIs. NO KEY NAMES SHOULD BE CHANGED WITHOUT PRIOR NOTIFICATION TO FRONTEND TEAM.
v1.0.0
Returns paginated list of invoice summaries.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| page | number | No | 1 | Current page number (1-based) |
| limit | number | No | 20 | Items per page (max 100) |
| minApy | number | No | 0 | Minimum APY filter |
| maxApy | number | No | 100 | Maximum APY filter |
| tiers | string | No | - | Comma-separated risk tiers (A,B,C,D) |
{
"data": [
{
"id": "string",
"riskScore": "number",
"status": "string",
"amount": "number | string",
"apy": "number (optional)",
"riskTier": "string (optional: 'A'|'B'|'C'|'D')"
}
],
"pagination": {
"currentPage": "number",
"totalPages": "number",
"totalItems": "number",
"itemsPerPage": "number",
"hasNextPage": "boolean",
"hasPreviousPage": "boolean"
}
}InvoicesResponse in types/api.ts
Returns risk assessment for a specific invoice.
| Name | Type | Required | Description |
|---|---|---|---|
| invoiceId | string | Yes | Invoice identifier |
{
"invoiceId": "string",
"riskScore": "number",
"scoreRange": {
"min": "number (optional)",
"max": "number (optional)"
},
"grade": "string (optional)",
"factors": {
"string": "number"
} (optional),
"updatedAt": "string (ISO 8601, optional)"
}RiskScoreResponse in types/api.ts
All error responses follow this shape:
{
"error": {
"message": "string (human-readable UI-safe message)",
"code": "string (machine-readable, optional)",
"details": "unknown (optional, for debugging only)"
}
}ApiErrorResponse in types/api.ts
- Integrate Orval or RTK Query code-gen to auto-generate TypeScript types from OpenAPI spec
- Add Swagger/OpenAPI UI for interactive documentation