VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Campo e alçadas dos representantes

Como funcionam rotas de visita, check-ins por GPS, conta-corrente, alçada de desconto e aprovações, e o mapa das rotas.

Além do cadastro e da carteira (veja Representantes comerciais), o representante trabalha na rua: segue rotas de visita, faz check-in em cada cliente e dá descontos dentro de um limite. Esta seção cobre o que a loja configura e acompanha desse trabalho: as rotas, os check-ins, a conta-corrente do representante, a régua de desconto e a fila de aprovação de descontos acima do limite.

Pontos-chave
  • Todas as rotas exigem o módulo trade-reps. A fila de aprovações aceita também o privilégio approve_rep_discounts (quem só aprova); o restante exige manage_trade_reps ou manage_vendors.
  • Dinheiro é inteiro em centavos. Descontos e comissões são pontos-base (bp): 500 = 5%.
  • O desconto passa por camadas: o desconto livre (qualquer representante pode dar), a alçada própria do representante (discount_limit_bp) e, acima disso, aprovação por um nível hierárquico.
  • A conta-corrente guarda um saldo de crédito em centavos por representante. Descontos acima do livre viram débitos. As comissões aparecem no extrato como créditos, mas não alteram o saldo.
  • Os valores de configuração financeira (finance-settings e régua de desconto) são por seller (vendor_id).

Como funciona

Rota de visita→Check-in no cliente→Pedido com desconto→Alçada ou aprovação→Conta-corrente

A cadeia de um desconto

Para cada item, a plataforma compara o desconto pedido com três limites, nesta ordem:

CamadaLimiteO que acontece
Desconto livreDo produto, senão da categoria, senão global_free_discount_bp do sellerSem custo para o representante.
Alçada própriadiscount_limit_bp do representante, sobre o que passa do livreO excedente vira débito na conta-corrente.
AprovaçãoQuando o excesso sobre o livre passa da alçada: approval_limit_1_bp (e _2_, _3_ com níveis estendidos) do seller definem o nível exigidoAbre uma solicitação na fila de aprovações, e o pedido fica retido até a decisão.

O cálculo prévio mostra em qual camada um preço cai, sem criar nada.

Conceitos-chave

Rotas e check-ins

Uma rota é uma lista nomeada de clientes a visitar, de um representante. Um check-in registra uma visita (coordenadas, observação, foto) ligada a uma rota. A rota é só o plano; o check-in é a prova.

Conta-corrente (ledger)

Cada lançamento tem entry_type (commission, discount, bonus, manual_credit, manual_debit, reverse_commission), um valor com sinal e o saldo depois do lançamento. Crédito é positivo, débito é negativo.

Régua de desconto por cluster

A régua define o desconto máximo por cluster do cliente (P pequeno, M médio, G grande) e por nível hierárquico (0 a 3). É uma matriz por seller.

Endpoints

MétodoCaminhoPara que serveAuth
GET/api/v1/admin/trade-reps/routesListar todas as rotasadmin
POST/api/v1/admin/trade-reps/routesCriar rotaadmin
PUT/api/v1/admin/trade-reps/routes/{routeId}Editar rotaadmin
DELETE/api/v1/admin/trade-reps/routes/{routeId}Excluir rotaadmin
GET/api/v1/admin/trade-reps/{id}/routesRotas de um representanteadmin
POST/api/v1/admin/trade-reps/checkinsRegistrar check-inadmin
GET/api/v1/admin/trade-reps/{id}/checkinsListar check-insadmin
GET/api/v1/admin/trade-reps/{id}/ledgerExtrato da conta-correnteadmin
POST/api/v1/admin/trade-reps/{id}/ledgerCrédito ou débito manualadmin
GET/api/v1/admin/trade-reps/finance-settingsLer parâmetros financeirosadmin
PUT/api/v1/admin/trade-reps/finance-settingsGravar parâmetros financeirosadmin
POST/api/v1/admin/trade-reps/discount-previewSimular um descontoadmin
GET/api/v1/admin/trade-reps/discount-rulerLer a réguaadmin
PUT/api/v1/admin/trade-reps/discount-rulerGravar a réguaadmin
GET/api/v1/admin/trade-reps/approvalsFila de aprovaçõesadmin
POST/api/v1/admin/trade-reps/approvals/{id}/decideDecidir uma aprovaçãoadmin

Erros comuns

  • Mandar o campo errado no check-in. A mensagem de erro fala em manager_id, mas o campo do corpo é rep_id.
  • Check-in com 0,0. Latitude e longitude ambas 0 são recusadas (latitude and longitude are required).
  • Editar uma rota que não existe. PUT /routes/{routeId} responde 200 com corpo null, não 404.
  • Esquecer o sinal no lançamento manual. O valor é sempre positivo; é o scope que decide crédito (A) ou débito (qualquer outro valor, inclusive omitido).
  • Gravar finance-settings parcial. O PUT grava todos os campos: o que você não mandar vira 0, vazio ou false.
  • Decidir uma aprovação já decidida. Devolve 409 approval_not_pending.
  • Ler a régua vazia como gravada. Sem régua salva, o GET devolve uma matriz sugerida com seeded: true, que só vale depois de você gravá-la.

Próximos passos

Rotas de visita
Planejar as visitas de cada representante.
Alçadas e régua
Configurar descontos por seller.
Aprovações
Decidir descontos acima do limite.
Anterior
Comissões de representantes
Próxima
Rotas de visita
Nesta página
  • Como funciona
  • A cadeia de um desconto
  • Conceitos-chave
  • Rotas e check-ins
  • Conta-corrente (ledger)
  • Régua de desconto por cluster
  • Endpoints
  • Erros comuns
  • Próximos passos