API d’optimisation de tournées (REST + SOAP) – Guide développeur

Ce que vous pouvez développer avec l’API d’optimisation de tournées TrackRoad#

L’API permet l’optimisation de tournées pour des cas d’usage métier courants :

• Systèmes de planification de tournées de livraison (coursiers, colis, épicerie)
• Planification d’interventions terrain (techniciens, réparations, installations)
• Dispatch de flotte avec plusieurs véhicules et plusieurs arrêts
• Workflows de géocodage et de calcul d’itinéraire turn-by-turn
• Modes de dispatch avancés pour différentes stratégies de routage

Le moteur de routage prend en charge des contraintes telles que :

• Fenêtres horaires (contraintes d’arrivée et de départ)
• Limites de capacité (poids / volume)
• Équilibrage du temps et de la distance entre véhicules
• Plusieurs points de départ et d’arrivée par véhicule
• Arrêts de pause et temps de service par arrêt

REST vs SOAP#

API REST (JSON/XML)

REST est léger et courant pour les intégrations web et mobiles. TrackRoad prend en charge les appels REST avec des payloads JSON ou XML.

API SOAP

SOAP est courant dans les systèmes d’entreprise et prend en charge des références de service fortement typées en .NET. SOAP est utile si vous souhaitez utiliser des classes compilées comme DispatchSpecification, Vehicle et Location.

Authentification (TrackServiceKey)#

TrackRoad utilise une clé API stable appelée TrackServiceKey. Elle ne se comporte pas comme un identifiant de session classique qui expire. Voir l’authentification API pour les détails complets.

• REST : envoyez votre clé dans l’en-tête HTTP : X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP : envoyez votre clé dans SessionIDHeader comme SessionID

API Dispatch (appel principal d’optimisation)#

L’optimisation de tournées s’effectue avec Dispatch. Dispatch prend des véhicules plus des arrêts et renvoie des tournées optimisées par véhicule.

Référence complète : API Dispatch

Endpoint SOAP WSDL

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

Entrées Dispatch typiques

• Véhicules (chacun avec un point de départ et d’arrivée)
• Arrêts (localisations)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima, etc.)
• MinimumOptimization (précision)

Fenêtres horaires et mode Optima#

TrackRoad prend en charge les fenêtres horaires via des contraintes d’arrivée et de départ aux arrêts. Pour de meilleurs résultats, TrackRoad recommande d’utiliser DispatchMode Optima avec les fenêtres horaires.

Variables clés

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Si votre langage ne peut pas transmettre de valeurs datetime nulles, utilisez 0001-01-01T00:00:00. TrackRoad traite les dates inférieures ou égales au 1er janvier 2012 comme nulles.

En savoir plus : Optimisation de tournées avec fenêtres horaires

Comprendre les résultats Dispatch#

Dispatch renvoie des tournées optimisées par véhicule. Chaque résultat véhicule comprend des arrêts ordonnés avec des métadonnées telles que :

• Séquence des arrêts
• MatchCode et qualité de correspondance d’adresse
• Latitude et Longitude
• Temps et distance jusqu’au prochain arrêt

Conseils de performance et de montée en charge

• Regroupez les arrêts lorsque c’est possible au lieu d’optimiser une tournée à la fois
• Fournissez des temps de service et des fenêtres horaires précis pour des résultats réalistes
• Utilisez le mode Optima pour les plannings avec contraintes
• Augmentez MinimumOptimization pour une meilleure qualité sur de grands ensembles d’arrêts
• Utilisez le dispatch multi-véhicules pour le routage de flotte au lieu de requêtes séparées

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

Cet exemple montre le flux REST recommandé avec X-API-Key (TrackServiceKey).

Étape 1 — Définir les en-têtes d’authentification

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

Étape 2 — Dispatch (optimiser les tournées)

Dispatch prend des véhicules plus des arrêts et renvoie des tournées optimisées. Cet exemple utilise un véhicule et plusieurs arrêts.

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

Conseil : Pour les fenêtres horaires, utilisez DispatchMode = Optima. Si votre intégration ne peut pas envoyer de valeurs nulles, utilisez une date par défaut comme 0001-01-01T00:00:00 pour représenter “null”.

Exemple 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

Les méthodes Login et Logout historiques restent disponibles pour la compatibilité ascendante. Pour la plupart des intégrations, utilisez X-API-Key (TrackServiceKey) dans chaque requête.

Exemple SOAP C# (SessionIDHeader → Dispatch)

L’authentification SOAP TrackRoad utilise SessionIDHeader.SessionID = TrackServiceKey. Voir l’authentification pour les détails complets.

Endpoint SOAP WSDL

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

Exemple SOAP C# étape par étape

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}");
        }
    }
}

Remarques

• Utilisez le mode Optima pour les fenêtres horaires et les plannings.
• Fournissez les heures de travail du conducteur (TimeIn, TimeOut) pour un routage réaliste.
• Si vous ne pouvez pas fournir de valeurs datetime nulles, utilisez DateTime.MinValue ou une règle de date nulle.

Dépannage : erreurs API courantes et comment les corriger#

L’optimisation de tournées est un problème basé sur des contraintes. Si vous fournissez des adresses invalides ou des contraintes impossibles, comme des fenêtres horaires trop serrées, un nombre insuffisant de véhicules ou des limites de capacité dépassées, le moteur Dispatch peut renvoyer des erreurs ou produire des tournées incomplètes.

1) “Dispatch failed” ou Success = false

• Adresses d’arrêt invalides ou incomplètes
• Fenêtres horaires impossibles
• Heures de travail du véhicule trop courtes
• Nombre insuffisant de véhicules pour desservir tous les arrêts
• Contraintes de capacité dépassées

2) Certains arrêts manquent dans les tournées

Causes courantes :

• Fenêtres horaires trop strictes
• Heures de travail trop strictes
• Capacité dépassée
• Le temps de service rend le planning non faisable

3) Correspondances d’adresse invalides ou de faible qualité (problèmes MatchCode)

• Fournissez des adresses complètes (rue, ville, code postal, pays)
• Si vous avez déjà les coordonnées, envoyez Latitude et Longitude
• Validez les arrêts par géocodage avant Dispatch si nécessaire

4) Les fenêtres horaires sont irréalisables

• Utilisez DispatchMode Optima
• Élargissez les fenêtres horaires
• Autorisez l’arrivée anticipée (CanArriveEarly = true) lorsque c’est approprié
• Ajoutez des véhicules ou augmentez les heures de travail des véhicules

5) Pas assez de véhicules ou routage de flotte incomplet

• Ajoutez plus de véhicules
• Augmentez la capacité (poids et volume)
• Augmentez les heures de travail
• Utilisez DispatchMode MinimumVehicles si votre objectif est de minimiser le nombre de véhicules nécessaires

6) L’API renvoie “key invalid” (authentification)

L’authentification TrackRoad utilise une clé API stable appelée TrackServiceKey. “Key invalid” signifie généralement que la clé est absente, incorrecte ou envoyée au mauvais endroit.

• REST : envoyez X-API-Key: TrackServiceKey
• SOAP : envoyez SessionIDHeader.SessionID = TrackServiceKey
• Voir l’authentification API pour les détails exacts.