API REST

La API de Serconsa está construida con FastAPI y sigue el prefijo /api/v1. La documentación interactiva se genera automáticamente:

Swagger UI: /api/v1/docs
ReDoc: /api/v1/redoc

Registro de routers

Todos los routers se incluyen en backend/app/api/router.py (backend/app/api/router.py:96):

router = APIRouter(prefix="/api/v1")
router.include_router(activities_router)
router.include_router(accounting_router)
router.include_router(auth_router)
router.include_router(budgets_router)
router.include_router(budget_items_router)
# ...

Autenticación

Los endpoints protegidos requieren un token JWT en el header:

Authorization: Bearer <token>

Flujo:

POST /api/v1/auth/login → devuelve access_token y refresh_token.
POST /api/v1/auth/refresh → renueva tokens.
GET /api/v1/users/me → datos del usuario autenticado.

Autorización

Los endpoints usan require_permission(modulo, accion) (backend/app/core/deps.py:47). Ejemplo:

@router.get("/{budget_id}", response_model=BudgetResponse)
async def get_budget(
    budget_id: uuid.UUID,
    _admin: User = Depends(require_permission("budgets", "leer")),
    service: BudgetService = Depends(get_budget_service),
):
    return await service.get_budget(budget_id)

El módulo y la acción se comprueban contra la tabla permissions.

Convenciones de endpoints

Listado: GET /recurso con limit, offset, filtros opcionales.
Detalle: GET /recurso/{id}.
Crear: POST /recurso.
Actualizar: PUT /recurso/{id}.
Borrar: DELETE /recurso/{id}.
Cambio de estado: PUT /recurso/{id}/estado.
Acciones específicas: POST /recurso/{id}/accion.

Códigos de respuesta

200: éxito.
201: creado.
204: borrado correctamente.
400: error de validación o dominio.
401: no autenticado.
403: permiso denegado.
404: no encontrado.
409: conflicto (p. ej. presupuesto finalizado).
413: archivo demasiado grande.

Módulos documentados

Para el resto de módulos, consultar la documentación OpenAPI interactiva en /api/v1/docs.