Equipe de campo

Uma loja que vende para empresas costuma ter representantes comerciais: pessoas que visitam clientes numa rota planejada e lançam pedidos pelo celular. A plataforma antiga (Venddor 1.0) chamava o representante de manager e tinha duas funções para ele que esta seção cobre: o check-in, que registra com GPS que o representante esteve num cliente, e a conta-corrente, o saldo de crédito que o representante pode gastar em descontos.

As rotas continuam no ar para o app antigo. Elas ficam em /api/v1.0 e também sem versão (/api), cada operação com até três nomes.

Como funciona

1. A rota

   A rota é uma lista de clientes que o representante visita (por exemplo, "Zona Sul, segunda-feira"). As rotas são criadas pelas rotas routes e ec_routes da API 1.0, que não fazem parte desta seção. Você precisa do route_id para registrar um check-in.

2. O check-in

   No cliente, o app envia a latitude e a longitude do celular. Check-ins grava a visita e listar check-ins devolve o histórico.

3. A conta-corrente

   O saldo de crédito do representante sobe com lançamentos manuais (scope=A) e desce com descontos concedidos em pedidos e com lançamentos manuais de redução. Conta-corrente do representante lê o extrato e faz os lançamentos.

Conceitos-chave

Representante (manager)

É um cadastro próprio, ligado a um usuário da loja. Cada representante tem um id inteiro (manager_id), um código interno opcional (internal_code, por exemplo REP-001) e um limite de desconto. A lista completa de representantes está na API 1.0 (/managers), fora desta seção.

Check-in

Um registro de visita: rota, representante, latitude, longitude e observação. O check-in guarda também o cliente visitado, mas estas rotas não enviam o cliente na gravação; o campo customer_id só vem preenchido nos check-ins gravados por outro caminho da plataforma. As coordenadas 0,0 são recusadas, porque um GPS sem sinal devolve esse valor.

Conta-corrente (crédito)

Cada lançamento tem um tipo e um valor. Os tipos que mexem no saldo são o crédito manual, o débito manual e o desconto concedido em pedido. A comissão é só registrada. O saldo nunca fica negativo: uma redução maior que o saldo é recusada com insufficient credit balance.

Ids, tempo e dinheiro

Ids de rota, representante e check-in são inteiros enviados como string ("2"). Valores de dinheiro saem em string decimal ("12.50"); no corpo de um lançamento o amount é número. Datas saem em Unix timestamp (segundos).

Endpoints

Erros comuns

• Mandar route_id e manager_id como número no JSON. O check-in lê os dois como texto: {"route_id": 2} responde 400 Invalid JSON. Mande "2".
• Usar a forma /api no check-in. Em lojas migradas da plataforma antiga, o route_id pode ser trocado pelo id de outro registro e a resposta é Route not found ou um filtro que devolve todas as rotas. Use /api/v1.0.
• Mandar latitude e longitude zeradas. 0,0 é recusado com latitude and longitude are required.
• Achar que manager_id desconhecido sempre dá erro. Na leitura do extrato, um manager_id que não é número volta como lista vazia, e um número que não existe volta 500 trade rep not found. No lançamento, um manager_id não numérico volta 200 com result: null.
• Mandar amount em string ("10") no lançamento: 400 Invalid JSON body.
• Confiar em scope. Só A soma. Qualquer outro texto reduz o saldo, inclusive um erro de digitação.
• Mandar valores com mais de duas casas (4.355): o valor é convertido para centavos e truncado.

Próximos passos