Equipe de campo do seller

Representante comercial (também chamado de promotor de vendas ou vendedor externo) é a pessoa que atende uma lista de clientes em nome do seller: visita, negocia, lança pedidos pelo aplicativo de campo e recebe comissão. Esta seção é o lado do seller dessa equipe: ele cadastra seus representantes, define quem atende quais clientes e ajusta quanto desconto cada um pode dar. O lado do administrador da loja, que enxerga todas as equipes, está em Representantes comerciais.

Como funciona

1. Cadastre
   Crie o representante com nome, e-mail e, se o e-mail ainda não tem login, uma senha. Ele já nasce preso ao seu seller.
2. Monte a carteira
   Consulte a carteira de cada representante e transfira clientes de um para outro quando a equipe mudar. A carteira em si é montada pelo administrador da loja.
3. Defina as alçadas
   Ajuste o discount_limit_bp de cada representante e os parâmetros financeiros do seller: desconto livre e níveis de aprovação.
4. Acompanhe
   Veja o extrato da conta-corrente do representante.

Conceitos importantes

Alçada de desconto

Alçada é o limite de desconto que alguém pode conceder sozinho. O representante tem a própria (discount_limit_bp); acima dela o pedido pede aprovação de um nível superior (hierarchy_level, de 1 a 4). Os parâmetros do seller (finance-settings) dizem quanto de excesso cada nível aprova. O pedido fica retido até alguém aprovar.

Conta-corrente

Cada representante tem um saldo em centavos (credit_balance) que ele pode gastar em descontos acima do livre. O extrato lista cada lançamento, com sinal.

Dois modos de operação

No modo do seller (o que esta seção cobre), o representante pertence a um seller (owner_vendor_id). No modo marketplace, o representante atende vários sellers e só o administrador o gerencia; ele não aparece nestas rotas.

Endpoints

Erros comuns

• Passar um UUID no lugar do id do representante. O id é inteiro; um valor que não é número é lido como 0 e a resposta é 404 not found.
• Reaproveitar um e-mail e mandar password. Se já existe usuário seller com esse e-mail, a senha dele é substituída.
• Mandar PUT /finance-settings só com o campo que mudou. A gravação é completa: os campos omitidos voltam a 0, vazio ou false.
• Esperar que owner_vendor_id do corpo valha. O servidor ignora e grava o seu seller.
• Transferir sem customer_ids. Move toda a carteira do representante de origem.
• Achar que vendor_view_orders só lê. Aqui ele também libera cadastrar, alterar e transferir.

Próximos passos