VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Sessão do cliente

Tudo sobre quem compra na loja: segundo fator, aparelhos conectados, visitante sem conta e verificações de contato.

Esta seção cobre a conta e a sessão de quem compra na loja (o cliente, na vitrine). O login, o cadastro e a renovação de token ficam em Autenticação; aqui está o que o cliente faz depois de entrar e o que o visitante, que ainda não tem conta, precisa para comprar.

As rotas ficam em /api/v1/storefront/. A loja é identificada pelo domínio da chamada (veja Multi-loja) e o cliente logado se identifica com Authorization: Bearer <access_token> (veja Tokens e escopos).

Pontos principais
  • Três situações convivem: cliente logado (token), visitante (só X-Session-ID) e chamada pública (nada). Cada página diz qual se aplica.
  • O X-Session-ID do visitante é um UUID que o seu front-end gera e guarda; ele liga carrinho, perfil e pedido de visitante.
  • 2FA, verificação por código e consulta de CNPJ dependem de módulos que a loja liga. Módulo desligado devolve 403 module_disabled.
  • Estas rotas têm o limite de requisições da família /api/v1/storefront/: 600 por minuto por IP no padrão da plataforma.

Como funciona

Um comprador passa, em geral, por este caminho:

  1. Chega sem conta
    O front-end cria um X-Session-ID, monta o carrinho e guarda dados no perfil do visitante.
  2. Prova o contato
    Se a loja exige, confirma o e-mail por código.
  3. Compra
    Fecha o pedido de visitante, ou cria uma conta e entra (veja Autenticação).
  4. Protege a conta
    Liga o 2FA e confere os aparelhos em Sessões.

Conceitos principais

Cliente, visitante e administrador

O cliente tem conta e token e usa /api/v1/storefront/.... O visitante compra sem conta. O administrador e o seller (lojista) usam /api/v1/admin/... e /api/v1/vendor/...; veja Os três atores.

Sessão

Cada login cria uma sessão presa ao refresh_token. A sessão não é o access_token: encerrar a sessão impede a renovação, e o access token já emitido vale até expirar.

Dinheiro e datas

Valores monetários são inteiros em centavos (2190 = R$ 21,90). Datas são RFC 3339 em UTC. Veja Ids, dinheiro e datas.

Endpoints

MétodoRotaPara quêAutenticação
POST/api/v1/storefront/2fa/setupGera o segredo do autenticador.Cliente
POST/api/v1/storefront/2fa/confirmConfirma o código e ativa o 2FA.Cliente
POST/api/v1/storefront/2fa/disableDesliga o 2FA.Cliente
GET/api/v1/storefront/2fa/statusDiz se o 2FA está ativo.Cliente
GET/api/v1/storefront/sessionsLista as sessões abertas.Cliente
DELETE/api/v1/storefront/sessions/{id}Encerra uma sessão.Cliente
DELETE/api/v1/storefront/sessionsEncerra todas as sessões.Cliente
GET/api/v1/storefront/guest/profileLê o perfil do visitante.X-Session-ID
PUT/api/v1/storefront/guest/profileSalva ou mescla o perfil.X-Session-ID
DELETE/api/v1/storefront/guest/profileApaga o perfil.X-Session-ID
POST/api/v1/storefront/guest/ordersCria o pedido de um visitante.X-Session-ID
POST/api/v1/storefront/otp/sendEnvia o código de verificação.Pública
POST/api/v1/storefront/otp/verifyConfere o código.Pública
GET/api/v1/storefront/otp/statusConsulta se está verificado.Pública
GET/api/v1/storefront/register/cnpj/{cnpj}Consulta o CNPJ para o cadastro.Pública

Erros comuns

  • Mandar o mesmo X-Session-ID para vários visitantes. Cada visitante precisa de um UUID próprio.
  • Derivar o X-Session-ID de e-mail, CPF ou contador: quem adivinhar lê o perfil daquela sessão.
  • Chamar 2fa/setup de novo para "ver o QR code outra vez": isso troca o segredo e desliga o 2FA até o próximo confirm.
  • Tratar o 200 de otp/verify como sucesso sem ler verified.
  • Esperar que encerrar uma sessão derrube o access token na hora.
  • Enviar items no pedido de visitante que não batem com o carrinho (409 cart_mismatch).

Próximos passos

Pedido de visitante
Fechar a compra sem criar conta.
Verificação em duas etapas
Ligar e desligar o segundo fator.
Autenticação
Login, cadastro e renovação de token.
Erros
O formato das respostas de erro.
Anterior
Adoção de conta importada por CNPJ
Próxima
Verificação em duas etapas do cliente
Nesta página
  • Como funciona
  • Conceitos principais
  • Cliente, visitante e administrador
  • Sessão
  • Dinheiro e datas
  • Endpoints
  • Erros comuns
  • Próximos passos