Clientes

Um usuário é qualquer pessoa com login na loja: o cliente que compra, o administrador que opera o painel da loja e o usuário de seller (lojista) que opera o painel de um vendedor do marketplace. Todos moram na mesma tabela e na mesma API. O que muda é o user_type. Esta seção cobre o dia a dia de um cliente: cadastrar, consultar, corrigir, endereçar, ativar, desativar, definir formas de pagamento e ligar a um grupo.

Todas as rotas desta seção ficam em /api/v1/admin/users...: a API de administração, com UUIDs, datas RFC 3339, PF/PJ explícito, histórico de troca de tipo e operações em lote.

Como funciona

Os três tipos de usuário

Existe ainda o tipo root_admin (dono da plataforma), aceito em PUT mas que você não deve usar em integrações.

O ciclo de vida da conta

Mudar o status de um usuário derruba as sessões abertas dele na hora: o token em uso deixa de valer. Aprovar e recusar têm rotas próprias (Alterar cliente). As respostas sempre devolvem a letra. Palavras longas só são aceitas na entrada.

Pessoa física e pessoa jurídica

Essa é a forma canônica de PJ. Ela existe para que leitores antigos de first_name (nota fiscal, e-mails e integrações antigas) continuem vendo o nome inteiro da empresa. Você não precisa montar o espelho: ao criar ou editar uma PJ, a plataforma copia a razão social para first_name e zera last_name. Se você mandar só first_name e last_name junto de um CNPJ, os dois são juntados numa razão social em vez de a chamada ser recusada.

Regras do documento:

• CPF e CNPJ são validados pelos dígitos verificadores. Máscara é aceita (123.456.789-09) e removida antes de gravar. O CNPJ aceita o formato alfanumérico da Receita Federal (letras maiúsculas nas 12 primeiras posições).
• Um CPF só pode existir em uma conta ativa. Um CNPJ pode repetir em várias contas: elas passam a formar uma conta corporativa, e compradores de uma mesma empresa enxergam os pedidos uns dos outros.
• person_type aceita F, PF, J e PJ. Quem nunca teve o tipo declarado (person_type_declared: false) é classificado pelo documento: com CNPJ é PJ, sem CNPJ é PF.
• Trocar o tipo de um cliente existente tem prévia e histórico: veja PF e PJ.

Dados do cliente em três lugares

1. A conta: e-mail, nome, telefone, documento, idioma, status. É o objeto devolvido por Consultar cliente.
2. Os endereços: quantos o cliente quiser, um deles padrão (Endereços).
3. Os campos de perfil: campos que cada loja define (por exemplo, "ramo de atividade"). São lidos e gravados à parte (Campos de perfil).

Como um cliente se liga a um seller

O cadastro do cliente é da loja, e a mesma pessoa pode comprar de vários sellers. A ligação com um seller nasce de um destes fatos:

• Comprou do seller. O cliente aparece na lista de clientes do seller assim que existe um pedido dele (a venda de um pedido pai gera sub-pedidos por seller, veja Pedidos).
• Entrou na carteira do seller. O próprio seller cadastra ou importa clientes na carteira dele, mesmo sem pedido, pelo painel do seller.
• Está num grupo liberado ao seller. Grupos de usuários marcados como gerenciáveis pelo seller deixam o seller colocar clientes neles.

Já o usuário do seller (user_type: "vendor") se liga ao seller por vínculo de equipe (dono ou membro), e a listagem aceita o filtro vendor_id para ver os administradores de um seller.

Autenticação

Faça login (POST /api/v1/auth/login) e use access_token como Bearer. O login tem limite de requisições (429): guarde o token. Cada rota exige um privilégio:

Ids, datas e dinheiro

• Todo id é um UUID em string.
• As datas vêm em RFC 3339 (UTC). Junto delas vêm também os campos de apelido user_id, firstname, lastname, tax_id e timestamp (cadastro em Unix, em segundos).
• Dinheiro é sempre inteiro em centavos (total_spend_centavos).
• Telefones gravados na conta são normalizados para o formato internacional (11 3333-4444 vira +551133334444). O telefone de um endereço é gravado como veio.

Endpoints

Auth: Admin é o administrador, com Authorization: Bearer <JWT> e o privilégio de cada rota.

Grupos de usuários e seus privilégios estão em Grupos de usuários.

Erros comuns

1. Mandar a senha em PUT /users/{id}. A atualização não troca senha: a API recusa com 400 password_not_updatable. Use set-password (Acesso e senha).
2. Criar uma PJ só com first_name. Numa PJ o nome que vale é legal_name. Mande cnpj e legal_name e deixe a plataforma montar first_name.
3. Esperar que um CPF repetido dê 400. Ele volta como 500 com CPF already registered by another user. Pesquise o CPF antes de criar.
4. Usar a palavra do status na saída. status=active funciona na entrada, mas a saída é sempre a letra (A, D, P).
5. Achar que excluir apaga o histórico. A exclusão é lógica; pedidos e endereços continuam ligados ao registro. Para apenas impedir o acesso, desative (D).
6. Procurar a senha na resposta. A plataforma nunca devolve senha nem hash.

Próximos passos