B04 · Convenções da API: versionamento, erros, paginação e Scramble #6

Contexto

Admin, site público e app consomem a mesma API. Um contrato consistente evita retrabalho nos três clientes.

Escopo

• Prefixo /api/v1 e roteamento por módulo
• Envelope de erro único (code, message, errors, request_id) para validação, autenticação, autorização, não encontrado e erro interno
• Paginação por cursor para listas grandes e por página para listas administrativas, com meta e links
• API Resources padrão e convenção de datas (ISO 8601 em UTC) e valores monetários (centavos, inteiro, mais moeda)
• Instalar e configurar Scramble, agrupando a documentação por módulo e exigindo autenticação em ambiente de produção
• Middleware Idempotency-Key para endpoints que criam pedido ou cobrança
• Header X-Request-Id propagado para logs

Critérios de aceite

• /docs/api mostra a OpenAPI gerada e é válida
• Toda resposta de erro segue o envelope, inclusive 404 e 500
• Teste automatizado garante que toda rota de /api/v1 aparece na documentação

Notas técnicas

• Valores em centavos evitam erro de ponto flutuante
• Documentar a convenção em docs/api.md

Depende de

• B01 · Criar o esqueleto do backend Laravel 13 #3
• B02 · Modularizar com internachi/modular e teste de arquitetura #4

Definição de pronto

• Testes passando na CI
• Lint e análise estática sem erros
• Documentação atualizada (OpenAPI via Scramble no backend, ou README do módulo no front)
• Revisado por pelo menos uma pessoa