Identificação de cliente

Serve para quando uma página da loja precisa conversar com um sistema seu, e esse sistema precisa saber com quem está falando. Uma área logada, um painel, um formulário que já vem preenchido, um histórico que vive fora da CentralCart. A divisão de responsabilidade é o ponto central:

	CentralCart	O seu sistema
Responde	Quem é o cliente	O que fazer com essa informação
Fonte da verdade	A sessão da loja	A sua base

A CentralCart atesta a identidade e para por aí. O que aquele cliente pode ver, fazer ou receber é regra sua, e ela continua onde está hoje.

Por que não dá para ler a sessão direto

Duas saídas parecem óbvias e as duas são armadilhas:

O cookie de sessão é httpOnly e preso ao domínio da loja. O seu backend, em outro domínio, nunca o recebe.
Ler o e-mail pelo JavaScript da página e enviar ao seu servidor não prova nada. Qualquer pessoa manda qualquer e-mail para o seu endpoint.

O passe existe para resolver exatamente isso: o navegador carrega um valor que não serve para nada sozinho, e quem o troca por identidade é o seu servidor.

Antes de começar

Crie uma chave de API na sua loja com o escopo Identificar o cliente logado (customers:identify) e guarde como secret no seu backend.

Essa chave nunca vai para o HTML nem para o JavaScript da página. Ela fica só no seu servidor. É ela que dá sentido ao passe, então quem tiver a chave pode resolver qualquer passe daquela loja.

O fluxo

A página pede um passe

A chamada acontece no próprio domínio da loja, então a sessão do cliente é reconhecida sozinha. Não precisa enviar token nenhum.

const res = await fetch('/auth/handoff')

if (res.status === 401) {
  // ninguém logado nesta aba
  window.location.href = '/login'
  return
}

const { handoff, expires_in } = await res.json()

A página entrega o passe ao seu backend

const res = await fetch('https://your-system.com/api/session', {
  method: 'POST',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ handoff }),
})

Libere CORS para o domínio da loja. Não é preciso cookie da CentralCart nessa chamada, porque a autenticação é o passe.

O seu backend troca o passe pela identidade

De servidor para servidor, com a sua chave de API.

const r = await fetch('https://api.centralcart.io/v1/app/customer/identify', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${CC_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ handoff }),
})

if (!r.ok) return new Response('invalid handoff', { status: 401 })

const { customer } = await r.json()

O passe é consumido nesse instante. Uma segunda troca do mesmo passe falha.

O seu sistema segue com a regra dele

Agora você sabe quem é. O que vem depois é seu.

const record = await yourDatabase.findByEmail(customer.email)

if (!record) return new Response('not found', { status: 403 })

// emita a sua própria sessão e devolva o que a página precisa

Emita a sua sessão aqui. O passe serve para começar, não para repetir a cada requisição.

A página completa

O exemplo abaixo é uma página do tema, com cabeçalho e rodapé normais da loja.

<% layout "layouts/layout", page_title: 'Minha área' %>

<div class="container py-12 min-h-screen">
  <% unless user %>
    <h1 class="text-2xl font-bold mb-2">Acesso restrito</h1>
    <p class="text-muted-foreground mb-6">Entre na sua conta para continuar.</p>
    <a href="/login" class="btn-primary">Fazer login</a>
  <% else %>
    <div id="app">Carregando...</div>

    <script>
      (async () => {
        const target = document.getElementById('app')

        const { handoff } = await fetch('/auth/handoff').then((r) => r.json())

        const res = await fetch('https://your-system.com/api/session', {
          method: 'POST',
          credentials: 'include',
          headers: { 'content-type': 'application/json' },
          body: JSON.stringify({ handoff }),
        })

        if (res.status === 403) {
          target.innerHTML = '<p>Você não tem acesso a esta área.</p>'
          return
        }

        const data = await res.json()
        // monte a página com o que o seu sistema devolveu
      })()
    </script>
  <% endunless %>
</div>

O <% unless user %> é experiência, não proteção. Ele evita mostrar uma tela quebrada para quem não está logado. Quem decide de verdade é o seu backend, porque é ele que guarda os dados.

Emitir o passe

GET /auth/handoff

Fica no domínio da loja, não em api.centralcart.io. É justamente por ser a mesma origem que o cookie de sessão chega sozinho.

{
  "handoff": "V1StGXR8Z5jdHi6BmyT0eQx7KpLmN3cWaF9uYbZQsRtVhJdG",
  "expires_in": 60
}

Sem cliente logado, responde 401 com { "error": "CUSTOMER_UNAUTHENTICATED" }. O teto é de 20 passes por minuto, por cliente. Uma página legítima pede um por carregamento.

Trocar o passe

Ver Identificar o cliente logado para a referência completa do endpoint.

{
  "customer": {
    "store_id": 1234,
    "email": "[email protected]",
    "name": "Fulano de Tal",
    "avatar": null,
    "discord_id": null,
    "issued_at": "2026-09-22T14:03:11.284Z"
  }
}

O email é a identidade do cliente na loja, e é por ele que você casa com a sua base.

O que sustenta a segurança disso

O passe não serve sozinho. Sem a chave de API da loja, ninguém o resolve.
Vale uma vez. A primeira troca consome o passe.
Vale 60 segundos. Tempo de atravessar da página para o seu servidor, e nada além disso.
Vale só na loja que o emitiu. Uma chave de outra loja não resolve.
Não carrega sessão. Trocar o passe devolve identidade, nunca um token que permita agir como aquele cliente.
Revogação imediata. Revogue a chave no painel e a integração para na hora.

Não coloque o passe na URL. Ele é credencial, e query string sobra em log de acesso, em Referer e no histórico do navegador. Por isso a troca é POST com o passe no corpo.

Perguntas frequentes

Dá para usar isso fora de uma página da loja?

Não. O passe depende do cookie de sessão, que só é enviado no domínio da loja. Para um front em outro domínio, use a Storefront API, onde o próprio comprador faz login e recebe um token.

E se o que eu preciso saber já está na CentralCart?

Então não precisa de nada disso. Se a pergunta é “este cliente comprou tal produto”, a tag load orders aceita package_id e responde direto no template, sem sistema externo no meio. Veja Obtendo dados.O passe existe para o caso contrário: a resposta está numa base que é sua.

Posso guardar o passe para usar depois?

Não. Ele morre em 60 segundos e no primeiro uso. Guarde a sua própria sessão depois da troca.

Documentação da API

Endpoints de aplicação

Storefront API (Public)

Identificação de cliente

Por que não dá para ler a sessão direto

Antes de começar

O fluxo

A página completa

Emitir o passe

Trocar o passe

O que sustenta a segurança disso

Perguntas frequentes

​Por que não dá para ler a sessão direto

​Antes de começar

​O fluxo

​A página completa

​Emitir o passe

​Trocar o passe

​O que sustenta a segurança disso

​Perguntas frequentes

Por que não dá para ler a sessão direto

Antes de começar

O fluxo

A página completa

Emitir o passe

Trocar o passe

O que sustenta a segurança disso

Perguntas frequentes