Mapa de APIs

O que você encontra aqui

Esta nota funciona como referência rápida dos endpoints mais importantes que implementamos no admin e no ecommerce.

Ela não substitui as notas conceituais. Ela serve como mapa operacional.

Envelope padrão de resposta

Hoje existem dois perfis de API no projeto:

• admin (/api/ecommpanel/*), com no-store;
• pública versionada (/api/v1/*), com Cache-Control para leitura rápida e integração.

Admin

As APIs do admin usam dois helpers importantes:

export function jsonNoStore(payload: unknown, init?: ResponseInit): NextResponse {
  const response = NextResponse.json(payload, init);
  response.headers.set('Cache-Control', 'no-store, max-age=0');
  return response;
}

export function errorNoStore(status: number, error: string, details?: unknown): NextResponse {
  return jsonNoStore({ error, ...(details ? { details } : {}) }, { status });
}

Leitura guiada

Isso significa que, em geral, as respostas seguem dois formatos:

sucesso

{
  "ok": true
}

ou um documento específico como user, page, template, routes.

erro

{
  "error": "Mensagem de erro",
  "details": {}
}

Pública versionada

As APIs públicas usam envelope estável:

{
  "version": "v1",
  "generatedAt": "2026-03-18T03:00:00.000Z",
  "data": {},
  "meta": {}
}

E são publicadas com cache HTTP para suportar storefront, integrações e futuro app mobile sem acoplar tudo ao painel.

Pedidos operacionais

O projeto agora separa:

• conta do cliente;
• pedido operacional;
• rastreio público.

Isso se reflete em três frentes de API:

• POST /api/ecommerce/order-draft
• GET/GET/PATCH /api/ecommpanel/orders*
• GET /api/v1/orders/[publicToken]

Logística

O projeto agora expõe uma camada de simulacao logistica para storefront, integrações e futuro mobile.

Storefront interno

• POST /api/ecommerce/logistics/simulate

Uso:

• simular entrega e retirada na PDP;
• simular cobertura e SLA no carrinho;
• travar a opcao escolhida no checkout.

API pública versionada

• POST /api/v1/logistics/simulate
• GET /api/v1/catalog/products?postalCode=...&mode=delivery|pickup
• GET /api/v1/catalog/products/[slug]?postalCode=...&mode=delivery|pickup

Uso:

• storefront desacoplado;
• simuladores externos;
• futuro app usando a camada pública do projeto.
• leitura de sortimento já filtrado por regionalização.

API autenticada de integração

• POST /api/integration/v1/logistics/simulate
• GET /api/integration/v1/catalog/products?postalCode=...&mode=delivery|pickup
• GET /api/integration/v1/catalog/products/[slug]?postalCode=...&mode=delivery|pickup

Escopo:

• logistics.read

Uso:

• backends headless;
• apps autenticados;
• serviços parceiros que precisem de SLA, cobertura e retirada com governança por chave.
• apps que precisem listar apenas o sortimento atendível naquele CEP ou modo.

Operação de pedidos no painel

• GET /api/ecommpanel/orders
• GET /api/ecommpanel/orders/[orderId]
• PATCH /api/ecommpanel/orders/[orderId]

Uso:

• abrir fila operacional;
• revisar detalhe;
• atualizar status, contato, endereço e observações.

Clientes

O domínio de clientes também ficou separado do admin e do pedido operacional.

Hoje existem duas frentes:

• storefront e Minha conta;
• operação interna pelo painel.

Cliente no storefront

• POST /api/ecommerce/account/login
• POST /api/ecommerce/account/register
• POST /api/ecommerce/account/register/verify
• POST /api/ecommerce/account/login-token/request
• POST /api/ecommerce/account/login-token/verify
• GET /api/ecommerce/account/me
• PUT /api/ecommerce/account/profile
• GET/POST /api/ecommerce/account/addresses
• GET /api/ecommerce/account/lgpd/export
• POST /api/ecommerce/account/lgpd/request-erasure

Uso:

• cadastro inicial com confirmação opcional por e-mail;
• validação do cadastro pendente por código;
• login por código;
• consulta da conta;
• manutenção de perfil e endereços;
• exportação e solicitação de exclusão da conta.

Cliente no painel

• GET /api/ecommpanel/customers
• POST /api/ecommpanel/customers
• GET /api/ecommpanel/customers/[customerId]
• PUT /api/ecommpanel/customers/[customerId]
• GET /api/ecommpanel/customers/lgpd
• PUT /api/ecommpanel/customers/lgpd/policies
• GET /api/ecommpanel/customers/[customerId]/lgpd
• POST /api/ecommpanel/customers/[customerId]/lgpd

Uso:

• cadastrar cliente completo pelo time operacional;
• editar dados PF/PJ;
• manter conta ativa/inativa;
• operar exportação, solicitação e anonimização LGPD.
• aprovar ou rejeitar solicitações antes da execução;
• manter política de retenção por categoria de dado.
• revisar múltiplos endereços e consentimentos;
• preparar o cliente para atendimento, pedido manual e checkout assistido.

Auth do admin

`POST /api/ecommpanel/auth/login`

Faz login e cria sessão.

request

{
  "email": "main@ecommpanel.local",
  "password": "Admin@123456"
}

success

{
  "ok": true,
  "user": {
    "id": "usr-main-001",
    "email": "main@ecommpanel.local",
    "roleIds": ["main_admin"],
    "permissions": ["site.layout.manage", "site.content.manage"]
  },
  "csrfToken": "...",
  "mustChangePassword": false
}

erros comuns

• 400 quando falta email ou senha
• 401 para credenciais invalidas
• 423 para conta bloqueada
• 429 para rate limit

`GET /api/ecommpanel/auth/me`

Retorna a sessão autenticada atual.

success

{
  "authenticated": true,
  "user": {
    "id": "usr-main-001",
    "email": "main@ecommpanel.local"
  },
  "csrfToken": "..."
}

`POST /api/ecommpanel/auth/logout`

Revoga a sessão atual. Exige origem confiável e CSRF quando existe sessão ativa.

success

{
  "ok": true
}

`POST /api/ecommpanel/auth/login-token/request`

Solicita um código de acesso de 6 dígitos por e-mail.

request

{
  "email": "stalinsn@hotmail.com"
}

success

{
  "ok": true,
  "message": "Se o e-mail estiver ativo, o código de acesso será enviado.",
  "deliveryMode": "email",
  "debugCode": "408504",
  "expiresAt": "2026-03-18T23:26:44.902Z"
}

regras

• o código vale por um único login;
• expira em 10 minutos;
• não é permitido reenviar um novo código enquanto existir um ativo para o mesmo usuário.

`POST /api/ecommpanel/auth/login-token/verify`

Consome o código de acesso e cria a sessão do painel.

request

{
  "email": "stalinsn@hotmail.com",
  "code": "408504"
}

success

{
  "ok": true,
  "user": {
    "id": "usr-owner-001",
    "email": "stalinsn@hotmail.com"
  },
  "csrfToken": "...",
  "mustChangePassword": false
}

`POST /api/ecommpanel/auth/forgot-password`

Dispara a recuperação de senha. Quando o SMTP do painel está ativo, envia e-mail com link e token. Sem SMTP, em desenvolvimento, também pode devolver o token de debug.

request

{
  "email": "main@ecommpanel.local"
}

success

{
  "ok": true,
  "message": "Se o e-mail existir e estiver ativo, enviaremos as instrucoes de recuperacao.",
  "deliveryMode": "email",
  "debugResetToken": "...",
  "debugResetUrl": "http://localhost:3000/ecommpanel/reset-password?token=..."
}

`POST /api/ecommpanel/auth/reset-password`

Consome token e troca a senha.

request

{
  "token": "token-recebido",
  "password": "NovaSenha@12345"
}

success

{
  "ok": true,
  "sessionsRevoked": 2
}

Builder do site

`GET /api/ecommpanel/site/routes`

Lista rotas resumidas.

success

{
  "routes": [
    {
      "id": "page-abc",
      "title": "Landing Black Friday",
      "slug": "landing/black-friday",
      "status": "draft",
      "updatedAt": "2026-03-17T10:00:00.000Z",
      "publishedAt": null
    }
  ]
}

`POST /api/ecommpanel/site/routes`

Cria rota e página inicial.

request

{
  "title": "Landing Black Friday",
  "slug": "landing/black-friday",
  "description": "Campanha principal"
}

success

{
  "ok": true,
  "route": {
    "id": "page-abc",
    "title": "Landing Black Friday",
    "slug": "landing/black-friday"
  }
}

erros comuns

• 400 para titulo ou slug ausente
• 400 para slug inválido
• 409 para colisão com rota nativa ou duplicidade

`DELETE /api/ecommpanel/site/routes/[pageId]`

Move a rota para lixeira lógica.

success

{
  "ok": true,
  "route": {
    "id": "page-abc",
    "status": "deleted"
  }
}

`POST /api/ecommpanel/site/routes/[pageId]/restore`

Catalogo do painel

`GET /api/ecommpanel/catalog/products`

Lista os produtos operacionais do catalogo.

success

{
  "products": [
    {
      "id": "prd-123",
      "slug": "arroz-tipo-1-1kg",
      "name": "Arroz Tipo 1 1kg",
      "status": "active",
      "price": 11.43
    }
  ]
}

`POST /api/ecommpanel/catalog/products`

Cria um novo produto no catalogo.

request

{
  "slug": "arroz-tipo-1-1kg",
  "sku": "810001",
  "name": "Arroz Tipo 1 1kg",
  "status": "draft",
  "available": true,
  "price": 11.43,
  "categories": ["Mercearia"],
  "departments": ["Arroz"],
  "collections": ["Ofertas"]
}

`PUT /api/ecommpanel/catalog/products/[productId]`

Atualiza um produto existente.

Catalogo publico

`GET /api/v1/catalog/products`

Lista produtos publicos com filtros, facets e paginação.

filtros principais

• q
• category
• collection
• available
• brand
• dept
• price
• page
• limit
• sort

`GET /api/v1/catalog/products/[slug]`

Retorna o detalhe de um produto.

`GET /api/v1/catalog/categories`

Retorna as categorias derivadas do catalogo ativo.

Restaura da lixeira.

success

{
  "ok": true,
  "route": {
    "id": "page-abc",
    "status": "draft"
  }
}

`GET /api/ecommpanel/site/routes/trash`

Lista rotas removidas lógicamente.

Páginas do builder

`GET /api/ecommpanel/site/pages`

Retorna os documentos completos conhecidos pelo builder.

`POST /api/ecommpanel/site/pages`

Cria página completa a partir de título e slug.

request

{
  "title": "Institucional",
  "slug": "institucional/quem-somos",
  "description": "Pagina institucional"
}

success

{
  "ok": true,
  "page": {
    "id": "page-xyz",
    "title": "Institucional",
    "slug": "institucional/quem-somos",
    "layoutPreset": "institutional"
  }
}

`GET /api/ecommpanel/site/pages/[pageId]`

Retorna uma página específica.

`PUT /api/ecommpanel/site/pages/[pageId]`

Atualiza o documento inteiro da página.

request

{
  "title": "Quem somos",
  "slug": "institucional/quem-somos",
  "description": "Historia da empresa",
  "layoutPreset": "institutional",
  "slots": [
    {
      "id": "main",
      "name": "Main",
      "blocks": []
    }
  ],
  "seo": {
    "title": "Quem somos",
    "description": "Historia da empresa"
  },
  "theme": {
    "preset": "classic"
  }
}

success

{
  "ok": true,
  "page": {
    "id": "page-xyz",
    "title": "Quem somos",
    "slug": "institucional/quem-somos"
  }
}

`POST /api/ecommpanel/site/pages/[pageId]/publish`

Publica a página para o runtime.

success

{
  "ok": true,
  "page": {
    "id": "page-xyz",
    "status": "published"
  }
}

`POST /api/ecommpanel/site/pages/[pageId]/draft`

Volta a página para rascunho.

success

{
  "ok": true,
  "page": {
    "id": "page-xyz",
    "status": "draft"
  }
}

Blog

`GET /api/ecommpanel/blog/authors`

Lista os usuários editoriais ativos que podem ser usados como owner do post.

`GET /api/ecommpanel/blog/posts`

Lista os posts resumidos conhecidos pelo painel.

success

{
  "posts": [
    {
      "id": "post-abc",
      "slug": "runtime-do-site",
      "title": "Como estruturamos o runtime do site",
      "status": "draft",
      "category": "Arquitetura"
    }
  ]
}

`POST /api/ecommpanel/blog/posts`

Cria um post em rascunho.

request

{
  "title": "Como estruturamos o runtime do site",
  "slug": "runtime-do-site",
  "category": "Arquitetura",
  "authorName": "Equipe de Conteúdo"
}

`GET /api/ecommpanel/blog/posts/[postId]`

Retorna o documento completo do post e a fila de comentários conhecida para ele.

`PUT /api/ecommpanel/blog/posts/[postId]`

Atualiza o documento editorial completo.

Campos importantes:

• title
• slug
• excerpt
• category
• tags
• coverImageUrl
• intro
• sections
• outro
• interaction
• seo

`POST /api/ecommpanel/blog/posts/[postId]/publish`

Publica o post no runtime.

success

{
  "ok": true,
  "post": {
    "id": "post-abc",
    "status": "published",
    "slug": "runtime-do-site"
  }
}

`POST /api/ecommpanel/blog/posts/[postId]/draft`

Retorna o post para rascunho e remove o slug do runtime publicado.

`PATCH /api/ecommpanel/blog/posts/[postId]/comments/[commentId]`

Modera comentário.

request

{
  "status": "approved"
}

APIs públicas do blog

`GET /api/blog/posts/[slug]/comments`

Retorna só comentários aprovados.

`POST /api/blog/posts/[slug]/comments`

Cria comentário.

request

{
  "authorName": "Stalin",
  "content": "Gostei do fluxo de publicação."
}

success

{
  "ok": true,
  "visibility": "pending",
  "comment": null
}

Se o post não exigir moderação, visibility pode ser approved e o comment volta preenchido.

`GET /api/blog/posts/[slug]/reactions`

Retorna o resumo público de reações e, quando possível, a reação do usuário atual.

success

{
  "summary": {
    "likes": 10,
    "dislikes": 1,
    "userReaction": "like"
  }
}

`POST /api/blog/posts/[slug]/reactions`

Registra reação.

request

{
  "value": "like"
}

Valores aceitos:

• like
• dislike
• clear

`GET /api/ecommpanel/site/resolve?path=/landing/black-friday`

Endpoint de diagnostico do runtime.

success dinâmico

{
  "source": "dynamic",
  "path": "/landing/black-friday",
  "page": {
    "id": "page-abc",
    "slug": "landing/black-friday"
  }
}

success nativo

{
  "source": "native",
  "path": "/checkout",
  "page": null
}

Template estrutural

`GET /api/ecommpanel/site/template`

Retorna o documento consolidado do template.

success

{
  "template": {
    "schemaVersion": 4,
    "theme": {
      "preset": "classic",
      "campaign": "black-friday",
      "overrides": {}
    },
    "header": {},
    "home": {},
    "footer": {}
  }
}

`PATCH /api/ecommpanel/site/template`

Atualiza o template inteiro e republica o snapshot do storefront.

request

{
  "template": {
    "schemaVersion": 4,
    "theme": {
      "preset": "fresh",
      "campaign": null,
      "overrides": {
        "colorBrandPrimary": "#0f766e"
      }
    }
  }
}

Observação nova:

• home.override agora permite apontar /e-commerce para um slug já publicado e escolher se header e footer continuam visíveis.

Analytics administrativo

`GET /api/ecommpanel/analytics/config`

Retorna a configuração operacional atual de coleta interna, GTM e GA4.

`PATCH /api/ecommpanel/analytics/config`

Atualiza a configuração e publica o snapshot que a loja passa a ler em runtime.

Campos principais:

• internal.enabled
• internal.heartbeatIntervalSeconds
• internal.activeWindowMinutes
• internal.retainDays
• google.enabled
• google.gtmEnabled
• google.gtmContainerId
• google.gaEnabled
• google.gaMeasurementId

Analytics interno

`POST /api/analytics/collect`

Recebe lotes de eventos enviados pelo storefront.

Eventos aceitos hoje:

• page_view
• heartbeat
• interaction_click
• search_submit
• cart_update
• checkout_step

API pública versionada

`GET /api/v1`

Índice rápido dos recursos públicos disponíveis.

`GET /api/v1/content/pages`

Lista páginas dinâmicas publicadas no runtime.

`GET /api/v1/content/pages/[...slug]`

Retorna uma página publicada com slots, SEO e tema.

`GET /api/v1/content/blog/posts`

Lista posts publicados com filtros leves como limit, category e featured.

`GET /api/v1/content/blog/posts/[slug]`

Retorna o post publicado com comentários aprovados e resumo de reações.

`GET /api/v1/catalog/products`

Lista catálogo com filtros de busca, categoria, coleção e disponibilidade.

`GET /api/v1/catalog/products/[slug]`

Retorna o produto com detalhe rico, incluindo pricing, stock, logistics, SEO e variações mock.

`GET /api/v1/catalog/categories`

Lista categorias consolidadas com contagem de produtos e filhos.

`GET /api/v1/system/health`

Expõe um health snapshot simples de conteúdo, blog, template e modo de persistência publicado.

API de integração autenticada

Esta camada não substitui /api/v1.

Ela existe para:

• integrações externas autenticadas;
• app mobile;
• middlewares;
• parceiros técnicos.

Base:

• /api/integration/v1

Fluxo:

1. o cliente de API recebe keyId e secret;
2. troca isso por bearer token em POST /api/integration/v1/auth/token;
3. usa Authorization: Bearer ... nas chamadas seguintes.

`GET /api/integration/v1`

Índice autenticado das rotas disponíveis para o cliente e seus escopos.

`POST /api/integration/v1/auth/token`

Emite bearer token temporário a partir de keyId + secret.

`GET /api/integration/v1/catalog/products`

Lista produtos via escopo catalog.read.

`GET /api/integration/v1/catalog/products/[slug]`

Carrega detalhe de produto via escopo catalog.read.

`GET /api/integration/v1/catalog/categories`

Lista categorias via escopo catalog.read.

`GET /api/integration/v1/catalog/collections`

Lista coleções via escopo catalog.read.

`GET /api/integration/v1/content/pages`

Lista páginas publicadas via escopo content.read.

`GET /api/integration/v1/content/pages/[...slug]`

Carrega uma página publicada via escopo content.read.

`GET /api/integration/v1/content/blog/posts`

Lista posts publicados via escopo content.read.

`GET /api/integration/v1/content/blog/posts/[slug]`

Carrega um post publicado via escopo content.read.

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

Consulta rastreio por token com escopo orders.public.read.

`GET /api/integration/v1/system/health`

Expõe healthcheck autenticado via escopo health.read.

success

{
  "ok": true,
  "template": {
    "schemaVersion": 4,
    "theme": {
      "preset": "fresh"
    }
  }
}

Ecommerce storefront

`POST /api/checkout`

Fecha o pedido no ambiente atual de simulação.

Observação operacional:

• além de responder o orderId, a rota agora registra internamente o evento purchase_complete para alimentar o dashboard de analytics.

request

{
  "orderFormId": "of-123",
  "items": [
    {
      "id": "sku-1",
      "name": "Cafe",
      "quantity": 2,
      "price": 19.9
    }
  ],
  "clientProfileData": {
    "firstName": "Stalin",
    "email": "stalin@example.com"
  },
  "shipping": {
    "selectedAddress": {
      "postalCode": "01001-000",
      "city": "Sao Paulo",
      "state": "SP"
    }
  },
  "payments": [
    {
      "system": "pix",
      "value": 39.8
    }
  ],
  "totalizers": [],
  "value": 39.8
}

success

{
  "orderId": "ORD-ABC123",
  "status": "created"
}

erros comuns

• 400 para carrinho vazio
• 400 para dados do cliente incompletos
• 400 para endereço ausente
• 400 para pagamento ausente

Explicando de forma simples

"O mapa de APIs é o desenho da fronteira entre camadas. Quando o aluno aprende a ler esse mapa, ele para de pensar só em componente visual e passa a entender o sistema como contratos entre cliente, servidor, persistência e runtime."