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

Rotas: escrita

Cria, substitui e exclui rotas de entrega de um gerente.

Três operações para manter as rotas de entrega: criar uma rota com seus clientes, substituir uma rota inteira e excluí-la. Todas pedem usuário administrador. Cada uma existe em três grafias (routes, ec_routes, ecroutes) e em duas bases (/api/v1.0 e /api); a entrada principal vem primeiro e os aliases logo depois.

Use /api/v1.0 e UUIDs

Na base /api sem versão, o manager_id do corpo é traduzido para UUID, mas o route_id de volta sai como número e o {id} do caminho não é traduzido. Resultado: você cria a rota e não consegue mais atualizá-la nem excluí-la com o id que recebeu (500 Update failed e 500 Delete failed). Em /api/v1.0 tudo trafega em UUID e funciona de ponta a ponta.

Criar uma rota

POST/api/v1.0/routesAdmin

Criar uma rota de entrega

Cria a rota e devolve o id. O status inicial é A (ativa). Os ids de customers são gravados como texto, sem conferir se existem.

Corpo da requisição

manager_iduuidobrigatório
Id do usuário gerente dono da rota. Se for um inteiro que corresponda a um representante da força de vendas, a rota é criada nesse módulo e o route_id volta como número. Qualquer outro valor que não seja UUID falha com 500.
routestringobrigatório
Nome da rota.
customersarray
Lista de ids de clientes, cada um como string. Número dentro da lista dá 400 Invalid JSON. Se você omitir o campo, a rota é gravada com customers: null; envie [] para uma rota vazia.
POST/api/v1.0/ec_routesAdmin

Alias de POST /api/v1.0/routes

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/routes.

POST/api/v1.0/ecroutesAdmin

Alias de POST /api/v1.0/routes

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/routes.

POST/api/routesAdmin

Alias de POST /api/v1.0/routes

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/routes. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

POST/api/ec_routesAdmin

Alias de POST /api/v1.0/routes

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/routes. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

POST/api/ecroutesAdmin

Alias de POST /api/v1.0/routes

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/routes. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Substituir uma rota

PUT/api/v1.0/routes/{id}Admin

Substituir uma rota de entrega

Reescreve nome, gerente, clientes e status. É uma substituição completa, não um patch: o que você não enviar é apagado (customers omitido grava null; status omitido volta para A). A chamada não confere se a rota existe: um UUID desconhecido responde 200 e não altera nada.

Parâmetros de caminho

iduuidobrigatório
Id da rota (id da consulta). Valor 0 dá 400; texto que não seja UUID dá 500 Update failed.

Corpo da requisição

manager_iduuidobrigatório
Gerente dono da rota.
routestringobrigatório
Nome da rota.
customersarray
Lista de ids de clientes (strings). Substitui a lista atual.
statusstringpadrão: A
AD
A ativa, D desativada.
PUT/api/v1.0/ec_routes/{id}Admin

Alias de PUT /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/routes/{id}.

PUT/api/v1.0/ecroutes/{id}Admin

Alias de PUT /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/routes/{id}.

PUT/api/routes/{id}Admin

Alias de PUT /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/routes/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

PUT/api/ec_routes/{id}Admin

Alias de PUT /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/routes/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

PUT/api/ecroutes/{id}Admin

Alias de PUT /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/routes/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Excluir uma rota

DELETE/api/v1.0/routes/{id}Admin

Excluir uma rota de entrega

Exclui a rota e, antes, todos os check-ins registrados nela. A exclusão é definitiva. A resposta é 200 nos dois casos; o campo success diz se havia o que excluir.

Parâmetros de caminho

iduuidobrigatório
Id da rota. Valor 0 dá 400; texto que não seja UUID dá 500 Delete failed.
DELETE/api/v1.0/ec_routes/{id}Admin

Alias de DELETE /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/routes/{id}.

DELETE/api/v1.0/ecroutes/{id}Admin

Alias de DELETE /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/routes/{id}.

DELETE/api/routes/{id}Admin

Alias de DELETE /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/routes/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

DELETE/api/ec_routes/{id}Admin

Alias de DELETE /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/routes/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

DELETE/api/ecroutes/{id}Admin

Alias de DELETE /api/v1.0/routes/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/routes/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash
# Criar
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/routes" \
  -H "Content-Type: application/json" \
  -d '{"manager_id":"12da2430-2092-40da-b361-c0ed2c1cd0d4","route":"Zona Sul","customers":["0d6b8d2e-3f0a-4f0c-9d3c-6b1f2a9a7c11"]}'

# Substituir
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/routes/b094b7c2-2e1f-4174-9551-b05fa2fe482e" \
  -H "Content-Type: application/json" \
  -d '{"manager_id":"12da2430-2092-40da-b361-c0ed2c1cd0d4","route":"Zona Sul 2","customers":[],"status":"D"}'

# Excluir
curl -u "$EMAIL:$API_KEY" -X DELETE "$BASE_URL/api/v1.0/routes/b094b7c2-2e1f-4174-9551-b05fa2fe482e"

Resposta

201Rota criada
json
{ "route_id": "b094b7c2-2e1f-4174-9551-b05fa2fe482e" }
200Rota substituída
json
{ "success": true, "route_id": "b094b7c2-2e1f-4174-9551-b05fa2fe482e" }
200Rota excluída (ou nada a excluir)
json
{ "success": true }

Campos da resposta

route_iduuid
Id da rota criada ou atualizada. Na criação com manager_id de representante (inteiro), vem como número.
successboolean
No PUT, sempre true. No DELETE, true se uma rota foi excluída e false se o id não existia (a resposta continua 200).

Erros

StatusQuandoCorpo
400JSON inválido, ou customers com algo que não é string{"message": "Invalid JSON", "status": 400}
400manager_id ou route ausente (no POST e no PUT){"message": "Required fields: manager_id, route", "status": 400}
400id igual a 0{"error": "invalid id parameter"}
401Sem credencial ou credencial inválida{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}
403Usuário que não é administrador{"message": "Forbidden: admin scope required", "status": 403}
500manager_id ou id que não é UUID{"message": "Insert failed", "status": 500}, Update failed ou Delete failed
Não existe 404 aqui

PUT e DELETE de uma rota inexistente não devolvem 404. O PUT responde 200 sem ter alterado nada; o DELETE responde 200 com success: false. Para saber se a rota existe, consulte antes (Rotas: consulta).

Veja também

  • Rotas: consulta
  • Visão geral de frete e rotas
Anterior
Rotas: consulta
Próxima
Cotação de frete
Nesta página
  • Criar uma rota
  • Substituir uma rota
  • Excluir uma rota
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também