API conventions

HTTP APIs, errors, and OpenAPI workflow (DOC-005).

Source: docs/architecture/DOC-005-api-conventions.md

DOC-005: API conventions catalog

Estado

Accepted — 2026-08-23

Norma: ADR-012 · ADR-047. Recursos: glosario.

Paths V1 (indicativos)

POST   /api/v1/auth/signup
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
POST   /api/v1/auth/logout
GET    /api/v1/me

GET    /api/v1/customers
POST   /api/v1/customers
GET    /api/v1/customers/:id

GET    /api/v1/invoices
POST   /api/v1/invoices/import
GET    /api/v1/invoices/:id

GET    /api/v1/threads
GET    /api/v1/threads/:id
POST   /api/v1/threads/:id/messages

GET    /api/v1/promises
POST   /api/v1/promises
GET    /api/v1/disputes
GET    /api/v1/tasks
POST   /api/v1/tasks/:id/complete

GET    /api/v1/dashboard/summary

GET    /api/v1/sequences
POST   /api/v1/mailbox/connect   # OAuth start

Webhooks de mailbox: /api/v1/webhooks/mailbox/:provider — firma en adapter (ADR-032).

error.code (inicial)

codeHTTPCuándo
VALIDATION_ERROR400Zod/DTO
UNAUTHENTICATED401Token ausente/inválido
FORBIDDEN403Rol o tenant
ORGANIZATION_MISMATCH403Cross-tenant
NOT_FOUND404
CONFLICT409Unique invoice/import
IDEMPOTENCY_REPLAY200Misma key (no es error; misma body)
RATE_LIMITED429ADR-049
MAILBOX_NOT_CONNECTED409Send sin OAuth
CLASSIFICATION_FAILED503Vendor AI down → Task se crea igual
OPT_OUT409Intento de send a opted-out
INTERNAL500
MAINTENANCE503ADR-077
CSV_MISSING_REQUIRED400ADR-068
CSV_BAD_DATE400
CSV_BAD_MONEY400

Health (sin auth): GET /health/live · GET /health/ready (ADR-070).

Ampliar en el brief que introduzca el caso. No inventar codes en el controller.