Frete e rotas de entrega

Esta seção reúne quatro pequenas áreas de logística que a plataforma antiga (Venddor 1.0) expunha e que ainda são chamadas por ERPs, apps de campo e integradores: rotas de entrega (a lista de clientes que um gerente atende), cotação de frete por produto e CEP, sellers disponíveis (a lista de lojistas ativos) e a lista de formas de envio para aplicativos de terceiros.

São rotas de compatibilidade da Venddor 1.0, com as particularidades do contrato antigo.

Como funciona

Rotas de entrega

Uma rota de entrega é uma lista nomeada de clientes que um gerente (um usuário da loja, em geral um representante comercial ou entregador) deve visitar. Quem integra cria a rota com o nome e os ids dos clientes, o app de campo lê as rotas do gerente e registra check-ins no caminho. Os check-ins têm rotas próprias e não fazem parte desta seção.

Cotação de frete e sellers

delivery_methods devolve as opções de frete e o preço para um produto em um CEP, no formato da 1.0. sellers_availability lista os lojistas ativos, com filtro por estado e cidade. GET /api/admin/shipping-methods é a lista de formas de envio da loja para aplicativos de terceiros que usam token de app.

Conceitos-chave

Duas URLs, dois formatos de id

A plataforma monta o mesmo conjunto de rotas em /api/v1.0/... e em /api/.... Na URL com v1.0 os ids são UUIDs, como no resto da plataforma. Na URL sem versão a plataforma troca cada UUID por um inteiro de 31 bits derivado dele (por exemplo 496868694), porque integradores antigos esperam ids numéricos. Duas armadilhas dessa troca:

• O id numérico só é traduzido de volta quando a rota está na lista de recursos conhecidos. Rotas de entrega não estão nessa lista: o route_id numérico devolvido pelo POST /api/routes não funciona no PUT nem no DELETE da mesma família.
• Ids diferentes podem coincidir no formato numérico. Nas formas de envio padrão do sistema, duas delas (...0001 e ...0003) viram o mesmo número 1342177280.

Detalhes do formato em Convenções.

Maiúsculas e barra final

As URLs ignoram maiúsculas e a barra final: /api/EcRoutes/ chega ao mesmo lugar que /api/ecroutes. É por isso que existe a grafia ecroutes: o app de campo da 1.0 chama api/EcRoutes.

Formato de erro

Os erros desta família vêm como {"message": "...", "status": 400}. Falta de credencial é 401, usuário sem permissão é 403 (Forbidden: admin scope required). Mensagens são devolvidas em inglês, como no servidor.

Endpoints

Erros comuns

• Usar /api/routes sem versão e perder o fio. O route_id numérico devolvido não serve para atualizar nem excluir, e a consulta pelo id numérico do gerente não encontra as rotas criadas pelo UUID. Use /api/v1.0.
• Mandar manager_id que não é UUID. A rota é gravada com o gerente como UUID. Outro formato falha com 500 Insert failed (veja a página de escrita).
• Esquecer customers no PUT. O PUT substitui a rota inteira, inclusive a lista de clientes. Omitir o campo grava null.
• Chamar delivery_methods com product_id que não é UUID. Devolve 500 com a mensagem do banco, não 400.
• Esperar que o CEP seja validado. delivery_methods aceita qualquer texto em zipcode.
• Chamar /api/admin/shipping-methods com JWT. Essa rota aceita só token de app (vat_...).

Próximos passos