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

Cadastro do cliente

Porta de entrada por documento, criação da conta pela mini-loja e rascunho do cadastro que o cliente retoma depois.

Um cliente sem conta cria a dele pela própria mini-loja. Estas cinco rotas cobrem o caminho: a porta de entrada (algumas lojas só vendem para empresas e pedem o CNPJ antes de tudo), o cadastro e o rascunho que guarda o que a pessoa já digitou, para ela voltar mais tarde sem perder o formulário.

O telefone da conta nunca vem do corpo da requisição: é o número de WhatsApp do link. Num token de visitante, que não tem número, a conta nasce só com o e-mail.

Ler o estado da porta de entrada

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

Estado da porta de entrada (documento primeiro)

Lojas B2B podem exigir que o comprador informe o documento da empresa antes de ver catálogo, preços e sacola. Enquanto a porta está fechada, as rotas de catálogo respondem 403 entry_required. Esta rota diz o estado real da porta e o que mostrar.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

200Loja sem porta de entrada

json

{ "active": false, "locked": false, "document_label": "CNPJ", "accepts_cpf": false }

Campos da resposta

activeboolean

A loja usa porta de entrada.

lockedboolean

true enquanto catálogo, preços e sacola estão bloqueados para este token.

stagestring

ask_documentawait_logineligibleineligibleunknownpendingunverified

ask_document: peça o documento. await_login: o documento é aceito, mas o cliente ainda precisa entrar na conta. eligible: pode comprar. ineligible: a loja não vende para essa empresa. unknown: ainda não existe conta. pending: a conta aguarda aprovação. unverified: o cadastro público não pôde ser consultado agora.

document_labelstring

Nome do documento a pedir (por padrão CNPJ).

accepts_cpfboolean

A loja também aceita CPF.

companystring

Nome da empresa encontrada, quando o documento já foi informado.

messagestring

Mensagem da loja para uma empresa que ela não atende (stage: ineligible).

linkstring

Link da loja para esse caso.

signup_urlstring

Página de cadastro própria da loja. Vazio significa o cadastro da mini-loja.

Informar o documento

POST/api/v1/storefront/wa-coex/entry/{token}Pública

Informa o CPF ou CNPJ e reavalia a porta de entrada

Identifica a empresa pelo documento digitado e devolve o novo estado da porta (mesmo formato do GET). Se a conta existe e lista este WhatsApp, a escolha é gravada e a conta ligada. Se a loja não usa porta de entrada, devolve o estado vazio sem avaliar o documento.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

documentstringobrigatório

CPF ou CNPJ, com ou sem pontuação. O CNPJ pode ser alfanumérico.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/entry/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document": "11.222.333/0001-81"}'

200Empresa atendida, falta entrar

json

{ "active": true, "locked": true, "stage": "await_login", "document_label": "CNPJ", "accepts_cpf": false, "company": "Comercial Exemplo Ltda" }

Erros

Status	Quando	Corpo
400	Corpo ilegível ou maior que 1 KB.	`{"error":"invalid_body"}`
422	Documento inválido (dígito verificador, tamanho).	`{"error":"invalid_document"}`
422	É um CPF e a loja só aceita empresa.	`{"error":"document_kind_not_accepted"}`

Criar a conta

POST/api/v1/storefront/wa-coex/account/{token}Pública

Cria a conta do cliente e a liga ao token

Cria (ou reconhece) a conta do cliente e já a deixa ligada ao token, então a próxima chamada de GET /session volta com identified: true. Se o número já tem conta, ela é reconhecida sem ser sobrescrita.

Para CNPJ, a plataforma consulta o cadastro público da empresa: o endereço vem de lá, e empresa inativa ou fora das atividades aceitas pela loja é recusada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

namestringobrigatório

Nome completo. Pessoa física precisa de nome e sobrenome; para CNPJ vale a razão social, mesmo com uma palavra só. Se faltar, usa o nome do rascunho.

documentstringobrigatório

CPF ou CNPJ válido.

emailstringobrigatório

E-mail válido. Fica em minúsculas. Se faltar, usa o do rascunho.

terms_acceptedbooleanpadrão: false

Aceite dos termos e da política de privacidade. Obrigatório quando a loja exige (terms_required em checkout_policy).

extra_fieldsobject

Campos de cadastro adicionais que a loja marcou como obrigatórios, como mapa nome_do_campo para texto. A lista vem em registration_required_fields de Aparência. O corpo todo pode ter até 8 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/account/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "document": "123.456.789-09",
    "email": "maria.souza@example.com",
    "terms_accepted": true
  }'

Resposta

200Conta criada e ligada

json

{ "identified": true }

Erros

Todos os erros de regra voltam com 422 e um código. Apenas o corpo ilegível volta 400.

Status	`error`	Quando
400	`invalid_body`	Corpo ilegível ou maior que 8 KB.
422	`full_name_required`	Pessoa física sem sobrenome, ou nome vazio.
422	`invalid_document`	CPF ou CNPJ inválido.
422	`invalid_email`	E-mail ausente ou malformado.
422	`person_type_not_allowed`	A loja só cadastra empresas e o documento é CPF.
422	`consent_required`	A loja exige o aceite dos termos e `terms_accepted` não veio `true`.
422	`required_field_missing:<campo>`	Falta um campo obrigatório da loja. Depois dos dois pontos vem o nome do campo.
422	`cnpj_not_found`, `cnpj_inactive`, `cnae_not_accepted`	O CNPJ não existe no cadastro público, está inativo ou tem atividade que a loja não atende.
422	`registration_failed`	Qualquer outra falha ao criar a conta.
503	`cart_unavailable`	A conta foi criada, mas a ligação à sacola falhou. Repita a chamada: a conta é reconhecida.

Salvar o rascunho do cadastro

PUT/api/v1/storefront/wa-coex/registration-draft/{token}Pública

Salva os campos já digitados do cadastro

O rascunho guarda o formulário no servidor, ligado à sacola do token, para o cliente retomar em outro aparelho. Substitui o rascunho anterior inteiro. Nunca aceita segredos: não há campo de senha, código, captcha nem cartão, e campos desconhecidos são recusados (não ignorados).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

person_typestring

PFPJ

Tipo de pessoa. Aceita minúsculas; a resposta volta em maiúsculas.

stepstring

choosepfpj_cnpjpj_form

Passo do formulário em que a pessoa parou.

documentstring

CPF ou CNPJ. Só letras e números são mantidos (até 14).

first_namestring

Nome. Até 120 caracteres.

last_namestring

Sobrenome. Até 120.

emailstring

E-mail, em minúsculas. Até 254.

phonestring

Telefone. Até 40.

phone_secondarystring

Segundo telefone. Até 40.

trade_namestring

Nome fantasia. Até 200.

responsible_namestring

Nome do responsável. Até 200.

state_registrationstring

Inscrição estadual. Até 80.

addressobject

Endereço.

zipcodestring

CEP. Até 16.

streetstring

Logradouro. Até 240.

numberstring

Número. Até 40.

complementstring

Complemento. Até 160.

districtstring

Bairro. Até 160.

citystring

Cidade. Até 160.

statestring

UF, 2 letras, convertida para maiúsculas.

custom_fieldsobject

Campos adicionais da loja, como mapa texto para texto. No máximo 40 chaves; cada chave com 1 a 80 caracteres entre letras, números, _, . e -; valor com até 500 caracteres. Chaves com password, senha, token, otp, captcha, cvv, pan, card_number, secret ou pin são recusadas.

O corpo inteiro pode ter até 24 KB. Valores são aparados (espaços das pontas removidos) e a plataforma define version sozinha.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/storefront/wa-coex/registration-draft/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_type": "PF",
    "step": "pf",
    "first_name": "Maria",
    "email": "maria.souza@example.com",
    "address": { "zipcode": "01310-100", "state": "SP" }
  }'

Resposta

200Rascunho salvo

json

{
  "version": 1,
  "person_type": "PF",
  "step": "pf",
  "first_name": "Maria",
  "email": "maria.souza@example.com",
  "address": { "zipcode": "01310-100", "state": "SP" }
}

A resposta é o rascunho já limpo (campos vazios omitidos). Não existe GET do rascunho: para um token de link ele volta em draft.registration na resposta de GET /session. Um token de visitante grava o rascunho, mas GET /session não o devolve (o campo draft só existe para tokens de link), então o front-end do visitante precisa guardar uma cópia local.

Erros

Status	Quando	Corpo
400	JSON inválido, campo desconhecido, mais de um valor JSON ou corpo acima de 24 KB.	`{"error":"invalid_registration_draft"}`
422	Valor fora das regras. O `error` é um destes: `invalid_person_type`, `invalid_registration_step`, `invalid_document`, `registration_draft_too_large`, `forbidden_registration_field`.	`{"error":"invalid_person_type"}`
503	Falha ao gravar.	`{"error":"registration_draft_unavailable"}`

Apagar o rascunho

DELETE/api/v1/storefront/wa-coex/registration-draft/{token}Pública

Apaga o rascunho do cadastro

Remove só o rascunho do cadastro, sem tocar na sacola. Chame depois de criar a conta, ou se a pessoa desistir.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Responde 204 No Content, sem corpo. Se não havia rascunho, também responde 204. O erro possível é 503 {"error":"registration_draft_unavailable"}.

Veja também

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

Cadastro do cliente

Porta de entrada por documento, criação da conta pela mini-loja e rascunho do cadastro que o cliente retoma depois.

O telefone da conta nunca vem do corpo da requisição: é o número de WhatsApp do link. Num token de visitante, que não tem número, a conta nasce só com o e-mail.

Ler o estado da porta de entrada

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

Estado da porta de entrada (documento primeiro)

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

200Loja sem porta de entrada

json

{ "active": false, "locked": false, "document_label": "CNPJ", "accepts_cpf": false }

Campos da resposta

activeboolean

A loja usa porta de entrada.

lockedboolean

true enquanto catálogo, preços e sacola estão bloqueados para este token.

stagestring

ask_documentawait_logineligibleineligibleunknownpendingunverified

document_labelstring

Nome do documento a pedir (por padrão CNPJ).

accepts_cpfboolean

A loja também aceita CPF.

companystring

Nome da empresa encontrada, quando o documento já foi informado.

messagestring

Mensagem da loja para uma empresa que ela não atende (stage: ineligible).

linkstring

Link da loja para esse caso.

signup_urlstring

Página de cadastro própria da loja. Vazio significa o cadastro da mini-loja.

Informar o documento

POST/api/v1/storefront/wa-coex/entry/{token}Pública

Informa o CPF ou CNPJ e reavalia a porta de entrada

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

documentstringobrigatório

CPF ou CNPJ, com ou sem pontuação. O CNPJ pode ser alfanumérico.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/entry/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document": "11.222.333/0001-81"}'

200Empresa atendida, falta entrar

json

{ "active": true, "locked": true, "stage": "await_login", "document_label": "CNPJ", "accepts_cpf": false, "company": "Comercial Exemplo Ltda" }

Erros

Status	Quando	Corpo
400	Corpo ilegível ou maior que 1 KB.	`{"error":"invalid_body"}`
422	Documento inválido (dígito verificador, tamanho).	`{"error":"invalid_document"}`
422	É um CPF e a loja só aceita empresa.	`{"error":"document_kind_not_accepted"}`

Criar a conta

POST/api/v1/storefront/wa-coex/account/{token}Pública

Cria a conta do cliente e a liga ao token

Para CNPJ, a plataforma consulta o cadastro público da empresa: o endereço vem de lá, e empresa inativa ou fora das atividades aceitas pela loja é recusada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

namestringobrigatório

Nome completo. Pessoa física precisa de nome e sobrenome; para CNPJ vale a razão social, mesmo com uma palavra só. Se faltar, usa o nome do rascunho.

documentstringobrigatório

CPF ou CNPJ válido.

emailstringobrigatório

E-mail válido. Fica em minúsculas. Se faltar, usa o do rascunho.

terms_acceptedbooleanpadrão: false

Aceite dos termos e da política de privacidade. Obrigatório quando a loja exige (terms_required em checkout_policy).

extra_fieldsobject

Campos de cadastro adicionais que a loja marcou como obrigatórios, como mapa nome_do_campo para texto. A lista vem em registration_required_fields de Aparência. O corpo todo pode ter até 8 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/account/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "document": "123.456.789-09",
    "email": "maria.souza@example.com",
    "terms_accepted": true
  }'

Resposta

200Conta criada e ligada

json

{ "identified": true }

Erros

Todos os erros de regra voltam com 422 e um código. Apenas o corpo ilegível volta 400.

Status	`error`	Quando
400	`invalid_body`	Corpo ilegível ou maior que 8 KB.
422	`full_name_required`	Pessoa física sem sobrenome, ou nome vazio.
422	`invalid_document`	CPF ou CNPJ inválido.
422	`invalid_email`	E-mail ausente ou malformado.
422	`person_type_not_allowed`	A loja só cadastra empresas e o documento é CPF.
422	`consent_required`	A loja exige o aceite dos termos e `terms_accepted` não veio `true`.
422	`required_field_missing:<campo>`	Falta um campo obrigatório da loja. Depois dos dois pontos vem o nome do campo.
422	`cnpj_not_found`, `cnpj_inactive`, `cnae_not_accepted`	O CNPJ não existe no cadastro público, está inativo ou tem atividade que a loja não atende.
422	`registration_failed`	Qualquer outra falha ao criar a conta.
503	`cart_unavailable`	A conta foi criada, mas a ligação à sacola falhou. Repita a chamada: a conta é reconhecida.

Salvar o rascunho do cadastro

PUT/api/v1/storefront/wa-coex/registration-draft/{token}Pública

Salva os campos já digitados do cadastro

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

person_typestring

PFPJ

Tipo de pessoa. Aceita minúsculas; a resposta volta em maiúsculas.

stepstring

choosepfpj_cnpjpj_form

Passo do formulário em que a pessoa parou.

documentstring

CPF ou CNPJ. Só letras e números são mantidos (até 14).

first_namestring

Nome. Até 120 caracteres.

last_namestring

Sobrenome. Até 120.

emailstring

E-mail, em minúsculas. Até 254.

phonestring

Telefone. Até 40.

phone_secondarystring

Segundo telefone. Até 40.

trade_namestring

Nome fantasia. Até 200.

responsible_namestring

Nome do responsável. Até 200.

state_registrationstring

Inscrição estadual. Até 80.

addressobject

Endereço.

zipcodestring

CEP. Até 16.

streetstring

Logradouro. Até 240.

numberstring

Número. Até 40.

complementstring

Complemento. Até 160.

districtstring

Bairro. Até 160.

citystring

Cidade. Até 160.

statestring

UF, 2 letras, convertida para maiúsculas.

custom_fieldsobject

O corpo inteiro pode ter até 24 KB. Valores são aparados (espaços das pontas removidos) e a plataforma define version sozinha.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/storefront/wa-coex/registration-draft/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_type": "PF",
    "step": "pf",
    "first_name": "Maria",
    "email": "maria.souza@example.com",
    "address": { "zipcode": "01310-100", "state": "SP" }
  }'

Resposta

200Rascunho salvo

json

{
  "version": 1,
  "person_type": "PF",
  "step": "pf",
  "first_name": "Maria",
  "email": "maria.souza@example.com",
  "address": { "zipcode": "01310-100", "state": "SP" }
}

Erros

Status	Quando	Corpo
400	JSON inválido, campo desconhecido, mais de um valor JSON ou corpo acima de 24 KB.	`{"error":"invalid_registration_draft"}`
422	Valor fora das regras. O `error` é um destes: `invalid_person_type`, `invalid_registration_step`, `invalid_document`, `registration_draft_too_large`, `forbidden_registration_field`.	`{"error":"invalid_person_type"}`
503	Falha ao gravar.	`{"error":"registration_draft_unavailable"}`

Apagar o rascunho

DELETE/api/v1/storefront/wa-coex/registration-draft/{token}Pública

Apaga o rascunho do cadastro

Remove só o rascunho do cadastro, sem tocar na sacola. Chame depois de criar a conta, ou se a pessoa desistir.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Responde 204 No Content, sem corpo. Se não havia rascunho, também responde 204. O erro possível é 503 {"error":"registration_draft_unavailable"}.