Representantes comerciais

Representante comercial (ou promotor de vendas) é a pessoa que atende uma lista de clientes por conta da loja: visita, negocia, lança pedidos em nome do cliente e recebe comissão. Esta seção cobre o cadastro e a carteira (a lista de clientes que cada representante atende), os sellers que ele atende, as comissões e o desempenho. A parte de campo (rotas de visita, check-ins, conta-corrente, alçada de desconto) está em Campo e alçadas.

Como funciona

1. Cadastre

   Crie o representante com nome e e-mail. A plataforma cria o login dele e, no modo do seller, o vincula à equipe do seller.

2. Monte a carteira

   Atribua clientes um a um, importe uma planilha de CNPJ/CPF, ou transfira a carteira de outro representante.

3. Acompanhe

   Veja pedidos, resumo e painel e comissões.

Conceitos-chave

Modos: marketplace e seller

No modo marketplace, o vínculo representante-seller fica na tabela de sellers atendidos e a comissão sai por pedido. No modo do seller, a carteira é do próprio seller e o owner_vendor_id limita tudo. A lista aceita mode=seller ou mode=marketplace para separar.

Carteira e tipos de vínculo

Cada vínculo cliente-representante tem um link_kind: permanent (definitivo), temporary (cobertura com data final valid_until, que depois volta ao representante original) ou copy (o cliente fica com os dois). Um cliente pode estar na carteira de mais de um representante.

Nível hierárquico e alçada

hierarchy_level vai de 0 (campo) a 4 (aprovadores). discount_limit_bp é o desconto máximo que o representante dá sozinho. O restante da cadeia está em Campo e alçadas.

Estados e letras

A comissão tem status que, na leitura, sai como letra: P pendente, A aprovada, C paga. Na escrita você manda a palavra (pending, approved, paid).

Endpoints

Erros comuns

• Mandar o id como UUID. O {id} do representante é inteiro; texto devolve 400 invalid trade rep ID.
• Criar sem senha. Se o e-mail não tem usuário seller ainda, a criação exige password (400 password_required).
• E-mail de outro tipo de conta. Se o e-mail já pertence a um cliente ou administrador, a criação devolve 409 email_in_use.
• Transferir sem listar clientes. Se customer_ids vier vazio (ou all_filtered: true), a operação alcança toda a carteira do representante de origem.
• Esperar 404 ao excluir um id que não existe. DELETE devolve sempre 200 {"status":"deleted"}.
• Contar com o 409 de cliente já atribuído. Atribuir de novo apenas atualiza o vínculo; não há erro.
• Esquecer o vendor_id no modo seller. Transferir, copiar e substituir carteira trabalham por vendor_id; vazio significa os vínculos globais, não os do seller.

Próximos passos