Autenticação do cliente

A Storefront API tem duas identidades bem diferentes, e confundir as duas é o erro mais caro que dá para cometer aqui:

	Chave privada da loja	Sessão do comprador
Quem é	O lojista	O cliente que compra
Onde vive	Só no seu servidor	Navegador do comprador
Header	`Authorization: Bearer <chave-privada>`	`Authorization: Bearer <access_token>`
Pode ler	Todos os pedidos da loja	Só os pedidos daquele e-mail

Os dois usam o header Authorization, mas não são intercambiáveis. A chave privada da loja nunca deve chegar ao navegador: ela dá acesso de escrita a pedidos, produtos e estoque de toda a loja.

É o caminho principal. Não depende de nada externo e funciona de qualquer origem.

Peça o código

await fetch('https://api.centralcart.io/v1/webstore/auth/otp', {
  method: 'POST',
  headers: {
    'x-store-domain': 'sualoja.centralcart.ai',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email }),
})

A resposta é 202 e é sempre igual, tenha o e-mail comprado antes ou não. Não use este endpoint para descobrir se alguém é cliente, porque ele não responde isso de propósito.

Troque o código pela sessão

const res = await fetch('https://api.centralcart.io/v1/webstore/auth/verify', {
  method: 'POST',
  headers: {
    'x-store-domain': 'sualoja.centralcart.ai',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email, code }),
})

const { access_token, customer } = await res.json()

Use o token

await fetch('https://api.centralcart.io/v1/webstore/account/order', {
  headers: {
    'x-store-domain': 'sualoja.centralcart.ai',
    Authorization: `Bearer ${access_token}`,
  },
})

A Storefront API não tem login social, e é decisão consciente. O fluxo OAuth precisa devolver o token para um domínio que pertence à loja, então uma vitrine hospedada em outro domínio, como minhaloja.vercel.app, nunca receberia o retorno. As saídas seriam o lojista criar o próprio aplicativo no Google, ou existir uma credencial capaz de emitir sessão de qualquer comprador. As duas cobram caro para economizar dois cliques de quem está comprando. O código por e-mail entrega a mesma sessão, de qualquer origem e sem configuração.

Nada disso muda o storefront da CentralCart: lá o comprador continua entrando com Google e Discord normalmente.

A sessão

O access_token vale 30 dias, o mesmo prazo do cookie usado pelo storefront da CentralCart. Não existe revogação do lado do servidor: POST /webstore/auth/logout limpa o cookie, e o encerramento do Bearer é descartar o token no seu front. Se a sua aplicação precisa de logout imediato e garantido, guarde o token em memória ou em um cookie de sessão, e não em localStorage. Para saber se a sessão ainda vale, chame GET /webstore/auth/session. Um 401 com code CUSTOMER_UNAUTHENTICATED significa que é hora de mandar o comprador logar de novo. Todo endpoint que cria sessão também emite o cookie _cc_acct. Isso existe para que uma loja consiga migrar para headless aos poucos, com o front novo e páginas do storefront da CentralCart convivendo no mesmo domínio. Se a sua vitrine roda em outro domínio, ignore o cookie: navegador não envia cookie entre origens diferentes, e é exatamente por isso que o Bearer existe.

O que a sessão dá acesso

O escopo é sempre o e-mail do token. Não há parâmetro para consultar os pedidos de outra pessoa, e um pedido que não é do comprador responde 404.

GET /webstore/auth/session
GET /webstore/account/order
GET /webstore/account/order/{order_id}
POST /webstore/order/{orderId}/feedback, que também aceita o ?t= do link do pedido para quem avalia sem ter logado

Documentação da API

Endpoints de aplicação

Storefront API (Public)

Autenticação do cliente

A sessão

O que a sessão dá acesso

​Login por código de e-mail

​E o login social?

​A sessão

​Sobre o cookie

​O que a sessão dá acesso

Login por código de e-mail

E o login social?

A sessão

Sobre o cookie

O que a sessão dá acesso