Convenciones

Naming¶

Endpoints: snake_case en URL (/operations/visits, /billing/sii/documents).
JSON keys: snake_case (clinic_id, total_amount, created_at).
Resources: plural en path (/visits, /tutors), singular en payload id.
Verbos HTTP:
GET lista o detalle
POST crea
PATCH actualiza parcial (preferido sobre PUT)
DELETE borra (soft delete por defecto en entidades con deleted_at)

Header	Valor	Cuándo
`Authorization`	`Bearer <jwt>`	Todos los `/api/v1/*` excepto `/auth/login` y `/auth/register`
`Content-Type`	`application/json; charset=utf-8`	POST/PATCH
`X-Request-ID`	UUID propio (opcional)	Para correlación logs cliente↔servidor
`Idempotency-Key`	UUID único	POST de creación de invoices/payments (Sprint 6)

Headers de respuesta:

Header	Significado
`X-Request-ID`	Echo del cliente o generado server-side
`X-RateLimit-Remaining`	Cuota restante per IP/key
`X-RateLimit-Reset`	Timestamp Unix de reset

Cursor-based (preferido) y offset-based (legacy).

Cursor:

GET /operations/visits?limit=20&cursor=eyJpZCI6Ii4uLiJ9

Response:

{
  "data": [...],
  "next_cursor": "eyJpZCI6Ii4uLiJ9",
  "has_more": true
}

Offset (legacy, soportado en endpoints simples):

GET /operations/visits?limit=20&offset=40

Response:

{
  "data": [...],
  "total_count": 1284,
  "limit": 20,
  "offset": 40
}

Query params snake_case:

GET /billing/invoices?status=emitted&date_from=2026-04-01&date_to=2026-04-30

Para listas multi-valor: comas → ?status=emitted,paid.

Montos en enteros (centavos para CLP, USD): total_amount: 1234500 = $12.345,00.
Currency code ISO 4217: currency: "CLP".
Nunca floats para dinero (precisión).

POSTs financieros (invoices, payments, refunds) aceptan Idempotency-Key: