Documentação da API

Introdução

Todas as chamadas usam a URL base abaixo, HTTPS e o cabeçalho Accept: application/json.

https://roteirizando.pro/api/v1

A roteirização usa o VROOM sobre a malha viária do Brasil (OSRM com dados do OpenStreetMap): respeita capacidade de peso e cubagem, janelas de entrega, jornada do veículo e limite de paradas do plano. Cada rota traz sequência, previsão de chegada (ETA), traçado, custo de combustível, pedágio estimado pelas praças que o traçado cruza e lucratividade.

Autenticação

O administrador da conta gera os tokens no painel, em Integrações → API para ERP / TMS. O token aparece uma única vez: guarde-o como senha. Envie em todas as chamadas:

Authorization: Bearer 12|t8Hq...seu-token

Cada token recebe só as permissões necessárias:

Teste o token com GET /me, que devolve a empresa e as permissões.

Limites

• 120 requisições por minuto por token; POST /routes/optimize: 20 por minuto.
• Até 500 cargas e 100 veículos por otimização; o servidor aceita até 200 pontos (entregas, coletas, saídas e retornos) por chamada.
• As rotas criadas pela API contam no limite mensal do plano, como as criadas no painel.
• Acima do limite a resposta é 429 Too Many Requests, com o cabeçalho Retry-After.

Erros

Os erros vêm com HTTP adequado e uma mensagem em português, completa e pronta para mostrar ao usuário:

{
  "message": "Cargas não encontradas nesta conta: NAOEXISTE.",
  "missing": ["NAOEXISTE"]
}

Cargas

Cadastrar pelo XML da NF-e ou CT-e

Envie o XML autorizado (nfeProc/cteProc) no corpo. Destinatário, endereço, peso, volumes, valores e janela vêm do próprio documento.

curl -X POST https://roteirizando.pro/api/v1/deliveries \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/xml" \
  --data-binary @nota.xml

Também aceita JSON com o XML dentro: {"xml": "<nfeProc ...>"}.

Cadastrar com os campos em JSON

{
  "kind": "delivery",
  "recipient_name": "Mercado Bom Preço",
  "recipient_phone": "86999990000",
  "street": "Av. Frei Serafim", "number": "2280",
  "district": "Centro", "city": "Teresina", "state": "PI", "postal_code": "64001020",
  "weight_kg": 120.5, "volume_m3": 0.8, "packages": 4,
  "freight_value": 180.00, "document_number": "12345",
  "time_window_start": "2026-10-01T08:00:00-03:00",
  "time_window_end": "2026-10-01T12:00:00-03:00",
  "external_id": "PEDIDO-9981"
}

Obrigatórios: recipient_name, street, city e state (UF). A cidade precisa existir na lista de municípios do IBGE para a UF (acentos e maiúsculas não importam; a gravação usa o nome oficial). Opcionais: kind (delivery = entrega, padrão; collection = coleta no endereço; também aceita ENTREGA/COLETA), recipient_phone (para o aviso no WhatsApp), recipient_document, number, complement, district, postal_code (8 dígitos), latitude/longitude (pula a geocodificação), weight_kg, volume_m3, packages, goods_value, freight_value, document_number, external_id, time_window_start/time_window_end, service_time_seconds, priority (0 a 100) e notes.

Resposta 201:

{
  "data": {
    "tracking_code": "K43JVVPASU",
    "tracking_url": "https://roteirizando.pro/rastreio/K43JVVPASU",
    "status": "pending",
    "geocoding_status": "pending",
    "recipient_name": "Mercado Bom Preço",
    "city": "Teresina", "state": "PI",
    "weight_kg": 120.5, "volume_m3": 0.8
  }
}

O endereço é geocodificado em segundo plano (geocoding_status passa a success, approx quando localizado pela cidade/CEP, ou failed). Só cargas com coordenadas entram na roteirização.

Listar e consultar

Status possíveis: pending, routed, in_transit, delivered, failed, cancelled.

Veículos

Devolve placa, tipo, status, capacidade (kg e m³), eixos para pedágio e jornada (null = sem limite de horário).

Otimizar rotas

{
  "deliveries": ["K43JVVPASU", "LEZICCFJSI", "N6QK2OIFOL"],
  "vehicles": ["ABC1D23", "OSO5549"],
  "departure_at": "2026-10-01T07:00:00-03:00",
  "allow_partial": true,
  "return_to_depot": true,
  "fuel_price_per_liter": 6.29,
  "profile": "truck"
}

• deliveries (obrigatório): códigos de rastreio das cargas pendentes.
• vehicles: placas; se omitido, usa todos os veículos disponíveis.
• departure_at: saída; padrão daqui a 30 minutos.
• allow_partial: com true, o que não couber volta em unassigned em vez de dar erro.
• return_to_depot: com true (padrão) os veículos voltam para a base no fim da rota; com false a rota termina na última parada. Vale para todos os veículos da otimização.
• profile: perfil de deslocamento, car, moto ou truck. Muda a malha de ruas e os tempos de viagem (caminhão até 90 km/h e respeitando restrições de peso, altura e caminhão; moto respeitando vias proibidas para moto). Se omitido, cada veículo usa o perfil do seu tipo (moto → moto; VUC, toco, truck e carreta → truck; demais → car).

Resposta 201 (uma rota por veículo usado):

{
  "batch": "9b1f2c7e-...",
  "data": [{
    "code": "R261001-8KQ2M",
    "profile": "truck",
    "status": "planned",
    "vehicle": { "plate": "ABC1D23", "type": "toco" },
    "stops_count": 3,
    "distance_km": 48.6,
    "driving_minutes": 94,
    "costs": { "freight_revenue": 540.0, "fuel": 38.21, "toll": 15.0, "other": 0, "profit": 486.79 },
    "toll_plazas": [{ "name": "Praça Teresina", "highway": "BR-316", "uf": "PI", "charges": 1, "value": 15.0 }],
    "geometry": { "format": "polyline5", "value": "_p~iF~ps|U..." },
    "stops": [
      { "sequence": 1, "type": "job", "tracking_code": "K43JVVPASU", "eta": "2026-10-01T07:42:00-03:00", "status": "pending" }
    ],
    "tracking_url": "https://roteirizando.pro/acompanhar/..."
  }],
  "unassigned": [],
  "out_of_coverage": []
}

out_of_coverage lista cargas com coordenadas fora da malha viária (ex.: endereço geocodificado errado); elas ficam pendentes e o restante é roteirizado. O traçado vem em polyline com precisão 5 (formato do Google/OSRM), pronto para Leaflet, Mapbox ou Google Maps.

Rotas

A listagem é paginada (meta.current_page, meta.last_page, meta.total). O detalhe traz as paradas com ETA e status, traçado, custos e praças de pedágio. O DELETE vale só para rotas que ainda não saíram: as cargas voltam a pending e podem ser roteirizadas de novo. Status de rota: planned, dispatched, in_progress, completed, cancelled.

Com a rota in_progress, o campo live_position traz a posição real do veículo enviada pelo app do motorista (a cada ~30 s): latitude, longitude, heading (graus a partir do norte), speed_kmh, recorded_at e stale (true quando o último sinal tem mais de 5 minutos). Nas demais situações o campo vem null.

"live_position": {
  "latitude": -5.0892, "longitude": -42.8016,
  "heading": 90, "speed_kmh": 42,
  "recorded_at": "2026-10-01T09:42:10-03:00", "stale": false
}

Rastreio público

Cada carga tem tracking_url (página do cliente final, com fila e previsão) e cada rota tem tracking_url (acompanhamento ao vivo da rota inteira). As páginas mostram só bairro/cidade e horários, nunca telefone ou documento; podem ser enviadas ao cliente ou embutidas no seu sistema.

Boas práticas

• Use tokens diferentes por sistema (ERP, TMS, BI) e só com as permissões necessárias; revogue pelo painel quando não usar mais.
• Guarde o tracking_code junto do pedido no seu sistema: é a chave de todas as consultas.
• Envie recipient_phone para que o cliente receba o aviso de saída e de chegada pelo WhatsApp.
• Informe latitude/longitude quando já tiver: evita geocodificação aproximada em endereços rurais.
• Trate 429 esperando o tempo de Retry-After; não repita otimizações em sequência.