VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Autenticação

Cadastro de cliente e seller

Cria a conta de um cliente da loja ou a candidatura de um seller (lojista), com os erros por campo.

Existem dois cadastros públicos. register cria um cliente (quem compra na loja) e já devolve um par de tokens, então a pessoa fica logada. vendor-register cria a conta de um seller (lojista) e a ficha da empresa dele; na maioria das lojas a candidatura fica pendente até um administrador aprová-la, e nenhum token é devolvido.

Os dois exigem aceite das regras da loja e validam CPF e CNPJ pelo dígito verificador. O e-mail é único por loja (sem diferenciar maiúsculas).

Cadastrar um cliente

POST/api/v1/auth/registerPública

Cadastrar um cliente

A loja decide quais campos de perfil são obrigatórios (telefone, campos personalizados). Se faltar algum, a resposta lista os campos. Quando a loja só aceita empresas, um cadastro de pessoa física volta 403 person_type_not_allowed.

Cabeçalhos

Content-Typestringobrigatório
application/json.
X-Recaptcha-Tokenstring
Obrigatório só quando a loja ativou o reCAPTCHA.

Corpo da requisição

emailstringobrigatório
E-mail do cliente.
passwordstringobrigatório
Mínimo de 10 caracteres, com maiúscula, minúscula, dígito e símbolo.
first_namestringobrigatório
Nome. Em pessoa jurídica recebe a razão social inteira.
last_namestring
Sobrenome. Vazio em pessoa jurídica.
terms_acceptedbooleanobrigatório
Aceite dos termos de uso. Sem true a resposta é 400 consent_required.
privacy_acceptedbooleanobrigatório
Aceite da política de privacidade (LGPD). Mesmo efeito.
marketing_consentbooleanpadrão: false
Aceite opcional de comunicação de marketing; a data do aceite é guardada.
person_typestring
FPFJPJ
Pessoa física ou jurídica. Se omitido, vira PJ quando há cnpj e PF nos demais casos.
cpfstring
CPF, com ou sem pontuação (pessoa física).
cnpjstring
CNPJ, com ou sem pontuação (pessoa jurídica).
legal_namestring
Razão social (pessoa jurídica).
trade_namestring
Nome fantasia (pessoa jurídica).
phonestring
Telefone. Obrigatório quando a loja marca o telefone como campo obrigatório.
custom_fieldsobject
Mapa nome_do_campo: valor dos campos de perfil personalizados da loja. Os obrigatórios precisam estar aqui.
addressobject

Primeiro endereço salvo do cliente.

address_line1string
Logradouro.
address_line2string
Número, quando separado.
complementstring
Complemento.
districtstring
Bairro.
citystring
Cidade.
statestring
UF.
postal_codestring
CEP.
countrystringpadrão: BR
País.
labelstring
Nome do endereço.
phonestring
Telefone do endereço.
referral_codestring
Código de indicação, se a loja usa o programa de indicações. Falha em aplicá-lo não impede o cadastro.
accept_pending_sessionbooleanpadrão: false
Veja Login. Se a conta ficar pendente de aprovação, devolve uma sessão restrita.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.souza@example.com",
    "password": "MinhaSenha#2026",
    "first_name": "Maria",
    "last_name": "Souza",
    "cpf": "123.456.789-09",
    "phone": "11987654321",
    "terms_accepted": true,
    "privacy_accepted": true,
    "address": {
      "address_line1": "Avenida Paulista",
      "address_line2": "1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100"
    }
  }'

Resposta

201Conta criada e logada
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "0b6f0c0c7a1d4e5f8a9b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f",
  "expires_at": "2026-10-11T21:10:44Z"
}
200Cadastro aguardando aprovação
json
{
  "status": "pending_approval",
  "detail": "account_pending_approval"
}

O 200 acima acontece quando a loja aprova cadastros manualmente: a conta existe, mas não há token. Se você enviou accept_pending_session: true, a resposta também traz access_token, refresh_token, expires_at e account_status.

Campos da resposta

access_tokenstring
JWT do cliente recém-criado.
refresh_tokenstring
Token de renovação.
expires_atstring
Vencimento do token de acesso, RFC 3339 em UTC.
statusstring
pending_approval
Só na resposta 200 de aprovação pendente.

Erros do cadastro de cliente

StatusQuandoCorpo
400Falta email, password ou first_name{"error":"validation_failed","fields":{"email":"required"}}
400Sem aceite de termos/privacidade{"error":"consent_required","detail":"you must accept the terms of service and privacy policy"}
400Senha fraca{"error":"validation_failed","fields":{"password":"password_too_weak"}}
400CPF ou CNPJ inválido{"error":"validation_failed","fields":{"document":"invalid_cpf","cpf_cnpj":"invalid_cpf"}}
400Campo de perfil obrigatório vazio{"error":"required_field_missing","fields":{"phone":"required"}}
400Restrição de CNAE ou consulta de empresa (situação cadastral, inscrição estadual) reprovou{"error":"cnae_not_accepted","fields":{"cnae":"cnae_not_accepted"}} ou mensagem em português com o motivo em detail
400Qualquer outra falha{"error":"registration_failed"}
403Loja só aceita empresas{"error":"person_type_not_allowed","fields":{"person_type":"person_type_not_allowed"}}
409E-mail já cadastrado{"error":"email_already_registered","fields":{"email":"already_registered"}}
409CPF ou CNPJ já cadastrado{"error":"cpf_already_registered","fields":{"document":"already_registered","cpf":"already_registered"}} (ou cnpj_already_registered)
409CNPJ compartilhado por mais de uma conta, ou conta importada que exige código de possecnpj_ambiguous, cnpj_ownership_verification_required, cnpj_ownership_verification_failed
429Mais de 3 cadastros por minuto do mesmo IP{"error":"rate limit exceeded",...}

Os erros de campo vêm no objeto fields. Para ler o código de cada campo, use o valor, não o texto. As mensagens de reprovação de empresa (situação inativa, inscrição estadual irregular, consulta indisponível) saem em português, como retornadas pelo servidor.

Candidatura de seller

POST/api/v1/auth/vendor-registerPública

Candidatar-se como seller (lojista)

Cria, de uma vez, o usuário (tipo seller) e a ficha da empresa. Quando a loja usa pré-moderação, o seller nasce pendente e só consegue entrar depois da aprovação do administrador; a resposta não traz token. Documentos da candidatura são enviados depois, já logado (veja a área do seller). A loja pode desligar este cadastro; nesse caso a resposta é 403 feature_disabled.

Corpo da requisição

emailstringobrigatório
E-mail de acesso do usuário.
passwordstringobrigatório
Senha, mínimo de 8 caracteres neste cadastro.
first_namestringobrigatório
Nome do responsável.
last_namestring
Sobrenome do responsável.
phonestring
Telefone do responsável.
cpfstring
CPF do responsável.
company_namestringobrigatório
Razão social ou nome da empresa.
cnpjstringobrigatório
CNPJ da empresa, validado pelo dígito verificador.
cnae_codestring
Código CNAE principal.
state_regstring
Inscrição estadual.
vendor_emailstring
E-mail comercial da empresa.
vendor_phonestring
Telefone comercial.
websitestring
Site da empresa.
citystring
Cidade da empresa.
statestring
UF da empresa.
postal_codestring
CEP da empresa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/auth/vendor-register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contato@lojadojoao.example.com",
    "password": "Senha#Forte2026",
    "first_name": "João",
    "last_name": "Pereira",
    "company_name": "Loja do João LTDA",
    "cnpj": "11.222.333/0001-81",
    "vendor_email": "vendas@lojadojoao.example.com",
    "city": "Campinas",
    "state": "SP",
    "postal_code": "13010-111"
  }'

Resposta

201Candidatura criada
json
{
  "user": {
    "id": "5b0f6a52-3c1e-4d0a-9f1e-6a1f0c2d7e11",
    "email": "contato@lojadojoao.example.com",
    "first_name": "João",
    "last_name": "Pereira",
    "user_type": "vendor",
    "status": "P"
  },
  "vendor_id": "9c1e2f4a-7b3d-4a58-8e60-1d2c3b4a5f67"
}

Campos da resposta

userobject
Usuário criado (o exemplo mostra um recorte). id é UUID; user_type é vendor; status é P quando a candidatura aguarda aprovação.
vendor_idstring
UUID da ficha do seller recém-criada.

Erros da candidatura

StatusQuandoCorpo
400Falta email, password, first_name, company_name ou cnpj{"error":"validation_failed","fields":{"_form":"missing_required_fields"}}
400Senha com menos de 8 caracteres{"error":"validation_failed","fields":{"password":"too_short"}}
400CNPJ inválido{"error":"validation_failed","fields":{"cnpj":"invalid_cnpj"}}
400Falha inesperada{"error":"registration_failed"}
403A loja desligou o cadastro de sellers{"error":"feature_disabled","feature":"vendor_registration"}
409E-mail já cadastrado{"error":"validation_failed","fields":{"email":"already_registered"}}
409CPF já cadastrado{"error":"validation_failed","fields":{"cpf":"already_registered"}}
Validação de senha diferente nos dois cadastros

register exige 10 caracteres com maiúscula, minúscula, dígito e símbolo. vendor-register só confere o mínimo de 8 caracteres. Mande sempre uma senha que passe nas regras fortes, para não depender dessa diferença.

Depois do cadastro

Um cliente já cadastrado e logado segue para o catálogo e o carrinho. Um seller aprovado entra pelo login e usa as rotas do painel do seller. Em lojas que exigem e-mail verificado, veja Verificação de e-mail.

Veja também

  • Login e segundo fator
  • Verificações de formato
  • Adoção de conta por CNPJ
  • Os três atores
Anterior
Login e segundo fator
Próxima
Renovar e encerrar a sessão
Nesta página
  • Cadastrar um cliente
  • Exemplo de requisição
  • Resposta
  • Erros do cadastro de cliente
  • Candidatura de seller
  • Exemplo de requisição
  • Resposta
  • Erros da candidatura
  • Veja também