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, ativar, desativar, consultar crédito e acompanhar pedidos.

As rotas ficam em /api/v1.0/users... e seguem o contrato da Venddor 1.0, para integrações escritas para a plataforma antiga (ERP, CRM, app do vendedor). As respostas trazem user_id, firstname, status em letra e datas em Unix.

Como funciona

Os três tipos de usuário

Qualquer letra diferente de A e V vira cliente (C), sem erro. Por isso, ao alterar um usuário, não mande user_type se você não quer rebaixá-lo.

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. Para aprovar um cadastro pendente, mude o status de P para A com Alterar cliente. As respostas sempre devolvem a letra. Palavras longas só são aceitas na entrada.

Pessoa física e pessoa jurídica

A API 1.0 não tem um campo de tipo de pessoa. A diferença está no documento:

• Pessoa jurídica: o cadastro tem CNPJ. Ao criar ou alterar com CNPJ, o nome informado (firstname) vira a razão social. A lista e a consulta devolvem CNPJ apenas quando o usuário tem um, só com dígitos, sem máscara.
• Pessoa física: o cadastro não tem CNPJ. O CPF não é devolvido por esta API.

O CNPJ é validado pelos dígitos verificadores. Máscara é aceita (11.222.333/0001-81) e removida antes de gravar. Um mesmo 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.

Dados do cliente em três lugares

1. A conta: e-mail, nome, telefone, CNPJ, 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"). Vêm dentro da consulta do usuário, em fields, ou na rota própria (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.
• Entrou na carteira de um gerente de venda. Um gerente atende uma lista de clientes.
• Está num grupo liberado ao seller. Grupos de usuários marcados como gerenciáveis pelo seller deixam o seller colocar clientes neles.

Autenticação

HTTP Basic com e-mail:chave_de_api de um usuário administrador (a chave é gerada no painel), ou Authorization: Bearer <JWT>. Quem não é administrador recebe 403. As rotas também respondem sem o /v1.0 (/api/users), com os ids em formato decimal: veja Rotas sem versão.

Existe ainda um acesso por token de app, sem usuário, para ler e editar clientes: Clientes por token de app.

Ids, datas e dinheiro

• Em /api/v1.0, todo id é um UUID em string. Em /api/... (sem versão) os ids são decimais dentro de string.
• A data de cadastro vem como texto AAAA-MM-DD HH:MM:SS, e timestamp e last_login em Unix (segundos).
• Dinheiro é uma string decimal ("49.90").
• 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 (Basic ou Bearer). App é o token de app. Rotas /api/... sem versão têm a mesma lógica das /api/v1.0/... e ficam em Rotas sem versão.

Grupos de usuários estão em Grupos de usuários. Gerentes de venda (/managers) estão em Gerentes de venda.

Erros comuns

1. Mandar a senha em PUT /users/{id}. A atualização não troca senha: o campo password é ignorado em silêncio.
2. Criar uma PJ só com firstname. Para o cadastro nascer como PJ, mande o CNPJ; o nome informado vira a razão social.
3. Usar a palavra do status na saída. status=active funciona na entrada, mas a saída é sempre a letra (A, D, P).
4. Filtrar a lista por user_ids[]. O filtro é aplicado depois da paginação: numa página que não contém o id, o resultado vem vazio. Use GET /users/{id} para buscar um cliente conhecido.
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. Chamar POST /api/v1.0/customers sem saber que ele age em todas as contas com o mesmo CNPJ. Veja Sincronização por CNPJ.
7. Tratar o campo password como a senha. Ele volta sempre vazio. A plataforma nunca devolve senha nem hash.

Próximos passos