API de Otimização de Rotas (REST + SOAP) – Guia para Programadores

O que pode criar com a API de otimização de rotas da TrackRoad#

A API permite a otimização de rotas para casos empresariais comuns:

• Sistemas de planeamento de rotas de entrega (estafetas, encomendas, mercearias)
• Agendamento de serviços no terreno (técnicos, reparações, instalações)
• Expedição de frotas com vários veículos e várias paragens
• Fluxos de trabalho de geocodificação e encaminhamento passo a passo
• Modos avançados de expedição para diferentes estratégias de encaminhamento

O motor de encaminhamento suporta restrições como:

• Janelas horárias (restrições de chegada e partida)
• Limites de capacidade (peso / volume)
• Equilíbrio de tempo e distância entre veículos
• Múltiplos pontos de início e fim de veículos
• Paragens para pausa e tempo de serviço por paragem

REST vs SOAP#

API REST (JSON/XML)

REST é leve e comum em integrações web e móveis. A TrackRoad suporta chamadas REST com payloads JSON ou XML.

API SOAP

SOAP é comum em sistemas empresariais e suporta referências de serviço fortemente tipadas em .NET. SOAP é útil se quiser classes compiladas como DispatchSpecification, Vehicle e Location.

Autenticação (TrackServiceKey)#

A TrackRoad utiliza uma chave de API estável chamada TrackServiceKey. Não funciona como um ID de sessão clássico com expiração. Consulte autenticação da API para todos os detalhes.

• REST: Envie a sua chave no cabeçalho HTTP: X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP: Envie a sua chave em SessionIDHeader como SessionID

API Dispatch (chamada principal de otimização)#

A otimização de rotas é realizada através de Dispatch. O Dispatch recebe veículos e paragens e devolve rotas otimizadas por veículo.

Referência completa: API Dispatch

Endpoint WSDL SOAP

http://trackservice.trackroad.com/trackservice.asmx?wsdl

Entradas típicas do Dispatch

• Veículos (cada um com local de início e fim)
• Paragens (localizações)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima, etc.)
• MinimumOptimization (precisão)

Janelas horárias e modo Optima#

A TrackRoad suporta janelas horárias através de restrições de chegada e partida nas paragens. Para obter os melhores resultados, a TrackRoad recomenda a utilização de DispatchMode Optima para janelas horárias.

Variáveis principais

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Se a sua linguagem não conseguir passar valores datetime nulos, utilize 0001-01-01T00:00:00. A TrackRoad trata datas inferiores ou iguais a 1 de janeiro de 2012 como nulas.

Ler mais: Otimização de Rotas com Janelas Horárias

Compreender os resultados da expedição#

O Dispatch devolve rotas otimizadas por veículo. O resultado de cada veículo inclui paragens ordenadas com metadados como:

• Sequência de paragens
• MatchCode e confiança na correspondência de endereços
• Latitude e Longitude
• Tempo e distância até à próxima paragem

Dicas de desempenho e escalabilidade

• Agrupe as paragens sempre que possível em vez de otimizar uma rota de cada vez
• Forneça tempos de serviço e janelas horárias precisos para resultados realistas
• Utilize o modo Optima para horários com restrições
• Aumente a otimização mínima para melhor qualidade em conjuntos maiores de paragens
• Utilize expedição multi-veículo para o encaminhamento da frota em vez de pedidos separados

Exemplo REST JSON (X-API-Key → Dispatch)#

Este exemplo mostra o fluxo REST recomendado utilizando X-API-Key (TrackServiceKey).

Passo 1 — Definir cabeçalhos de autenticação

Headers:
X-API-Key: YOUR_TRACKSERVICEKEY
Content-Type: application/json

Passo 2 — Dispatch (otimizar rotas)

O Dispatch recebe veículos e paragens e devolve rotas otimizadas. Este exemplo utiliza um veículo e múltiplas paragens.

POST https://trackservice.trackroad.com/rest/dispatch
Headers:
X-API-Key: YOUR_TRACKSERVICEKEY
Content-Type: application/json

{
  "DispatchMode": "Optima",
  "DistanceUnit": "Mile",
  "MinimumOptimization": 1,
  "Vehicles": [
    {
      "Name": "Vehicle 1",
      "StartLocation": { "Name": "Depot", "Address": "350 5th Ave, New York, NY" },
      "FinishLocation": { "Name": "Depot", "Address": "350 5th Ave, New York, NY" },
      "TimeIn": "2025-12-25T08:00:00",
      "TimeOut": "2025-12-25T18:00:00",
      "CapacityWeight": 1000,
      "CapacityVolume": 100
    }
  ],
  "Stops": [
    {
      "Name": "Stop 1",
      "Address": "405 Lexington Ave, New York, NY",
      "ServiceTimeMinutes": 10,
      "TimeWindowStart": "2025-12-25T09:00:00",
      "TimeWindowEnd": "2025-12-25T11:00:00",
      "Weight": 120,
      "Volume": 12
    },
    {
      "Name": "Stop 2",
      "Address": "11 Wall St, New York, NY",
      "ServiceTimeMinutes": 8,
      "TimeWindowStart": "2025-12-25T10:00:00",
      "TimeWindowEnd": "2025-12-25T14:00:00",
      "Weight": 60,
      "Volume": 6
    },
    {
      "Name": "Stop 3",
      "Address": "200 Central Park West, New York, NY",
      "ServiceTimeMinutes": 12,
      "Weight": 80,
      "Volume": 8
    }
  ]
}

Dica: Para janelas horárias, utilize DispatchMode = Optima. Se a sua integração não conseguir enviar valores nulos, utilize uma data predefinida como 0001-01-01T00:00:00 para representar “null”.

Exemplo curl

curl -X POST "https://trackservice.trackroad.com/rest/dispatch" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -H "Content-Type: application/json" \
  -d @dispatch-request.json

Os métodos Login e Logout legados estão disponíveis para compatibilidade retroativa. Para a maioria das integrações, utilize X-API-Key (TrackServiceKey) em todos os pedidos.

Exemplo SOAP em C# (SessionIDHeader → Dispatch)

A autenticação SOAP da TrackRoad utiliza SessionIDHeader.SessionID = TrackServiceKey. Consulte autenticação para todos os detalhes.

Endpoint WSDL SOAP

http://trackservice.trackroad.com/trackservice.asmx?wsdl

Exemplo SOAP em C# passo a passo

using System;
using System.Collections.Generic;
using TrackServiceRef; // your generated SOAP reference namespace

public class TrackRoadSoapExample
{
    public static void OptimizeRoutesWithSoap()
    {
        var client = new TrackServiceSoapClient();

        // TrackRoad SOAP uses TrackServiceKey as SessionID.
        string sessionId = "YOUR_TRACKSERVICEKEY";

        // Vehicles
        var vehicle = new Vehicle
        {
            Name = "Vehicle 1",
            StartLocation = new Location { Name = "Depot", Address = "350 5th Ave, New York, NY" },
            FinishLocation = new Location { Name = "Depot", Address = "350 5th Ave, New York, NY" },
            TimeIn = new DateTime(2025, 12, 25, 8, 0, 0),
            TimeOut = new DateTime(2025, 12, 25, 18, 0, 0),
            CapacityWeight = 1000,
            CapacityVolume = 100
        };

        // Stops
        var stops = new List<Location>
        {
            new Location
            {
                Name = "Stop 1",
                Address = "405 Lexington Ave, New York, NY",
                ServiceTime = 10,
                TimeConstraintArrival = new DateTime(2025, 12, 25, 9, 0, 0),
                TimeConstraintDeparture = new DateTime(2025, 12, 25, 11, 0, 0),
                CanArriveEarly = true,
                Weight = 120,
                Volume = 12
            },
            new Location
            {
                Name = "Stop 2",
                Address = "11 Wall St, New York, NY",
                ServiceTime = 8,
                TimeConstraintArrival = new DateTime(2025, 12, 25, 10, 0, 0),
                TimeConstraintDeparture = new DateTime(2025, 12, 25, 14, 0, 0),
                CanArriveEarly = true,
                Weight = 60,
                Volume = 6
            },
            new Location
            {
                Name = "Stop 3",
                Address = "200 Central Park West, New York, NY",
                ServiceTime = 12,
                Weight = 80,
                Volume = 8
            }
        };

        // Dispatch spec
        var spec = new DispatchSpecification
        {
            DispatchMode = DispatchMode.Optima,
            DistanceUnit = DistanceUnit.Mile,
            MinimumOptimization = 1,
            CurrentTime = DateTime.MinValue
        };

        // Dispatch
        var dispatchResult = client.Dispatch(sessionId, spec, new[] { vehicle }, stops.ToArray());

        if (!dispatchResult.Success)
            throw new Exception("Dispatch failed: " + dispatchResult.Message);

        foreach (var route in dispatchResult.Routes)
        {
            Console.WriteLine($"Vehicle: {route.VehicleName}");
            Console.WriteLine($"Distance: {route.Distance}");
            Console.WriteLine($"Duration: {route.Duration}");

            foreach (var stop in route.Stops)
                Console.WriteLine($"  {stop.Sequence}. {stop.Name}  ETA: {stop.ETA}");
        }
    }
}

Notas

• Utilize o modo Optima para janelas horárias e horários.
• Forneça o horário de trabalho do motorista (TimeIn, TimeOut) para um encaminhamento realista.
• Se não conseguir fornecer valores datetime nulos, utilize DateTime.MinValue ou uma regra de data nula.

Resolução de problemas: erros comuns da API e como corrigi-los#

A otimização de rotas é um problema baseado em restrições. Se fornecer endereços inválidos ou restrições impossíveis, como janelas horárias apertadas, veículos insuficientes ou limites de capacidade excedidos, o motor de expedição pode devolver erros ou produzir rotas incompletas.

1) “Dispatch failed” ou Success = false

• Endereços de paragem inválidos ou incompletos
• Janelas horárias impossíveis
• Horário de trabalho do veículo demasiado curto
• Veículos insuficientes para servir todas as paragens
• Restrições de capacidade excedidas

2) Algumas paragens não aparecem nas rotas

Causas comuns:

• Janelas horárias demasiado restritas
• Horários de trabalho demasiado restritos
• Capacidade excedida
• O tempo de serviço empurra o horário para além dos limites viáveis

3) Correspondências de endereços inválidas ou de baixa qualidade (problemas de MatchCode)

• Forneça endereços completos (rua, cidade, código postal, país)
• Se já tiver coordenadas, envie Latitude e Longitude
• Valide as paragens com geocodificação antes da expedição, quando necessário

4) As janelas horárias são inviáveis

• Utilize DispatchMode Optima
• Alargue as janelas horárias
• Permita chegada antecipada (CanArriveEarly = true) quando adequado
• Adicione veículos ou aumente o horário de trabalho dos veículos

5) Veículos insuficientes ou encaminhamento de frota incompleto

• Adicione mais veículos
• Aumente a capacidade (peso e volume)
• Aumente o horário de trabalho
• Utilize DispatchMode MinimumVehicles se o seu objetivo for minimizar o número de veículos necessários

6) A API devolve “key invalid” (autenticação)

A autenticação da TrackRoad utiliza uma chave de API estável chamada TrackServiceKey. “Key invalid” significa normalmente que a chave está em falta, incorreta ou não foi enviada no cabeçalho correto.

• REST: envie X-API-Key: TrackServiceKey
• SOAP: envie SessionIDHeader.SessionID = TrackServiceKey
• Consulte autenticação da API para detalhes exatos.