Saltar a contenido

Convenciones de la API

Reglas comunes a todos los endpoints REST de Gestión Civis.

Prefijo y versión

  • Todos los endpoints cuelgan de /api/.
  • Cada módulo registra su blueprint con su prefijo (ver Arquitectura).

Formato de respuesta

Convención documentada (objetivo)

// Éxito
{ "status": "ok", "data": { } }

// Error
{ "error": { "code": "MODULO-ERROR-CODE", "message": "...", "source": { }, "detail": { } } }

En la práctica

El formato de error es uniforme y está garantizado por el manejador global de AppException (ver Sistema de errores). El formato de éxito varía según el endpoint y su antigüedad: muchos devuelven directamente el recurso o una lista, y otros usan envoltorios ({"mensaje": "...", ...}).

Recomendación para endpoints nuevos

Mantener el formato de error vía AppException y, para nuevas respuestas de éxito, tender al envoltorio {"status": "ok", "data": ...} por coherencia.

Autenticación

  • Cabecera: Authorization: Bearer <access_token>.
  • Excepcionalmente se admite el token por query param token (p. ej. para servir PDFs de informes directamente desde el navegador).
  • Ver Autenticación y autorización.

Paginación, orden y filtros

Convención por query params:

Parámetro Significado
page Página (1-based).
per_page Tamaño de página.
sort Campo de ordenación.
order asc / desc.

La respuesta de un listado paginado incluye total_count. Muchos listados admiten además filtros específicos del recurso (por estado, ejercicio, texto, etc.) — documentados en cada módulo.

Listados por cursor

Algunos listados de gran volumen (p. ej. auditoría MOS) usan paginación por cursor en lugar de page/per_page.

Códigos de estado HTTP

Código Uso habitual
200 OK.
201 Recurso creado.
204 Sin contenido (también preflight CORS).
400 Error de validación / negocio (AppException por defecto).
401 No autenticado o token expirado (AUTH-TOKEN-EXPIRED).
403 Sin permiso (@permiso_required).
404 Recurso no encontrado.
413 Fichero demasiado grande (> 10 MB).

CORS

  • En desarrollo, orígenes permitidos: http://localhost:5173 y http://127.0.0.1:5173.
  • Cabeceras expuestas: incluye Content-Disposition (para descargas).
  • En producción, ajustar los orígenes permitidos al dominio real.

Multi-tenancy

La aplicación es multi-entidad: casi todos los recursos llevan entidad_id. El decorador @token_required inyecta entidad_id desde el token y los handlers deben filtrar siempre por esa entidad.