Arquitetura/docs/arquitetura/apis-e-integracoesEtapa 4 de 6
APIs e integrações
O sistema oferece superfícies distintas para navegador público, aplicações autenticadas e operação administrativa. Separar essas superfícies reduz exposição e torna cache, autenticação e auditoria previsíveis.
Recorte da seçãoReferência do sistema
Consulte contratos, decisões e comportamentos atuais do sistema com caminhos diretos para os detalhes relacionados.
Atualizado21 de jul. de 2026
Seções4
Tags4
apiintegracoesheadlesstokens
Nesta página · 4 tópicos
Superfícies
| Superfície | Base | Autenticação | Uso |
|---|---|---|---|
| Pública | /api/v1 | sem credencial | catálogo, conteúdo, logística, rastreio e saúde pública |
| Integração | /api/integration/v1 | key ID + secret para token bearer | apps, parceiros e automações por escopo |
| Administrativa | /api/ecommpanel | sessão + CSRF + RBAC | painel e mutações operacionais |
| Commerce Bridge | /api/bff/* e /api/vtex/* | servidor e credenciais do provedor | adaptação opcional de serviços externos |
Fluxo autenticado
mermaid
Princípios
- CORS não substitui autenticação; clientes fora do navegador continuam capazes de chamar uma URL pública.
- Segredos e tokens nunca entram no bundle do frontend.
- A API pública expõe apenas campos previstos no contrato.
- A integração exige escopo por domínio e pode restringir IP e validade.
- Rotação invalida o segredo anterior conforme o fluxo do cliente.
- Logs registram rota, status, cliente e hashes técnicos sem guardar credencial.
- O healthcheck público informa somente disponibilidade e versão do contrato; diagnóstico detalhado pertence ao painel autenticado.
- Tokens de tradução são inicializados pela fonte autorizada e consumidos atomicamente no PostgreSQL, sem senha compartilhada enviada pelo navegador.
Escopos dinâmicos
Entidades modeladas no Data Studio podem gerar contratos e escopos próprios. O cliente recebe somente as entidades autorizadas, e operações de escrita permanecem separadas das permissões de leitura.
Detalhes exatos estão em 01 - Contratos de API.