> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centralcart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação do cliente

> Como logar o comprador na sua vitrine e manter a sessão, com código por e-mail.

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           |

<Warning>
  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.
</Warning>

## Login por código de e-mail

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

<Steps>
  <Step title="Peça o código">
    ```ts theme={null}
    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.
  </Step>

  <Step title="Troque o código pela sessão">
    ```ts theme={null}
    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()
    ```
  </Step>

  <Step title="Use o token">
    ```ts theme={null}
    await fetch('https://api.centralcart.io/v1/webstore/account/order', {
      headers: {
        'x-store-domain': 'sualoja.centralcart.ai',
        Authorization: `Bearer ${access_token}`,
      },
    })
    ```
  </Step>
</Steps>

## E o login social?

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.

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

## 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.

## Sobre o cookie

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