Mini-loja do WhatsApp

O que é a mini-loja do WhatsApp, como o token de sessão funciona e o mapa das rotas de sessão, identificação e cadastro.

A mini-loja é a loja web leve que abre quando o cliente toca no link que recebe no WhatsApp da loja (ou entra pela página /wa do site). Ela usa o mesmo catálogo, o mesmo carrinho e o mesmo checkout da loja, numa interface pensada para o celular. O número de WhatsApp da loja funciona em coexistência (wa-coex): o mesmo número atende no aplicativo WhatsApp Business e pela API da plataforma. As rotas /api/v1/storefront/wa-coex/... são a API dessa mini-loja.

Esta seção cobre a base de tudo: como obter e usar o token da mini-loja, como abrir a sessão, como o cliente se identifica e como a loja entrega nome, cores e regras ao front-end. Catálogo, sacola, checkout e pedidos estão nas seções irmãs (veja os cartões no fim da página).

Pontos-chave

Não há cabeçalho Authorization. A credencial é o token da mini-loja, que vai no caminho da URL (/session/{token}). Quem tem o token age como aquele visitante ou cliente, então trate-o como uma senha.
Um token é de visitante (sem conta, criado por POST /guest) ou de link (amarrado a um número de WhatsApp, entregue pela conversa). Os dois valem 90 dias por padrão; a loja pode alterar esse prazo.
Dinheiro é sempre inteiro em centavos (7992 = R$ 79,92). Ids são UUID em string.
Os códigos de erro (error) são estáveis e em inglês, em snake_case. Quando existe message, ele já é um texto em português para mostrar ao cliente.
Nenhuma resposta é guardada em cache (Cache-Control: no-store), com as exceções GET /brand e GET /appearance, que têm cache curto e público.

Como funciona

Obter o token→Abrir a sessão→Navegar e montar a sacola→Identificar o cliente→Fechar o pedido

Obter o token
Pela web, chame POST /guest no host da loja: devolve um token de visitante. Pelo WhatsApp, o link enviado ao cliente carrega o token (ou um código curto que GET /short/{code} troca pelo token).
Abrir a sessão
GET /session/{token} diz se o cliente já está identificado, devolve a sacola atual e a mensagem de boas-vindas do assistente.
Ler a aparência e as regras
GET /appearance/{token} traz cores, horário de funcionamento, política de checkout e o mapa de funcionalidades ligadas (store_caps). Use-o para decidir o que mostrar.
Identificar o cliente
O visitante pode navegar e montar a sacola se a loja permitir. Para comprar, ele entra em uma conta existente (link ou código) ou cria uma (cadastro).

Conceitos-chave

O token da mini-loja

O token é uma string opaca, assinada pela plataforma. Ele identifica a loja, o visitante (um identificador sintético para visitantes, o número de WhatsApp para tokens de link) e a origem da visita (campanha). Não tente ler nem montar o token no cliente: peça sempre um novo à plataforma.

Tenant. A loja é resolvida pelo host da requisição (https://minhaloja.io.venddor.com.br). Um token de outra loja usado neste host é recusado com 409 tenant_mismatch.
Validade. Passado o prazo, as rotas respondem 401 token expired. Quando a loja tem número de WhatsApp, a resposta traz restart_url (https://wa.me/<número>) para o cliente pedir um link novo.
Mini-loja desligada. Se a loja desativou a mini-loja, toda rota responde 403 web preview disabled.

Visitante, link e conta

Situação	Como acontece	O que pode
Visitante (`anonymous: true`)	Token de `POST /guest`. Não tem número de WhatsApp.	Navegar e montar a sacola, se a loja permitir (`allow_shopping_unlogged`). Para comprar, entra ou cria conta.
Link de WhatsApp	Token entregue na conversa, com o número do cliente.	Se o número identifica exatamente uma conta ativa, o cliente já entra identificado.
Identificado (`identified: true`)	Entrou por link, código, e-mail/senha ou cadastro.	Preços do cliente, endereços salvos, pedidos, cartões salvos.

A identificação liga o token (e a sacola dele) a uma conta de cliente. Depois de "sair", o número deixa de identificar a conta até um novo login com prova.

Quem pode ver o quê

Cada rota só mostra dados do dono do token. Pedidos, endereços, cartões e anexos são conferidos pelo número ou pela conta ligada ao token, e um pedido de outra pessoa responde 404 order_not_found, igual a um pedido que não existe.

Erros que valem para todas as rotas com `{token}`

Status	`error`	Quando
401	`invalid token`	Token malformado ou com assinatura inválida.
401	`token expired`	Token vencido. Pode vir com `restart_url`.
403	`web preview disabled`	A loja desligou a mini-loja. Vem com `message` em português.
404	`store unavailable`	A loja do token não está disponível.
409	`tenant_mismatch`	O token é de outra loja.
429	(corpo da plataforma)	Limite de requisições por IP. Veja Limites de requisições.

As páginas abaixo listam só os erros próprios de cada rota.

Endpoints

Todas as rotas abaixo são públicas (sem Authorization); a credencial é o token no caminho, exceto onde indicado.

Método	Rota	O que faz	Página
POST	`/api/v1/storefront/wa-coex/guest`	Cria um token de visitante	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/sellers`	Lista os sellers com mini-loja	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/brand`	Nome, logotipo e cores da loja	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/short/{code}`	Troca um código curto de link por token	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/session/{token}`	Estado da sessão, sacola e boas-vindas	Abrir a sessão
POST	`/api/v1/storefront/wa-coex/session/{token}/login-intent`	Marca o início de um login pelo link	Ligar uma conta
POST	`/api/v1/storefront/wa-coex/session/{token}/bind-account`	Liga a conta logada à sessão (cliente)	Ligar uma conta
DELETE	`/api/v1/storefront/wa-coex/session/{token}/bind-account`	Sai da conta (cliente)	Ligar uma conta
POST	`/api/v1/storefront/wa-coex/otp/{token}/request`	Envia código ao WhatsApp do token	Entrar por código
POST	`/api/v1/storefront/wa-coex/otp/{token}/verify`	Confere o código e libera endereços	Entrar por código
POST	`/api/v1/storefront/wa-coex/phone-login/{token}/request`	Entra por e-mail, CPF ou CNPJ	Entrar por código
POST	`/api/v1/storefront/wa-coex/phone-login/{token}/verify`	Confere o código da conta	Entrar por código
GET	`/api/v1/storefront/wa-coex/entry/{token}`	Estado da porta de entrada (CNPJ primeiro)	Cadastro
POST	`/api/v1/storefront/wa-coex/entry/{token}`	Informa o documento da empresa	Cadastro
POST	`/api/v1/storefront/wa-coex/account/{token}`	Cria a conta do cliente	Cadastro
PUT	`/api/v1/storefront/wa-coex/registration-draft/{token}`	Salva o rascunho do cadastro	Cadastro
DELETE	`/api/v1/storefront/wa-coex/registration-draft/{token}`	Apaga o rascunho do cadastro	Cadastro
GET	`/api/v1/storefront/wa-coex/appearance/{token}`	Aparência, horário, política e funcionalidades	Aparência e utilidades
GET	`/api/v1/storefront/wa-coex/geocode/{token}`	CEP ou texto em coordenadas, e o inverso	Aparência e utilidades
POST	`/api/v1/storefront/wa-coex/realtime/{token}`	Credencial temporária para chamada de voz	Aparência e utilidades

Erros comuns

Guardar o token em lugar público. O token é a credencial. Não o coloque em logs, URLs compartilhadas ou analytics.
Reaproveitar um token de visitante depois do 401 token expired. Peça outro com POST /guest; a sacola do token antigo não migra sozinha.
Chamar POST /guest com a loja de vários sellers sem v. A resposta é 409 seller_required. Liste os sellers e repita com ?v=<slug>.
Esperar que GET /session crie conta. Ela só lê. Cadastro e login são rotas próprias.
Ignorar store_caps. As opções da mini-loja (avaliações, cálculo de frete na ficha, cashback...) variam por loja. O mapa store_caps da aparência diz o que está ligado.
Tratar account_required como erro de servidor. É o caminho normal para um visitante que tenta comprar numa loja que exige conta.

Próximos passos

Abrir a sessão

Token de visitante, sellers, marca e estado da sessão.

Cadastro

Porta de entrada, conta nova e rascunho do cadastro.

Catálogo da mini-loja

Listar, buscar e abrir produtos.

Sacola e checkout

Montar a sacola e fechar o pedido.

API atual/Referência completa

Mini-loja do WhatsApp

O que é a mini-loja do WhatsApp, como o token de sessão funciona e o mapa das rotas de sessão, identificação e cadastro.

Pontos-chave

Não há cabeçalho Authorization. A credencial é o token da mini-loja, que vai no caminho da URL (/session/{token}). Quem tem o token age como aquele visitante ou cliente, então trate-o como uma senha.
Um token é de visitante (sem conta, criado por POST /guest) ou de link (amarrado a um número de WhatsApp, entregue pela conversa). Os dois valem 90 dias por padrão; a loja pode alterar esse prazo.
Dinheiro é sempre inteiro em centavos (7992 = R$ 79,92). Ids são UUID em string.
Os códigos de erro (error) são estáveis e em inglês, em snake_case. Quando existe message, ele já é um texto em português para mostrar ao cliente.
Nenhuma resposta é guardada em cache (Cache-Control: no-store), com as exceções GET /brand e GET /appearance, que têm cache curto e público.

Como funciona

Obter o token→Abrir a sessão→Navegar e montar a sacola→Identificar o cliente→Fechar o pedido

Obter o token
Pela web, chame POST /guest no host da loja: devolve um token de visitante. Pelo WhatsApp, o link enviado ao cliente carrega o token (ou um código curto que GET /short/{code} troca pelo token).
Abrir a sessão
GET /session/{token} diz se o cliente já está identificado, devolve a sacola atual e a mensagem de boas-vindas do assistente.
Ler a aparência e as regras
GET /appearance/{token} traz cores, horário de funcionamento, política de checkout e o mapa de funcionalidades ligadas (store_caps). Use-o para decidir o que mostrar.
Identificar o cliente
O visitante pode navegar e montar a sacola se a loja permitir. Para comprar, ele entra em uma conta existente (link ou código) ou cria uma (cadastro).

Conceitos-chave

O token da mini-loja

Tenant. A loja é resolvida pelo host da requisição (https://minhaloja.io.venddor.com.br). Um token de outra loja usado neste host é recusado com 409 tenant_mismatch.
Validade. Passado o prazo, as rotas respondem 401 token expired. Quando a loja tem número de WhatsApp, a resposta traz restart_url (https://wa.me/<número>) para o cliente pedir um link novo.
Mini-loja desligada. Se a loja desativou a mini-loja, toda rota responde 403 web preview disabled.

Visitante, link e conta

Situação	Como acontece	O que pode
Visitante (`anonymous: true`)	Token de `POST /guest`. Não tem número de WhatsApp.	Navegar e montar a sacola, se a loja permitir (`allow_shopping_unlogged`). Para comprar, entra ou cria conta.
Link de WhatsApp	Token entregue na conversa, com o número do cliente.	Se o número identifica exatamente uma conta ativa, o cliente já entra identificado.
Identificado (`identified: true`)	Entrou por link, código, e-mail/senha ou cadastro.	Preços do cliente, endereços salvos, pedidos, cartões salvos.

A identificação liga o token (e a sacola dele) a uma conta de cliente. Depois de "sair", o número deixa de identificar a conta até um novo login com prova.

Quem pode ver o quê

Erros que valem para todas as rotas com `{token}`

Status	`error`	Quando
401	`invalid token`	Token malformado ou com assinatura inválida.
401	`token expired`	Token vencido. Pode vir com `restart_url`.
403	`web preview disabled`	A loja desligou a mini-loja. Vem com `message` em português.
404	`store unavailable`	A loja do token não está disponível.
409	`tenant_mismatch`	O token é de outra loja.
429	(corpo da plataforma)	Limite de requisições por IP. Veja Limites de requisições.

As páginas abaixo listam só os erros próprios de cada rota.

Endpoints

Todas as rotas abaixo são públicas (sem Authorization); a credencial é o token no caminho, exceto onde indicado.

Método	Rota	O que faz	Página
POST	`/api/v1/storefront/wa-coex/guest`	Cria um token de visitante	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/sellers`	Lista os sellers com mini-loja	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/brand`	Nome, logotipo e cores da loja	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/short/{code}`	Troca um código curto de link por token	Abrir a sessão
GET	`/api/v1/storefront/wa-coex/session/{token}`	Estado da sessão, sacola e boas-vindas	Abrir a sessão
POST	`/api/v1/storefront/wa-coex/session/{token}/login-intent`	Marca o início de um login pelo link	Ligar uma conta
POST	`/api/v1/storefront/wa-coex/session/{token}/bind-account`	Liga a conta logada à sessão (cliente)	Ligar uma conta
DELETE	`/api/v1/storefront/wa-coex/session/{token}/bind-account`	Sai da conta (cliente)	Ligar uma conta
POST	`/api/v1/storefront/wa-coex/otp/{token}/request`	Envia código ao WhatsApp do token	Entrar por código
POST	`/api/v1/storefront/wa-coex/otp/{token}/verify`	Confere o código e libera endereços	Entrar por código
POST	`/api/v1/storefront/wa-coex/phone-login/{token}/request`	Entra por e-mail, CPF ou CNPJ	Entrar por código
POST	`/api/v1/storefront/wa-coex/phone-login/{token}/verify`	Confere o código da conta	Entrar por código
GET	`/api/v1/storefront/wa-coex/entry/{token}`	Estado da porta de entrada (CNPJ primeiro)	Cadastro
POST	`/api/v1/storefront/wa-coex/entry/{token}`	Informa o documento da empresa	Cadastro
POST	`/api/v1/storefront/wa-coex/account/{token}`	Cria a conta do cliente	Cadastro
PUT	`/api/v1/storefront/wa-coex/registration-draft/{token}`	Salva o rascunho do cadastro	Cadastro
DELETE	`/api/v1/storefront/wa-coex/registration-draft/{token}`	Apaga o rascunho do cadastro	Cadastro
GET	`/api/v1/storefront/wa-coex/appearance/{token}`	Aparência, horário, política e funcionalidades	Aparência e utilidades
GET	`/api/v1/storefront/wa-coex/geocode/{token}`	CEP ou texto em coordenadas, e o inverso	Aparência e utilidades
POST	`/api/v1/storefront/wa-coex/realtime/{token}`	Credencial temporária para chamada de voz	Aparência e utilidades

Erros comuns

Guardar o token em lugar público. O token é a credencial. Não o coloque em logs, URLs compartilhadas ou analytics.
Reaproveitar um token de visitante depois do 401 token expired. Peça outro com POST /guest; a sacola do token antigo não migra sozinha.
Chamar POST /guest com a loja de vários sellers sem v. A resposta é 409 seller_required. Liste os sellers e repita com ?v=<slug>.
Esperar que GET /session crie conta. Ela só lê. Cadastro e login são rotas próprias.
Ignorar store_caps. As opções da mini-loja (avaliações, cálculo de frete na ficha, cashback...) variam por loja. O mapa store_caps da aparência diz o que está ligado.
Tratar account_required como erro de servidor. É o caminho normal para um visitante que tenta comprar numa loja que exige conta.

Próximos passos

Abrir a sessão

Token de visitante, sellers, marca e estado da sessão.

Cadastro

Porta de entrada, conta nova e rascunho do cadastro.

Catálogo da mini-loja

Listar, buscar e abrir produtos.

Sacola e checkout

Montar a sacola e fechar o pedido.