Criar cliente

Cadastra um cliente pessoa física ou jurídica, um administrador ou um usuário de seller.

Use esta operação quando o cadastro nasce fora da vitrine: um ERP que exporta sua base, um atendimento que abre a conta por telefone, uma migração de outro sistema. O cliente criado já pode entrar com o e-mail e a senha, comprar e receber os e-mails de cadastro que a loja tiver configurado (o mesmo evento de cadastro de uma conta criada na vitrine é disparado).

Antes de criar, procure o e-mail e o documento com Listar clientes: o e-mail é único entre os usuários não excluídos, e o CPF só pode existir em uma conta ativa.

POST/api/v1/admin/usersAdmin

Cria um usuário

Exige manage_users. O corpo muda conforme o tipo de pessoa:

PF: mande first_name (e last_name), e cpf se a loja exigir.
PJ: mande cnpj e legal_name (razão social). trade_name e responsible_name são opcionais. Quem manda cnpj sem declarar person_type está criando uma empresa: o cadastro nasce PJ.

Um usuário admin criado é ligado automaticamente ao grupo de administradores padrão da loja, para nunca ficar sem acesso. Os privilégios dele vêm dos grupos.

Corpo da requisição

emailstringobrigatório

E-mail de login. Vira minúsculo. Formato válido e ainda não usado por outro usuário.

passwordstringobrigatório

Senha inicial. Esta rota não aplica a regra de senha forte; use pelo menos 10 caracteres com maiúscula, minúscula, número e símbolo, a mesma regra de Acesso e senha.

first_namestring

Nome. Obrigatório para PF. Numa PJ é preenchido pela plataforma com a razão social.

last_namestring

Sobrenome. Numa PJ é sempre gravado vazio.

phonestring

Telefone, gravado em formato internacional (11 3333-4444 vira +551133334444).

user_typestringpadrão: customer

customervendoradmin

Papel. Outro valor causa erro 500.

statusstringpadrão: A

ADP

Status inicial. Aceita a letra ou a palavra (active, disabled, pending). Use P para um cadastro que ainda será aprovado.

person_typestring

FPFJPJ

Tipo de pessoa. Se omitido, o tipo fica sem declarar e é deduzido do documento (CNPJ presente é PJ), a não ser que você mande cnpj, caso em que nasce J.

cpfstring

CPF, com ou sem máscara. Validado pelos dígitos. Único entre contas ativas.

cnpjstring

CNPJ, com ou sem máscara (aceita o formato alfanumérico). Validado pelos dígitos. Cria ou entra na conta corporativa daquele CNPJ.

legal_namestring

Razão social. Obrigatória para PJ (ou envie first_name e last_name, que serão juntados).

trade_namestring

Nome fantasia. Opcional.

responsible_namestring

Pessoa que opera a conta PJ. Gravada no campo de perfil responsible_name.

responsible_cpfstring

CPF do responsável da PJ. Só é gravado se for um CPF válido.

languagestringpadrão: pt-BR

pt-BRenes

Idioma da conta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contato@paodoce.example.com",
    "password": "Troque-Esta-Senha-9!",
    "cnpj": "11.222.333/0001-81",
    "legal_name": "Padaria Pão Doce Ltda",
    "trade_name": "Pão Doce",
    "responsible_name": "João Pereira",
    "phone": "11 3333-4444"
  }'

Resposta

201Cliente PJ criado

json

{
  "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "email": "contato@paodoce.example.com",
  "user_type": "customer",
  "status": "A",
  "first_name": "Padaria Pão Doce Ltda",
  "last_name": "",
  "phone": "+551133334444",
  "cnpj": "11222333000181",
  "legal_name": "Padaria Pão Doce Ltda",
  "trade_name": "Pão Doce",
  "language": "pt-BR",
  "currency": "BRL",
  "timezone": "America/Sao_Paulo",
  "email_verified": false,
  "login_count": 0,
  "is_root": false,
  "account_type": "individual",
  "person_type": "J",
  "person_type_declared": true,
  "display_name": "Pão Doce",
  "responsible_name": "João Pereira",
  "created_at": "2026-10-11T20:55:51.332285Z",
  "updated_at": "2026-10-11T20:55:51.332285Z",
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "firstname": "Padaria Pão Doce Ltda",
  "lastname": "",
  "tax_id": "11222333000181",
  "timestamp": 1791752151,
  "updated_timestamp": 1791752151
}

A resposta é o usuário completo, com os campos descritos em Consultar cliente. Repare no espelho da PJ: first_name é a razão social e last_name é vazio.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"unexpected end of JSON input"}`
400	Falta nome (PF) ou senha	`{"error":"email, password, and first_name are required"}`
400	Falta razão social (PJ)	`{"error":"email, password, and legal_name are required for a PJ customer"}`
400	E-mail já em uso	`{"error":"email already registered"}`
400	E-mail inválido	`{"error":"invalid email format"}`
400	CPF ou CNPJ com dígito verificador errado	`{"error":"invalid CPF"}` ou `{"error":"invalid CNPJ"}`
400	`person_type` desconhecido	`{"error":"invalid person_type: Q (want F/PF or J/PJ)"}`
400	`person_type` PJ sem `cnpj`, ou PF sem `cpf` numa loja que exige CPF	`{"error":"cnpj required for person type PJ"}` ou `{"error":"cpf required for person type PF"}`
401	Sem credenciais, chave inválida ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_users`	`{"error":"insufficient privileges","required":"manage_users"}`
500	CPF já registrado em outra conta	`{"error":"failed to create user","detail":"CPF already registered by another user"}`
500	`user_type` inválido	`{"error":"failed to create user","detail":"o valor enviado está fora da faixa permitida (campo relacionado a \"user_type\"). Corrija o valor e reenvie."}`

Veja também