APIs de Integração e Chaves

Objetivo deste guia

Registrar como a camada autenticada de integração funciona no projeto, sem confundir essa superfície com:

• a API pública do storefront;
• a API administrativa do painel;
• a autenticação de cliente final.

Três superfícies diferentes

Hoje o ecossistema tem três camadas de API com objetivos distintos.

1. API pública

Rota base:

• /api/v1

Uso:

• storefront;
• SEO;
• leitura pública;
• futuro consumo simples em app ou integrações sem segredo.

Características:

• sem autenticação;
• cache HTTP habilitado;
• sem PII;
• payload versionado.

2. API de integração autenticada

Rota base:

• /api/integration/v1

Uso:

• app mobile proprietário;
• middlewares;
• ERPs;
• parceiros técnicos;
• automações server-to-server.

Características:

• exige credencial;
• usa keyId + secret para emissão de bearer token;
• trabalha com escopos;
• registra logs operacionais;
• não depende de sessão do painel.

3. API administrativa

Rotas:

• /api/ecommpanel/*

Uso:

• somente o painel admin.

Características:

• sessão server-side;
• CSRF;
• RBAC;
• perfil operacional.

Fluxo de autenticação da integração

Etapa 1. Criar um cliente de API

No painel:

• EcommPanel -> APIs e integrações

Cada cliente guarda:

• nome operacional;
• descrição;
• escopos permitidos;
• allowlist opcional de IPs;
• status ativo/inativo;
• expiração opcional.

No momento da criação, o painel entrega:

• keyId
• secret

Importante:

• o secret só aparece integralmente uma vez;
• depois disso o sistema mantém apenas hash e hint final.

Etapa 2. Emitir bearer token

Entrada:

• POST /api/integration/v1/auth/token

Payload:

{
  "keyId": "ak_xxxxxxxx",
  "secret": "valor-secreto"
}

Resposta:

{
  "version": "v1",
  "generatedAt": "2026-03-25T10:00:00.000Z",
  "data": {
    "accessToken": "itk_xxxxxxxxx",
    "expiresAt": "2026-03-25T22:00:00.000Z",
    "client": {
      "id": "api_abc123",
      "keyId": "ak_xxxxxxxx",
      "name": "App mobile",
      "scopes": ["catalog.read", "content.read"]
    }
  }
}

Etapa 3. Consumir rotas autenticadas

Header:

Authorization: Bearer itk_xxxxxxxxx

Escopos atuais

`catalog.read`

Libera:

• produtos;
• categorias;
• coleções.

`content.read`

Libera:

• páginas publicadas;
• blog publicado.

`health.read`

Libera:

• healthcheck autenticado do ecossistema.

`orders.public.read`

Libera:

• rastreio de pedido por publicToken dentro de contexto autenticado.

`customers.read`

Situação atual:

• reservado para evolução futura.

Observação:

• o escopo já existe como contrato, mas os endpoints de cliente ainda não foram abertos na camada de integração.

Rotas autenticadas disponíveis hoje

Índice e autenticação

• GET /api/integration/v1
• POST /api/integration/v1/auth/token

Catálogo

• GET /api/integration/v1/catalog/products
• GET /api/integration/v1/catalog/products/[slug]
• GET /api/integration/v1/catalog/categories
• GET /api/integration/v1/catalog/collections

Conteúdo

• GET /api/integration/v1/content/pages
• GET /api/integration/v1/content/pages/[...slug]
• GET /api/integration/v1/content/blog/posts
• GET /api/integration/v1/content/blog/posts/[slug]

Pedidos públicos

• GET /api/integration/v1/orders/[publicToken]

Sistema

• GET /api/integration/v1/system/health

Como o painel controla isso

Tela:

• EcommPanel -> APIs e integrações

Ela centraliza:

• criação de clientes de API;
• edição de escopos;
• allowlist de IPs;
• expiração;
• rotação de secret;
• logs recentes;
• referência das rotas autenticadas.

Como o segredo é armazenado

O sistema não guarda o secret puro.

Ele armazena:

• hash do secret;
• hint final;
• metadados da credencial.

O bearer token temporário também não fica salvo em claro:

• apenas o hash do token é persistido;
• o token real é retornado só no momento da emissão.

Logging operacional

Cada chamada autenticada gera trilha com:

• rota;
• método;
• status;
• modo de autenticação (key ou token);
• escopo;
• cliente;
• instante da chamada.

Objetivo:

• auditoria;
• observabilidade;
• investigação futura;
• base para rate limit por cliente e alertas.

O que não fazer

• não embutir secret em código client-side;
• não usar essa camada para storefront público;
• não expor dados pessoais do cliente final pela API de integração sem camada LGPD específica;
• não tratar customers.read como liberado enquanto a superfície correspondente não existir.

Relação com o roadmap

Próximos passos naturais desta frente:

• provider de API keys com rotação agendada;
• playground interno autenticado;
• limite por cliente e por escopo;
• chaves específicas para mobile/backend;
• abertura planejada de recursos privados com política LGPD e masking por campo.

Leituras relacionadas

• 14 - Mapa de APIs
• 16 - API Publica v1 e Cache
• 11 - Painel - Auth RBAC e Segurança
• 26 - Ecommerce - Auth e Seguranca