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

Ligar uma conta

Liga a conta de um cliente logado no site ao token da mini-loja (e desliga), com a prova de login feita dentro do link.

O cliente pode já ter uma conta na loja (e-mail e senha, CPF ou CNPJ). Para que a sacola, os preços e os pedidos dessa conta apareçam na mini-loja, o token precisa ser ligado (em inglês, bound) à conta. Estas três rotas fazem a ligação e o caminho de volta ("sair").

A plataforma exige prova de que a mesma pessoa controla o link e a conta. Sem isso, qualquer pessoa logada no navegador poderia puxar para a própria conta a sacola do WhatsApp de outra. A prova é um login feito depois que a tela de login do link foi aberta, no prazo de 15 minutos. O fluxo é:

Avisar que a tela de login abriu
Chame POST /session/{token}/login-intent. A resposta traz um segredo de uso único, o login_intent.
Fazer o login normal da loja
O cliente entra com a rota de login da loja (Login) e você recebe um JWT de cliente.
Ligar a conta ao token
Chame POST /session/{token}/bind-account com o JWT no Authorization e o login_intent no corpo. Dali em diante o token está identificado.

POST/api/v1/storefront/wa-coex/session/{token}/login-intentPública

Registra que a tela de login do link foi aberta

Sem corpo. Gera um segredo válido por 15 minutos, guardado na sacola do token. Cada chamada substitui o segredo anterior.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/session/$TOKEN/login-intent"

Resposta

200Segredo gerado

json

{ "login_intent": "baba71d43bac5d04afdfc31e3e1921d6491bb4ec55285ce2ebd4a8bf286cca3e", "expires_in": 900 }

Campos da resposta

login_intentstring

Segredo de 64 caracteres hexadecimais. Mande-o em bind-account.

expires_ininteger

Validade em segundos (900).

Erros

Status	Quando	Corpo
503	A sacola do token não pôde ser aberta.	`{"error":"cart_unavailable"}`
503	Não foi possível gravar o segredo.	`{"error":"login_intent_unavailable"}`

Ligar a conta

POST/api/v1/storefront/wa-coex/session/{token}/bind-accountCliente

Liga a conta do cliente logado ao token

Exige dois identificadores: o token no caminho e o JWT do cliente no cabeçalho. Só contas de cliente podem ser ligadas (vendedores e administradores recebem 403).

A ligação é aceita quando uma destas condições vale: a conta já está ligada a este token; o telefone da conta é exatamente este número de WhatsApp e foi verificado, e a pessoa não saiu da conta (veja a próxima rota); ou o login_intent confere e o JWT foi emitido depois que a tela de login abriu. Com um token de visitante (sem número de WhatsApp), o login feito no link é a prova inteira.

Cabeçalhos

Authorizationstringobrigatório

Bearer <JWT do cliente>, da rota de login da loja.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

login_intentstring

Segredo devolvido por login-intent. Obrigatório na prática quando o login é a única prova. O segredo é consumido ao ligar com sucesso.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/session/$TOKEN/bind-account" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"login_intent": "baba71d43bac5d04afdfc31e3e1921d6491bb4ec55285ce2ebd4a8bf286cca3e"}'

Resposta

200Conta ligada

json

{ "identified": true, "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10" }

Campos da resposta

identifiedboolean

Sempre true.

user_iduuid

Id da conta ligada.

Depois de ligar, a plataforma ainda leva para a conta as conversas do número e envia ao cliente o aviso de conta pronta, em segundo plano.

Erros

Status	Quando	Corpo
401	Sem `Authorization` válido.	`{"error":"missing authorization header"}`
403	O JWT não é de cliente desta loja.	`{"error":"account_scope_invalid"}`
403	Faltou a prova: segredo ausente, errado, vencido, ou JWT emitido antes da tela de login.	`{"error":"fresh_login_required"}`
409	O token já pertence a outra conta.	`{"error":"account_binding_conflict"}`
409	A conta não está ativa.	`{"error":"account_inactive"}`
409	A conta ou a sacola do token não existe mais.	`{"error":"account_or_cart_unavailable"}`
503	Falha ao gravar a ligação.	`{"error":"account_binding_unavailable"}`

Sair da conta

DELETE/api/v1/storefront/wa-coex/session/{token}/bind-accountCliente

Desliga a conta do token (logout da mini-loja)

A conta do JWT precisa ser a mesma que está ligada ao token. Depois de sair, o número do link deixa de identificar a conta sozinho: um novo login com prova é necessário.

Cabeçalhos

Authorizationstringobrigatório

Bearer <JWT do cliente>.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

scopestring

all

Com all, sai de todos os aparelhos em que a conta estava ligada a este número. Qualquer outro valor, ou ausente, sai só deste aparelho.

200Desligado

json

{ "identified": false }

Erros

Status	Quando	Corpo
401	Sem `Authorization` válido.	`{"error":"missing authorization header"}`
403	O JWT não é de cliente desta loja.	`{"error":"account_scope_invalid"}`
409	A conta do JWT não é a que está ligada.	`{"error":"account_binding_conflict"}`
409	O token não estava ligado a nenhuma conta.	`{"error":"account_not_bound"}`
503	Falha ao desligar.	`{"error":"account_logout_unavailable"}`

Veja também

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

Ligar uma conta

Liga a conta de um cliente logado no site ao token da mini-loja (e desliga), com a prova de login feita dentro do link.

Avisar que a tela de login abriu
Chame POST /session/{token}/login-intent. A resposta traz um segredo de uso único, o login_intent.
Fazer o login normal da loja
O cliente entra com a rota de login da loja (Login) e você recebe um JWT de cliente.
Ligar a conta ao token
Chame POST /session/{token}/bind-account com o JWT no Authorization e o login_intent no corpo. Dali em diante o token está identificado.

POST/api/v1/storefront/wa-coex/session/{token}/login-intentPública

Registra que a tela de login do link foi aberta

Sem corpo. Gera um segredo válido por 15 minutos, guardado na sacola do token. Cada chamada substitui o segredo anterior.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/session/$TOKEN/login-intent"

Resposta

200Segredo gerado

json

{ "login_intent": "baba71d43bac5d04afdfc31e3e1921d6491bb4ec55285ce2ebd4a8bf286cca3e", "expires_in": 900 }

Campos da resposta

login_intentstring

Segredo de 64 caracteres hexadecimais. Mande-o em bind-account.

expires_ininteger

Validade em segundos (900).

Erros

Status	Quando	Corpo
503	A sacola do token não pôde ser aberta.	`{"error":"cart_unavailable"}`
503	Não foi possível gravar o segredo.	`{"error":"login_intent_unavailable"}`

Ligar a conta

POST/api/v1/storefront/wa-coex/session/{token}/bind-accountCliente

Liga a conta do cliente logado ao token

Exige dois identificadores: o token no caminho e o JWT do cliente no cabeçalho. Só contas de cliente podem ser ligadas (vendedores e administradores recebem 403).

Cabeçalhos

Authorizationstringobrigatório

Bearer <JWT do cliente>, da rota de login da loja.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

login_intentstring

Segredo devolvido por login-intent. Obrigatório na prática quando o login é a única prova. O segredo é consumido ao ligar com sucesso.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/session/$TOKEN/bind-account" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"login_intent": "baba71d43bac5d04afdfc31e3e1921d6491bb4ec55285ce2ebd4a8bf286cca3e"}'

Resposta

200Conta ligada

json

{ "identified": true, "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10" }

Campos da resposta

identifiedboolean

Sempre true.

user_iduuid

Id da conta ligada.

Depois de ligar, a plataforma ainda leva para a conta as conversas do número e envia ao cliente o aviso de conta pronta, em segundo plano.

Erros

Status	Quando	Corpo
401	Sem `Authorization` válido.	`{"error":"missing authorization header"}`
403	O JWT não é de cliente desta loja.	`{"error":"account_scope_invalid"}`
403	Faltou a prova: segredo ausente, errado, vencido, ou JWT emitido antes da tela de login.	`{"error":"fresh_login_required"}`
409	O token já pertence a outra conta.	`{"error":"account_binding_conflict"}`
409	A conta não está ativa.	`{"error":"account_inactive"}`
409	A conta ou a sacola do token não existe mais.	`{"error":"account_or_cart_unavailable"}`
503	Falha ao gravar a ligação.	`{"error":"account_binding_unavailable"}`

Sair da conta

DELETE/api/v1/storefront/wa-coex/session/{token}/bind-accountCliente

Desliga a conta do token (logout da mini-loja)

A conta do JWT precisa ser a mesma que está ligada ao token. Depois de sair, o número do link deixa de identificar a conta sozinho: um novo login com prova é necessário.

Cabeçalhos

Authorizationstringobrigatório

Bearer <JWT do cliente>.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

scopestring

all

Com all, sai de todos os aparelhos em que a conta estava ligada a este número. Qualquer outro valor, ou ausente, sai só deste aparelho.

200Desligado

json

{ "identified": false }

Erros

Status	Quando	Corpo
401	Sem `Authorization` válido.	`{"error":"missing authorization header"}`
403	O JWT não é de cliente desta loja.	`{"error":"account_scope_invalid"}`
409	A conta do JWT não é a que está ligada.	`{"error":"account_binding_conflict"}`
409	O token não estava ligado a nenhuma conta.	`{"error":"account_not_bound"}`
503	Falha ao desligar.	`{"error":"account_logout_unavailable"}`