Contratos e acesso às APIs¶
Fontes de verdade¶
contracts/<módulo>/schemas.py: modelos de entrada/saída das APIs.types.py: tipos auxiliares, quando presentes.- Routers e dependências do módulo: rotas e autenticação efetivamente exigidas.
flow-gateway.yaml: mapeamento/rewrite público em Kubernetes.- Clientes internos: consumidores, headers, timeouts e tratamento de erro.
Não copie schemas para outro serviço sem avaliar compatibilidade. Mudanças aditivas com defaults ajudam consumidores antigos; remoções e alterações de semântica exigem plano de rollout e testes de contrato.
Três superfícies diferentes¶
| Superfície | Acesso | Cuidados |
|---|---|---|
| Painel e API da plataforma | Sessão do usuário e autorização por rota/loja | Não confiar no merchant_id fornecido pelo navegador sem validar acesso |
| APIs internas dos serviços | Chave/header definidos no cliente e no destino | Credenciais são diferentes de sessão web; não expor nem publicar exemplos reais |
| Callbacks externos | Validação específica do fornecedor/evento | Handshake Meta não substitui validação dos eventos; WooCommerce usa assinatura associada à loja |
Papéis existentes: super_admin, admin e merchant. A política central fica
em modules/frontend_entrypoint/app/auth/authz.py. Algumas rotas são exclusivas
de superadministrador; staff pode acessar lojas em rotas que permitem isso;
lojista fica limitado à própria loja. Não tratar essa descrição como autorização
global de todos os endpoints: confira a dependência da rota e seus testes.
Explorar uma operação localmente¶
- Use ambiente local com dados fictícios.
- Localize router, schema e cliente consumidor da operação.
- Consulte o OpenAPI/Swagger local do módulo quando habilitado; não exponha interfaces internas no domínio público só para explorar contratos.
- Confira header/cookie exigido, contexto de loja e campos opcionais.
- Teste sucesso, falta de autenticação, acesso a outra loja, erro externo e compatibilidade com payloads antigos.
Respostas queued indicam agendamento, não conclusão. Resposta HTTP de webhook
também não comprova entrega de mensagem ou indexação final. Erro de rede não é
prova de credencial inválida. Use request/job ID e diagnóstico.