Patrones de Desarrollo API

Este documento describe los patrones arquitectónicos de la API. Para documentación específica de endpoints, navega a las secciones por dominio en el menú lateral.

Dominios API

Command API Tenants, Auth, Users

Remuneraciones API Empleados, Contratos, Nómina

Common API Indicadores, Parámetros

Arquitectura de Flujo de Solicitudes

El Orchestrator implementa una arquitectura estricta por capas donde cada capa tiene una responsabilidad específica.

flowchart LR
    A[Solicitud HTTP]
    B[authenticateToken]
    C[getDatabaseNameForUser]
    D[getTenantPool]
    E[Lógica de Negocio]
    F[Manejador de Errores]
    G[Respuesta JSON]

    A --> B
    B -->|req.user poblado| C
    C -->|dbName| D
    D -->|pool| E

    E -->|Éxito| G
    E -->|Fallo| F
    F --> G

Patrón de Integración Frontend

Sevastopol se integra con el Orchestrator usando un patrón de proxy simple. Todas las rutas API en Sevastopol son proxies delgados que reenvían solicitudes.

sequenceDiagram
    participant I as 🏝️ SolidJS Island
    participant AF as 🔐 authenticatedFetch
    participant API as 📡 API Astro
    participant PX as ↔️ createProxy
    participant O as 🎯 Orchestrator

    I->>AF: fetch('/api/admin/chart-of-accounts')
    AF->>AF: Adjunta cookie sid
    AF->>API: HTTP request

    API->>PX: createProxy()
    PX->>O: Reenviar a :8000

    O-->>PX: JSON (snake_case)
    PX-->>API: Respuesta
    API-->>AF: JSON
    AF-->>I: Datos parseados

Convenciones de Respuesta

Matriz de Códigos de Estado

Código	Caso de Uso	Ejemplo
`200`	GET/PUT exitoso	Recurso obtenido o actualizado
`201`	POST exitoso	Recurso creado
`204`	DELETE exitoso	Recurso eliminado (sin cuerpo)
`400`	Entrada inválida	Campos requeridos faltantes
`401`	No autorizado	Sin token o token inválido
`403`	Prohibido	Token válido pero sin permisos
`404`	No encontrado	El recurso no existe
`409`	Conflicto	Recurso duplicado
`500`	Error interno	Error de base de datos