API — visão geral

A API é um FastAPI servido em /api/v1. JSON, camelCase, autenticação Bearer JWT (exceto /auth/login, /auth/password/*, /health).

• Base dev: https://api-dev.abys.cloudface.tech/api/v1
• Swagger (interativo): https://api-dev.abys.cloudface.tech/api/v1/docs
• OpenAPI JSON: https://api-dev.abys.cloudface.tech/api/v1/openapi.json

A referência completa é gerada do código (OpenAPI) — sempre fiel. Veja Referência (Swagger).

Grupos de endpoints

Core

• Auth: POST /auth/login · POST /auth/refresh · POST /auth/logout · GET /auth/me · POST /auth/password/forgot · POST /auth/password/reset
• Usuário: PATCH /users/me · GET|PUT /users/me/preferences · GET /stores
• Catálogo/Estoque: GET /lojas · GET /produtos · GET /estoque?lojaId= · GET /produtos/:id/grade

Módulo Remanejamento

• Recomendações: GET /recomendacoes (filtros) · GET /recomendacoes/:id · POST /recomendacoes/:id/{aprovar|recusar|executar}
• Lotes: GET /lotes · GET /lotes/:id · /lotes/:id/{recomendacoes|fluxo|totais} · POST /lotes/:id/recomendacoes/:recoId/{vetar|restaurar}
• Config: GET|PUT /regras · GET|PUT /config/cadence
• Métricas: /metricas/{kpis-dashboard|validacao|efetividade-semanal|aprendizado} · GET /historico

Convenções

• camelCase em todo corpo (request e response).
• RBAC: mutações exigem papel analista/admin; transições de status são validadas no servidor (HTTP 409 em transição inválida).
• Multi-tenant: toda resposta é escopada ao tenant do usuário autenticado.