Clientes do seller

Numa loja com vários sellers (lojistas), o cliente pertence à loja, mas cada seller precisa saber quem compra dele. Esta seção entrega isso: a lista dos clientes que já pediram ao seller (com total gasto e último pedido), a carteira própria (clientes que o seller cadastra à mão ou importa por CPF/CNPJ, mesmo que ainda não tenham comprado), a frequência de compra esperada para destacar quem está atrasado e os grupos de clientes que o seller pode gerir. Tudo vive em /api/v1/vendor/customers e /api/v1/vendor/usergroups.

Como funciona

Quem aparece na lista

A lista junta duas origens: quem tem pedido com o seller e quem foi posto na carteira (sem precisar de pedido). Um cliente que só está na carteira aparece com order_count zero e days_since_last_order ausente.

Frequência esperada e atraso

O seller define quantos dias costuma esperar entre uma compra e a seguinte (PUT /customers/expected-frequency). Com isso, cada cliente ganha days_overdue: quantos dias passaram além do esperado (0 é "em dia" ou "frequência não configurada"). Quem nunca comprou não entra em "atrasado": ele tem seu próprio filtro, never_ordered.

Carteira própria e importação

Ficar na carteira é um vínculo seller-cliente que existe sozinho: tirar o cliente da carteira não apaga o usuário nem os pedidos, e o cliente continua na carteira de outros sellers.

Conceitos importantes

Identidade PF e PJ

person_type é F (pessoa física, com cpf) ou J (pessoa jurídica, com cnpj, legal_name razão social e trade_name nome fantasia). display_name já escolhe o melhor nome para mostrar: fantasia, depois razão social, depois nome.

Dados pessoais

cpf e cnpj aparecem sem máscara. Trate-os como dado pessoal (LGPD) e não os registre em log.

Endpoints

Erros comuns

• Procurar customers: [] numa lista vazia. Vem null.
• Enviar um id que não é UUID em GET /customers?id=. Volta 500, não 400.
• Importar CPF digitado com erro. O dígito verificador é conferido: a linha volta invalid_document e as outras seguem.
• Esperar que a carteira crie o cliente. Ela só liga; documento sem cadastro volta customer_not_found.
• Pôr no grupo um cliente que nunca comprou do seller. O servidor recusa (has no orders with vendor).
• Usar filter=overdue sem ter configurado a frequência. Com frequência 0 ninguém está atrasado e a lista vem vazia.

Próximos passos