API de optimización de rutas (REST + SOAP) – Guía para desarrolladores

Qué puede construir con la API de optimización de rutas de TrackRoad#

La API permite optimización de rutas para casos de negocio comunes:

• Sistemas de planificación de rutas de entrega (mensajería, paquetería, grocery)
• Programación de servicios en campo (técnicos, reparaciones, instalaciones)
• Dispatch de flotas con múltiples vehículos y múltiples paradas
• Flujos de geocodificación y rutas giro a giro
• Modos avanzados de dispatch para distintas estrategias de ruteo

El motor de ruteo admite restricciones como:

• Ventanas horarias (restricciones de llegada y salida)
• Límites de capacidad (peso / volumen)
• Balanceo de tiempo y distancia entre vehículos
• Múltiples puntos de inicio y finalización por vehículo
• Paradas de descanso y tiempo de servicio por parada

REST vs SOAP#

API REST (JSON/XML)

REST es ligero y común para integraciones web y móviles. TrackRoad admite llamadas REST con payloads JSON o XML.

API SOAP

SOAP es común en sistemas empresariales y soporta referencias de servicio fuertemente tipadas en .NET. Es útil si desea clases compiladas como DispatchSpecification, Vehicle y Location.

Autenticación (TrackServiceKey)#

TrackRoad utiliza una clave API estable llamada TrackServiceKey. No funciona como una session ID clásica con expiración. Consulte autenticación de la API para ver todos los detalles.

• REST: Envíe su clave en el encabezado HTTP: X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP: Envíe su clave en SessionIDHeader como SessionID

API Dispatch (llamada principal de optimización)#

La optimización de rutas se realiza mediante Dispatch. Dispatch toma vehículos más paradas y devuelve rutas optimizadas por vehículo.

Referencia completa: API Dispatch

Endpoint SOAP WSDL

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

Entradas típicas de Dispatch

• Vehículos (cada uno con ubicación de inicio y finalización)
• Paradas (ubicaciones)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima, etc.)
• MinimumOptimization (precisión)

Ventanas horarias y modo Optima#

TrackRoad admite ventanas horarias mediante restricciones de llegada y salida por parada. Para mejores resultados, TrackRoad recomienda usar DispatchMode Optima con ventanas horarias.

Variables clave

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Si su lenguaje no puede enviar valores datetime nulos, use 0001-01-01T00:00:00. TrackRoad trata las fechas menores o iguales al 1 de enero de 2012 como nulas.

Más información: Optimización de rutas con ventanas horarias

Cómo entender los resultados de Dispatch#

Dispatch devuelve rutas optimizadas por vehículo. Cada resultado incluye paradas ordenadas con metadatos como:

• Secuencia de parada
• MatchCode y confianza de coincidencia de dirección
• Latitud y Longitud
• Tiempo y distancia hasta la siguiente parada

Consejos de rendimiento y escalado

• Agrupe paradas siempre que sea posible en lugar de optimizar una ruta cada vez
• Proporcione tiempos de servicio y ventanas horarias precisos para obtener resultados realistas
• Use el modo Optima para programaciones con restricciones
• Aumente minimum optimization para una mejor calidad con conjuntos grandes de paradas
• Use dispatch multi-vehículo para el ruteo de flotas en lugar de solicitudes separadas

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

Este ejemplo muestra el flujo REST recomendado usando X-API-Key (TrackServiceKey).

Paso 1 — Definir encabezados de autenticación

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

Paso 2 — Dispatch (optimizar rutas)

Dispatch toma vehículos más paradas y devuelve rutas optimizadas. Este ejemplo usa un vehículo y múltiples paradas.

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
    }
  ]
}

Consejo: Para ventanas horarias, use DispatchMode = Optima. Si su integración no puede enviar valores nulos, use una fecha por defecto como 0001-01-01T00:00:00 para representar “null”.

Ejemplo 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

Login y Logout heredados siguen disponibles por compatibilidad hacia atrás. Para la mayoría de las integraciones, use X-API-Key (TrackServiceKey) en cada solicitud.

Ejemplo SOAP C# (SessionIDHeader → Dispatch)

La autenticación SOAP de TrackRoad usa SessionIDHeader.SessionID = TrackServiceKey. Consulte autenticación para ver todos los detalles.

Endpoint SOAP WSDL

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

Ejemplo SOAP C# paso a paso

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

• Use el modo Optima para ventanas horarias y programaciones.
• Proporcione el horario laboral del conductor (TimeIn, TimeOut) para obtener rutas realistas.
• Si no puede proporcionar valores datetime nulos, use DateTime.MinValue o una regla de fecha nula.

Resolución de problemas: errores comunes de la API y cómo corregirlos#

La optimización de rutas es un problema basado en restricciones. Si proporciona direcciones no válidas o restricciones imposibles, como ventanas horarias muy estrictas, vehículos insuficientes o límites de capacidad excedidos, el motor Dispatch puede devolver errores o producir rutas incompletas.

1) “Dispatch failed” o Success = false

• Direcciones de parada no válidas o incompletas
• Ventanas horarias imposibles
• Horario laboral del vehículo demasiado corto
• No hay suficientes vehículos para atender todas las paradas
• Se excedieron las restricciones de capacidad

2) Faltan algunas paradas en las rutas

Causas comunes:

• Ventanas horarias demasiado estrictas
• Horario laboral demasiado estricto
• Capacidad excedida
• El tiempo de servicio lleva el horario más allá de los límites factibles

3) Coincidencias de dirección inválidas o de baja calidad (problemas de MatchCode)

• Proporcione direcciones completas (calle, ciudad, código postal, país)
• Si ya tiene coordenadas, envíe Latitud y Longitud
• Valide las paradas con geocodificación antes de Dispatch cuando sea necesario

4) Las ventanas horarias no son factibles

• Use DispatchMode Optima
• Amplíe las ventanas horarias
• Permita llegada anticipada (CanArriveEarly = true) cuando corresponda
• Añada vehículos o aumente el horario laboral del vehículo

5) Vehículos insuficientes o ruteo de flota incompleto

• Añada más vehículos
• Aumente la capacidad (peso y volumen)
• Aumente el horario laboral
• Use DispatchMode MinimumVehicles si su objetivo es minimizar el número de vehículos requeridos

6) La API devuelve “key invalid” (autenticación)

La autenticación de TrackRoad usa una clave API estable llamada TrackServiceKey. “Key invalid” normalmente significa que la clave falta, es incorrecta o no se envió en el lugar correcto.

• REST: envíe X-API-Key: TrackServiceKey
• SOAP: envíe SessionIDHeader.SessionID = TrackServiceKey
• Consulte autenticación de la API para ver los detalles exactos.