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

Entrar por código

Envia e confere códigos de verificação pelo WhatsApp, e entra em uma conta existente informando e-mail, CPF ou CNPJ.

Quando o cliente abre o link recebido no WhatsApp, o número do link já o identifica (veja Mini-loja do WhatsApp). Estas quatro rotas cobrem os casos em que isso não basta: confirmar o número com um código antes de mostrar dados sensíveis, ou entrar em uma conta cadastrada com outro telefone.

O código tem 6 dígitos, vale 15 minutos, só existe um código válido por número (um novo invalida o anterior) e aceita 5 tentativas. Cada número recebe no máximo 3 códigos a cada 15 minutos.

Pedir um código ao número do token

POST/api/v1/storefront/wa-coex/otp/{token}/requestPública

Envia um código de 6 dígitos ao WhatsApp do token

Sem corpo. A mensagem sai do número da loja para o número do token.

Parâmetros de caminho

tokenstringobrigatório

Token de link.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/otp/$TOKEN/request"

Resposta

200Código enviado

json

{ "sent": true, "to": "•••••••••8888" }

Campos da resposta

sentboolean

Sempre true.

tostring

Número de destino com todos os dígitos trocados por "•" menos os 4 últimos, para mostrar ao cliente onde olhar.

Erros

Status	Quando	Corpo
409	O WhatsApp só permite mensagem livre dentro de 24 h da última mensagem do cliente, e essa janela fechou. Peça ao cliente para mandar uma mensagem à loja e tente de novo.	`{"error":"whatsapp_window_closed"}`
429	Já foram enviados 3 códigos nos últimos 15 minutos.	`{"error":"too_many_requests"}`
502	O envio falhou por outro motivo.	`{"error":"whatsapp_send_failed"}`

Conferir o código do número

POST/api/v1/storefront/wa-coex/otp/{token}/verifyPública

Confere o código e libera os endereços salvos

Confirma que quem está na tela controla o número. Em caso de sucesso devolve os endereços salvos da conta desse número (leitura protegida por código).

Parâmetros de caminho

tokenstringobrigatório

Token de link.

Corpo da requisição

codestringobrigatório

Código recebido.

200Código válido

json

{
  "verified": true,
  "name": "Maria Souza",
  "addresses": [
    { "id": "7b1a...", "street": "Avenida Paulista", "number": "1000", "city": "São Paulo", "state": "SP", "zip": "01310-100" }
  ]
}

Campos da resposta

verifiedboolean

Sempre true.

namestring

Nome da conta do número. Ausente se o número não tem conta.

addressesarray

Endereços salvos. Se a loja não permite vários endereços, vem no máximo um. Ausente se o número não tem conta.

Erros

Status	Quando	Corpo
400	`code` ausente ou corpo inválido.	`{"error":"code required"}`
401	Código errado, vencido ou já usado, ou mais de 5 tentativas.	`{"error":"invalid or expired code"}`
500	Falha ao conferir.	`{"error":"..."}`

Entrar em uma conta por e-mail, CPF ou CNPJ

POST/api/v1/storefront/wa-coex/phone-login/{token}/requestPública

Começa o login de uma conta pelo documento ou e-mail

O cliente digita o identificador da conta (e-mail, CPF ou CNPJ). Duas coisas podem acontecer:

Se a conta encontrada tem este mesmo número de WhatsApp, o cliente é identificado na hora, sem código. Faz sentido: o link já provou o número.
Se a conta tem outro telefone, o código é enviado a esse telefone da conta, não ao número do link. O cliente nomeia a conta mas não escolhe para onde o código vai.

Parâmetros de caminho

tokenstringobrigatório

Token de link (não vale token de visitante).

Corpo da requisição

identifierstringobrigatório

E-mail, CPF ou CNPJ da conta, com ou sem pontuação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/phone-login/$TOKEN/request" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "123.456.789-09"}'

Resposta

200Conta do próprio número: entrou direto

json

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

200Conta de outro telefone: código enviado

json

{ "sent": true, "to": "•••••••••1234" }

Campos da resposta

identifiedboolean

true quando entrou direto. Neste caso não há phone-login/verify.

user_iduuid

Id da conta (só no login direto).

sentboolean

true quando o código foi enviado.

tostring

Telefone da conta que recebeu o código, mascarado (só os 4 últimos dígitos aparecem).

Erros

Status	Quando	Corpo
403	Token de visitante.	`{"error":"whatsapp_identity_required"}`
404	Nenhuma conta com esse identificador.	`{"error":"account_not_found"}`
409	A conta não tem telefone cadastrado para receber o código.	`{"error":"account_phone_missing"}`
409	A conta já está ligada a outro cliente neste número.	`{"error":"account_binding_conflict"}`
409	Janela de 24 h do WhatsApp fechada.	`{"error":"whatsapp_window_closed"}`
429	Limite de 3 códigos em 15 minutos.	`{"error":"too_many_requests"}`
502	O envio falhou.	`{"error":"whatsapp_send_failed"}`
503	Falha ao procurar a conta, abrir a sacola ou ligar a conta.	`{"error":"account_lookup_failed"}`, `{"error":"cart_unavailable"}` ou `{"error":"account_binding_unavailable"}`

Conferir o código da conta

POST/api/v1/storefront/wa-coex/phone-login/{token}/verifyPública

Confere o código e liga a conta ao número do link

Só vale depois de um phone-login/request que respondeu sent: true. Se o código confere, a conta é ligada ao token. Nenhum JWT é emitido: a credencial da mini-loja continua sendo o token.

Parâmetros de caminho

tokenstringobrigatório

Token de link.

Corpo da requisição

codestringobrigatório

Código de exatamente 6 dígitos.

200Conta ligada

json

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

Campos da resposta

verifiedboolean

Sempre true.

identifiedboolean

Sempre true.

user_iduuid

Id da conta ligada.

namestring

Nome da conta. Pode vir vazio se a leitura do cadastro falhar.

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"code_required"}`
422	O código não tem exatamente 6 dígitos.	`{"error":"invalid_code_format"}`
409	Não há login pendente (`request` não foi chamado, ou o pedido venceu).	`{"error":"code_not_requested"}`
401	Código errado ou vencido.	`{"error":"invalid_otp"}`
409	A conta já pertence a outro cliente neste número.	`{"error":"account_binding_conflict"}`
500	Falha ao conferir.	`{"error":"otp_check_failed"}`
503	Falha ao abrir a sacola ou ligar a conta.	`{"error":"cart_unavailable"}` ou `{"error":"account_binding_unavailable"}`

Veja também

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

Entrar por código

Envia e confere códigos de verificação pelo WhatsApp, e entra em uma conta existente informando e-mail, CPF ou CNPJ.

Pedir um código ao número do token

POST/api/v1/storefront/wa-coex/otp/{token}/requestPública

Envia um código de 6 dígitos ao WhatsApp do token

Sem corpo. A mensagem sai do número da loja para o número do token.

Parâmetros de caminho

tokenstringobrigatório

Token de link.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/otp/$TOKEN/request"

Resposta

200Código enviado

json

{ "sent": true, "to": "•••••••••8888" }

Campos da resposta

sentboolean

Sempre true.

tostring

Número de destino com todos os dígitos trocados por "•" menos os 4 últimos, para mostrar ao cliente onde olhar.

Erros

Status	Quando	Corpo
409	O WhatsApp só permite mensagem livre dentro de 24 h da última mensagem do cliente, e essa janela fechou. Peça ao cliente para mandar uma mensagem à loja e tente de novo.	`{"error":"whatsapp_window_closed"}`
429	Já foram enviados 3 códigos nos últimos 15 minutos.	`{"error":"too_many_requests"}`
502	O envio falhou por outro motivo.	`{"error":"whatsapp_send_failed"}`

Conferir o código do número

POST/api/v1/storefront/wa-coex/otp/{token}/verifyPública

Confere o código e libera os endereços salvos

Confirma que quem está na tela controla o número. Em caso de sucesso devolve os endereços salvos da conta desse número (leitura protegida por código).

Parâmetros de caminho

tokenstringobrigatório

Token de link.

Corpo da requisição

codestringobrigatório

Código recebido.

200Código válido

json

{
  "verified": true,
  "name": "Maria Souza",
  "addresses": [
    { "id": "7b1a...", "street": "Avenida Paulista", "number": "1000", "city": "São Paulo", "state": "SP", "zip": "01310-100" }
  ]
}

Campos da resposta

verifiedboolean

Sempre true.

namestring

Nome da conta do número. Ausente se o número não tem conta.

addressesarray

Endereços salvos. Se a loja não permite vários endereços, vem no máximo um. Ausente se o número não tem conta.

Erros

Status	Quando	Corpo
400	`code` ausente ou corpo inválido.	`{"error":"code required"}`
401	Código errado, vencido ou já usado, ou mais de 5 tentativas.	`{"error":"invalid or expired code"}`
500	Falha ao conferir.	`{"error":"..."}`

Entrar em uma conta por e-mail, CPF ou CNPJ

POST/api/v1/storefront/wa-coex/phone-login/{token}/requestPública

Começa o login de uma conta pelo documento ou e-mail

O cliente digita o identificador da conta (e-mail, CPF ou CNPJ). Duas coisas podem acontecer:

Se a conta encontrada tem este mesmo número de WhatsApp, o cliente é identificado na hora, sem código. Faz sentido: o link já provou o número.
Se a conta tem outro telefone, o código é enviado a esse telefone da conta, não ao número do link. O cliente nomeia a conta mas não escolhe para onde o código vai.

Parâmetros de caminho

tokenstringobrigatório

Token de link (não vale token de visitante).

Corpo da requisição

identifierstringobrigatório

E-mail, CPF ou CNPJ da conta, com ou sem pontuação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/phone-login/$TOKEN/request" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "123.456.789-09"}'

Resposta

200Conta do próprio número: entrou direto

json

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

200Conta de outro telefone: código enviado

json

{ "sent": true, "to": "•••••••••1234" }

Campos da resposta

identifiedboolean

true quando entrou direto. Neste caso não há phone-login/verify.

user_iduuid

Id da conta (só no login direto).

sentboolean

true quando o código foi enviado.

tostring

Telefone da conta que recebeu o código, mascarado (só os 4 últimos dígitos aparecem).

Erros

Status	Quando	Corpo
403	Token de visitante.	`{"error":"whatsapp_identity_required"}`
404	Nenhuma conta com esse identificador.	`{"error":"account_not_found"}`
409	A conta não tem telefone cadastrado para receber o código.	`{"error":"account_phone_missing"}`
409	A conta já está ligada a outro cliente neste número.	`{"error":"account_binding_conflict"}`
409	Janela de 24 h do WhatsApp fechada.	`{"error":"whatsapp_window_closed"}`
429	Limite de 3 códigos em 15 minutos.	`{"error":"too_many_requests"}`
502	O envio falhou.	`{"error":"whatsapp_send_failed"}`
503	Falha ao procurar a conta, abrir a sacola ou ligar a conta.	`{"error":"account_lookup_failed"}`, `{"error":"cart_unavailable"}` ou `{"error":"account_binding_unavailable"}`

Conferir o código da conta

POST/api/v1/storefront/wa-coex/phone-login/{token}/verifyPública

Confere o código e liga a conta ao número do link

Só vale depois de um phone-login/request que respondeu sent: true. Se o código confere, a conta é ligada ao token. Nenhum JWT é emitido: a credencial da mini-loja continua sendo o token.

Parâmetros de caminho

tokenstringobrigatório

Token de link.

Corpo da requisição

codestringobrigatório

Código de exatamente 6 dígitos.

200Conta ligada

json

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

Campos da resposta

verifiedboolean

Sempre true.

identifiedboolean

Sempre true.

user_iduuid

Id da conta ligada.

namestring

Nome da conta. Pode vir vazio se a leitura do cadastro falhar.

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"code_required"}`
422	O código não tem exatamente 6 dígitos.	`{"error":"invalid_code_format"}`
409	Não há login pendente (`request` não foi chamado, ou o pedido venceu).	`{"error":"code_not_requested"}`
401	Código errado ou vencido.	`{"error":"invalid_otp"}`
409	A conta já pertence a outro cliente neste número.	`{"error":"account_binding_conflict"}`
500	Falha ao conferir.	`{"error":"otp_check_failed"}`
503	Falha ao abrir a sacola ou ligar a conta.	`{"error":"cart_unavailable"}` ou `{"error":"account_binding_unavailable"}`