Contratos de API
Mapa das superfícies estáveis. Consulte o arquivo `route.ts` correspondente antes de alterar payload, status ou cache.
Consulte contratos, decisões e comportamentos atuais do sistema com caminhos diretos para os detalhes relacionados.
Nesta página · 6 tópicos
API pública `/api/v1`
| Recurso | Rotas |
|---|---|
| Conteúdo | /content/pages, /content/pages/[...slug], /content/blog/posts, /content/blog/posts/[slug] |
| Catálogo | /catalog/products, /catalog/products/[slug], /catalog/categories, /catalog/collections |
| Logística | /logistics/simulate |
| Pedido | /orders/[publicToken] |
| Sistema | /system/health |
Leituras públicas usam resposta padronizada e não expõem campos administrativos, credenciais ou dados pessoais. /system/health retorna apenas estado básico do serviço; caminhos físicos, contagens internas e configuração da loja ficam no diagnóstico autenticado.
API de integração `/api/integration/v1`
Replica recursos autorizados com autenticação e escopos. O fluxo é:
- cliente envia
keyIdesecretpara/auth/token; - servidor retorna bearer temporário;
- cliente usa
Authorization: Bearer ...; - middleware valida status, validade, IP e escopo;
- requisição é registrada sem guardar o token puro.
API administrativa `/api/ecommpanel`
Grupos principais: autenticação, usuários, analytics, catálogo, clientes, Data Studio, integrações, logística, mídia, pedidos, promoções, configurações, site e saúde. Mutações exigem sessão, permissão, origem confiável e CSRF.
Conta do cliente
| Rota | Resposta |
|---|---|
/api/ecommerce/account/me | autenticação, expiração e identidade mínima |
/api/ecommerce/account/details | perfil, endereços e pedidos do titular autenticado, carregados sob demanda |
/api/ecommerce/account/password | nova sessão e novo CSRF após revogar as sessões anteriores |
Login por senha ou código não devolve mais o cadastro completo no mesmo payload. A interface conclui a autenticação e busca detalhes somente quando a jornada exige.
Códigos esperados
| Status | Significado |
|---|---|
| 200/201 | sucesso de leitura ou criação |
| 400 | payload inválido |
| 401 | autenticação ausente ou inválida |
| 403 | origem, CSRF ou permissão insuficiente |
| 404 | recurso não encontrado |
| 409 | conflito de estado ou unicidade |
| 423 | conta temporariamente bloqueada |
| 429 | limite de tentativas |
| 503 | dependência autoritativa indisponível |
Compatibilidade
Adições opcionais são preferíveis a mudanças destrutivas. Renomear campo, alterar unidade monetária ou remover status exige versão nova ou janela de migração documentada.