ADR-047 — HTTP API conventions

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-047-http-api-conventions.md

ADR-047: HTTP API conventions

Estado

Accepted — 2026-08-23

Contexto

ADR-012 fija REST /api/v1 + OpenAPI. Faltan errores, paginación e idempotencia — IVPrior lo tenía en su ADR-014 largo.

Detalle de codes: docs/architecture/DOC-005-api-conventions.md.

Decisión

  1. JSON request/response. Fechas ISO-8601. UUID en path.
  2. Paginación: page + pageSize (default 20, max 100) + total. Filtros query: status, customerId, agingBucket, q.
  3. Errores:
{
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Human-readable en-US",
    "details": [],
    "requestId": "…"
  }
}
  1. HTTP: 400 validación, 401 auth, 403 rol/tenant, 404, 409 conflicto, 429 rate limit, 500 inesperado.
  2. Idempotencia: header Idempotency-Key en POST de import CSV, send message, record promise. Reintento = misma respuesta.
  3. X-Request-Id / requestId en logs (ADR-028).
  4. Listados siempre scoped por organizationId del token (ADR-018).
  5. PATCH parcial; no PUT que pise relaciones enteras sin brief.

Consecuencias

  • OpenAPI documenta error.code del DOC-005.
  • Tests de contrato cubren 403 cross-tenant.