API atual/Referência completa/Mini-loja WhatsApp: sessão

Abrir a sessão

Cria o token de visitante, lista os sellers com mini-loja, lê a marca da loja, troca um código curto por token e abre o estado da sessão.

Estas cinco rotas são o começo de toda visita à mini-loja. As quatro primeiras não exigem token (a loja é resolvida pelo host da requisição) e servem para você chegar a um token válido e pintar a primeira tela. A última, GET /session/{token}, é a que o front-end chama ao abrir a página: ela devolve a sacola atual, se o cliente está identificado e a mensagem de boas-vindas.

Uma loja de vários sellers (seller é o lojista que vende dentro da plataforma) pode ter um número de WhatsApp por seller. Nesse caso a visita precisa dizer de qual seller é a mini-loja: o POST /guest exige o parâmetro v com o slug do seller, que você descobre em GET /sellers.

Criar o token de visitante

POST/api/v1/storefront/wa-coex/guestPública

Cria um token de visitante para a loja do host

Sem corpo. A loja vem do host (https://minhaloja.io.venddor.com.br).

Parâmetros de consulta

vstring

slug do seller. Obrigatório só quando a loja tem mais de um seller com mini-loja; nas demais, é ignorado. Maiúsculas e minúsculas são tratadas igual.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/guest"

Resposta

200Token criado

json

{ "token": "eyJ0IjoiZGZlMjU1NWUt...Y1Fl" }

Campos da resposta

tokenstring

Token de visitante, opaco. Use-o no caminho das demais rotas. Vale 90 dias por padrão.

Erros

Status	Quando	Corpo
403	A loja desligou a mini-loja.	`{"error":"web preview disabled","message":"Nossa loja no WhatsApp não está disponível no momento."}`
404	O host não é de uma loja.	`{"error":"store unavailable"}`
404	`v` não é o slug de um seller com mini-loja.	`{"error":"seller_not_found","message":"Não encontramos essa loja."}`
409	A loja tem vários sellers e `v` não foi enviado.	`{"error":"seller_required","message":"Escolha a loja que você quer abrir."}`
500	Falha ao assinar o token.	`{"error":"..."}`

As mensagens message saem em português, como o servidor as devolve.

Listar os sellers

GET/api/v1/storefront/wa-coex/sellersPública

Lista os sellers com mini-loja ativa

Devolve a lista só quando há mais de um seller dono de número de WhatsApp ativo. Lojas de um seller só, e lojas que vendem o catálogo de todos os sellers juntos (marketplace), recebem multi: false e lista vazia.

200Loja com vários sellers

json

{
  "multi": true,
  "sellers": [
    { "slug": "casa-do-cafe", "name": "Casa do Café", "logo_url": "/uploads/.../logo.png", "short": "94bd7e9a" }
  ]
}

Campos da resposta

multiboolean

true quando o cliente precisa escolher um seller antes de abrir a mini-loja.

sellersarray

Sellers ativos, ordenados pelo nome da empresa.

slugstring

Identificador para o parâmetro v de POST /guest.

namestring

Nome da empresa do seller.

logo_urlstring

Caminho do logotipo. Pode faltar.

shortstring

Os 8 primeiros caracteres do id do seller. O front-end compara com o seller do token.

Os erros são os mesmos de POST /guest (403 e store unavailable).

Ler a marca da loja

GET/api/v1/storefront/wa-coex/brandPública

Nome, logotipo e cores da loja, antes de ter token

Serve para pintar a tela de abertura enquanto o token ainda está sendo criado. Tem cache público de 120 segundos.

200Marca da loja

json

{
  "storefront_layout": "",
  "store_name": "Loja de Demonstração Venddor",
  "logo_url": "/uploads/dfe2555e/theme/logo/logo-v1.png",
  "accent_color": "#2563eb",
  "header_color": "#2563eb",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798"
}

Campos da resposta

storefront_layoutstring

Perfil de layout da loja, usado para desenhar o esqueleto de carregamento. Vazio quando não há.

store_namestring

Nome de exibição da loja.

logo_urlstring

Caminho do logotipo.

accent_colorstring

Cor de destaque, em hexadecimal.

header_colorstring

Cor do cabeçalho, em hexadecimal.

tenant_iduuid

Id da loja deste host. Compare com a loja do token que você guardou: se diferir, descarte o token antes de renderizar. Não é segredo.

Erros próprios: 503 {"error":"brand_unavailable"} quando a plataforma não conseguiu ler as cores do tema (guarde a última marca boa e tente de novo), além do 403 web preview disabled e do 404 store unavailable.

Trocar um código curto por token

GET/api/v1/storefront/wa-coex/short/{code}Pública

Troca o código curto de um link de WhatsApp pelo token

Os links enviados pela conversa podem usar um código curto no lugar do token inteiro. Esta rota devolve o token correspondente, para você guardar em cookie.

Parâmetros de caminho

codestringobrigatório

Código curto do link.

200Token do link

json

{ "token": "eyJ0IjoiZGZlMjU1NWUt...Y1Fl" }

Erro próprio: 404 {"error":"unknown_link"} quando o código não existe (ou não é desta loja). Mais 403 web preview disabled e 404 store unavailable.

Abrir o estado da sessão

GET/api/v1/storefront/wa-coex/session/{token}Pública

Estado da sessão: identificação, sacola e boas-vindas

Chame ao abrir a página. Registra o clique no link (para as métricas da loja) e devolve tudo que a primeira tela precisa.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/session/$TOKEN"

Resposta

200Visitante sem conta

json

{
  "account_required": false,
  "phone_masked": "",
  "anonymous": true,
  "identified": false,
  "welcome": {
    "text": "Olá! Seja bem-vindo(a) à *Loja de Demonstração Venddor*!",
    "buttons": [
      { "id": "welcome:0:comprar", "label": "Quero comprar" },
      { "id": "welcome:2:pedidos", "label": "Meus pedidos" }
    ],
    "login_required": false
  },
  "campaign_ref": "web",
  "cart": {
    "cart_id": "74481399-0286-4dd1-ac8e-13328e00b86d",
    "items": [],
    "subtotal_cents": 0,
    "total_cents": 0,
    "supports_line_selection": true,
    "currency": "BRL",
    "item_count": 0
  }
}

Campos da resposta

account_requiredboolean

true quando a loja exige conta para finalizar a compra (não permite visitante navegar e comprar sem login).

phone_maskedstring

Número de WhatsApp do link com parte dos dígitos mascarada. Vazio para visitante.

anonymousboolean

true para token de visitante. Omitido quando false.

identifiedboolean

true quando o token já está ligado a uma conta de cliente.

namestring

Nome do cliente identificado.

user_iduuid

Id do cliente identificado.

welcomeobject

Abertura do assistente da loja. Ausente quando a loja desligou as boas-vindas. Tem text, buttons (lista de id e label) e login_required.

auth_revokedboolean

true quando o cliente saiu da conta pelo WhatsApp: descarte credenciais guardadas no navegador.

campaign_refstring

Origem da visita (campanha ou web).

cartobject

Sacola atual. Formato completo em Ler a sacola.

draftobject

Rascunho de checkout salvo (nome, e-mail, documento, escolhas anteriores e registration, o rascunho do cadastro). Só aparece em token de link; token de visitante nunca recebe draft.

saved_documentstring

CPF ou CNPJ do cliente identificado, quando a loja reaproveita o documento salvo.

credit_available_centsinteger

Crédito disponível do cliente, em centavos, quando ele tem limite de crédito.

signup_phonestring

Enquanto ninguém está identificado, o WhatsApp do link (dígitos nacionais). O formulário de cadastro o usa como telefone da conta.

Erros

Status	Quando	Corpo
409	O número do link já está ligado a outra conta.	`{"error":"account_binding_conflict"}`
503	Não foi possível montar a sessão.	`{"error":"session_unavailable"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: sessão

Abrir a sessão

Cria o token de visitante, lista os sellers com mini-loja, lê a marca da loja, troca um código curto por token e abre o estado da sessão.

Criar o token de visitante

POST/api/v1/storefront/wa-coex/guestPública

Cria um token de visitante para a loja do host

Sem corpo. A loja vem do host (https://minhaloja.io.venddor.com.br).

Parâmetros de consulta

vstring

slug do seller. Obrigatório só quando a loja tem mais de um seller com mini-loja; nas demais, é ignorado. Maiúsculas e minúsculas são tratadas igual.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/guest"

Resposta

200Token criado

json

{ "token": "eyJ0IjoiZGZlMjU1NWUt...Y1Fl" }

Campos da resposta

tokenstring

Token de visitante, opaco. Use-o no caminho das demais rotas. Vale 90 dias por padrão.

Erros

Status	Quando	Corpo
403	A loja desligou a mini-loja.	`{"error":"web preview disabled","message":"Nossa loja no WhatsApp não está disponível no momento."}`
404	O host não é de uma loja.	`{"error":"store unavailable"}`
404	`v` não é o slug de um seller com mini-loja.	`{"error":"seller_not_found","message":"Não encontramos essa loja."}`
409	A loja tem vários sellers e `v` não foi enviado.	`{"error":"seller_required","message":"Escolha a loja que você quer abrir."}`
500	Falha ao assinar o token.	`{"error":"..."}`

As mensagens message saem em português, como o servidor as devolve.

Listar os sellers

GET/api/v1/storefront/wa-coex/sellersPública

Lista os sellers com mini-loja ativa

200Loja com vários sellers

json

{
  "multi": true,
  "sellers": [
    { "slug": "casa-do-cafe", "name": "Casa do Café", "logo_url": "/uploads/.../logo.png", "short": "94bd7e9a" }
  ]
}

Campos da resposta

multiboolean

true quando o cliente precisa escolher um seller antes de abrir a mini-loja.

sellersarray

Sellers ativos, ordenados pelo nome da empresa.

slugstring

Identificador para o parâmetro v de POST /guest.

namestring

Nome da empresa do seller.

logo_urlstring

Caminho do logotipo. Pode faltar.

shortstring

Os 8 primeiros caracteres do id do seller. O front-end compara com o seller do token.

Os erros são os mesmos de POST /guest (403 e store unavailable).

Ler a marca da loja

GET/api/v1/storefront/wa-coex/brandPública

Nome, logotipo e cores da loja, antes de ter token

Serve para pintar a tela de abertura enquanto o token ainda está sendo criado. Tem cache público de 120 segundos.

200Marca da loja

json

{
  "storefront_layout": "",
  "store_name": "Loja de Demonstração Venddor",
  "logo_url": "/uploads/dfe2555e/theme/logo/logo-v1.png",
  "accent_color": "#2563eb",
  "header_color": "#2563eb",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798"
}

Campos da resposta

storefront_layoutstring

Perfil de layout da loja, usado para desenhar o esqueleto de carregamento. Vazio quando não há.

store_namestring

Nome de exibição da loja.

logo_urlstring

Caminho do logotipo.

accent_colorstring

Cor de destaque, em hexadecimal.

header_colorstring

Cor do cabeçalho, em hexadecimal.

tenant_iduuid

Id da loja deste host. Compare com a loja do token que você guardou: se diferir, descarte o token antes de renderizar. Não é segredo.

Trocar um código curto por token

GET/api/v1/storefront/wa-coex/short/{code}Pública

Troca o código curto de um link de WhatsApp pelo token

Os links enviados pela conversa podem usar um código curto no lugar do token inteiro. Esta rota devolve o token correspondente, para você guardar em cookie.

Parâmetros de caminho

codestringobrigatório

Código curto do link.

200Token do link

json

{ "token": "eyJ0IjoiZGZlMjU1NWUt...Y1Fl" }

Erro próprio: 404 {"error":"unknown_link"} quando o código não existe (ou não é desta loja). Mais 403 web preview disabled e 404 store unavailable.

Abrir o estado da sessão

GET/api/v1/storefront/wa-coex/session/{token}Pública

Estado da sessão: identificação, sacola e boas-vindas

Chame ao abrir a página. Registra o clique no link (para as métricas da loja) e devolve tudo que a primeira tela precisa.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/session/$TOKEN"

Resposta

200Visitante sem conta

json

{
  "account_required": false,
  "phone_masked": "",
  "anonymous": true,
  "identified": false,
  "welcome": {
    "text": "Olá! Seja bem-vindo(a) à *Loja de Demonstração Venddor*!",
    "buttons": [
      { "id": "welcome:0:comprar", "label": "Quero comprar" },
      { "id": "welcome:2:pedidos", "label": "Meus pedidos" }
    ],
    "login_required": false
  },
  "campaign_ref": "web",
  "cart": {
    "cart_id": "74481399-0286-4dd1-ac8e-13328e00b86d",
    "items": [],
    "subtotal_cents": 0,
    "total_cents": 0,
    "supports_line_selection": true,
    "currency": "BRL",
    "item_count": 0
  }
}

Campos da resposta

account_requiredboolean

true quando a loja exige conta para finalizar a compra (não permite visitante navegar e comprar sem login).

phone_maskedstring

Número de WhatsApp do link com parte dos dígitos mascarada. Vazio para visitante.

anonymousboolean

true para token de visitante. Omitido quando false.

identifiedboolean

true quando o token já está ligado a uma conta de cliente.

namestring

Nome do cliente identificado.

user_iduuid

Id do cliente identificado.

welcomeobject

Abertura do assistente da loja. Ausente quando a loja desligou as boas-vindas. Tem text, buttons (lista de id e label) e login_required.

auth_revokedboolean

true quando o cliente saiu da conta pelo WhatsApp: descarte credenciais guardadas no navegador.

campaign_refstring

Origem da visita (campanha ou web).

cartobject

Sacola atual. Formato completo em Ler a sacola.

draftobject

Rascunho de checkout salvo (nome, e-mail, documento, escolhas anteriores e registration, o rascunho do cadastro). Só aparece em token de link; token de visitante nunca recebe draft.

saved_documentstring

CPF ou CNPJ do cliente identificado, quando a loja reaproveita o documento salvo.

credit_available_centsinteger

Crédito disponível do cliente, em centavos, quando ele tem limite de crédito.

signup_phonestring

Enquanto ninguém está identificado, o WhatsApp do link (dígitos nacionais). O formulário de cadastro o usa como telefone da conta.

Erros

Status	Quando	Corpo
409	O número do link já está ligado a outra conta.	`{"error":"account_binding_conflict"}`
503	Não foi possível montar a sessão.	`{"error":"session_unavailable"}`