Retour aux actualités

Connecter TSC à un ERP, WMS ou poste de garde via OData et API

Pavel NOVOTNÝ
Blog
Connecter TSC à un ERP, WMS ou poste de garde via OData et API

Connecter un système de réservation à un ERP, un WMS ou une application de poste de garde ne nécessite pas forcément un vaste projet d’intégration. Pour un cas concret à l’entrée du site, quatre appels API suffisent : obtenir un jeton Bearer, retrouver la réservation par son numéro, enregistrer l’arrivée puis, plus tard, le départ.

L’agent du poste de garde n’a pas besoin de connaître l’identifiant interne de la réservation dans Time Slot Control. Il utilise une donnée que le conducteur possède déjà sur sa confirmation ou dans le code QR : ReservationNumber. TSC renvoie via OData l’enregistrement correspondant et son identifiant Id ; le même identifiant Id est ensuite utilisé pour les actions de changement d’état.

OData et API : les deux parties d’une même interface

Time Slot Control associe le standard OData v4 à des endpoints API classiques. La répartition des rôles est simple :

  • l’endpoint d’authentification délivre un jeton JWT Bearer,
  • OData permet de filtrer et de charger uniquement les données nécessaires,
  • les actions OData liées exécutent une étape précise du processus, par exemple GateArrival ou GateDeparture.

Le jeton n’est donc pas obtenu par une « requête OData ». Il est délivré par l’endpoint d’authentification de la même API TSC, puis envoyé dans l’en-tête de chaque requête OData. Les ERP et WMS peuvent également accéder par OData aux sociétés, commandes et lignes de commande ; IntegrationId permet d’associer les identifiants TSC aux clés du système source.

Cinq étapes pour connecter le poste de garde à Time Slot Control : numéro de réservation, jeton Bearer, requête OData, arrivée et départ

Cas pratique : le poste de garde enregistre l’entrée et la sortie

Le conducteur se présente au poste de garde avec son numéro de réservation. L’agent le scanne ou le saisit dans l’application existante. L’application vérifie la réservation dans TSC, peut comparer l’immatriculation, le transporteur et l’heure prévue, puis enregistre la présence du transporteur sur le site une fois l’entrée autorisée. À la sortie, elle utilise le même identifiant Id et indique que le transporteur a quitté le site.

Les exemples suivants utilisent le sandbox disponible à l’adresse https://api.tscsandbox.com. Remplacez le paramètre {tenant} par le nom de votre environnement. L’API de production possède la même structure à l’adresse https://api.timeslotcontrol.com.

Avant de commencer

Créez dans TSC un compte API dédié. Ce compte doit disposer du rôle d’accès à l’API et uniquement des autorisations réellement utilisées par l’intégration—notamment la lecture des réservations et l’exécution des actions d’arrivée et de départ. Ne stockez pas le mot de passe dans le code source ; utilisez un gestionnaire de secrets ou la configuration sécurisée de votre plateforme d’intégration.

1. Obtenir un jeton Bearer

curl -X POST "https://api.tscsandbox.com/v1/{tenant}/Token" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "api-gatehouse@example.com",
    "Password": "<secret-from-vault>"
  }'

La réponse contient le jeton :

{
  "token": "eyJhbGciOi..."
}

Utilisez cette valeur dans les appels suivants sous la forme Authorization: Bearer <token>. Il n’est pas nécessaire de créer un jeton pour chaque véhicule. L’intégration peut le conserver de manière sécurisée en mémoire et le renouveler à son expiration ou après une réponse 401 Unauthorized.

2. Charger la réservation par ReservationNumber

Un filtre OData retrouve la réservation à partir de son numéro. Avec $select, l’application du poste de garde ne charge que les champs dont elle a besoin :

curl --get "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation" \
  -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "\$filter=ReservationNumber eq 'R-2026-00421'" \
  --data-urlencode "\$select=Id,ReservationNumber,VehicleNumberPlate,Carrier,Start,End,RealGateVehicleArrival,RealGateVehicleDeparture" \
  --data-urlencode "\$top=2"

Une réponse type contient une enveloppe OData et le tableau value :

{
  "@odata.context": "https://api.tscsandbox.com/odata/v1/{tenant}/$metadata#Reservation(...)" ,
  "value": [
    {
      "Id": "37efcb13-f1cb-4a61-baea-adfb4337036f",
      "ReservationNumber": "R-2026-00421",
      "VehicleNumberPlate": "1AB2345",
      "Carrier": "Example Carrier",
      "Start": "2026-09-01T12:30:00Z",
      "End": "2026-09-01T13:30:00Z",
      "RealGateVehicleArrival": null,
      "RealGateVehicleDeparture": null
    }
  ]
}

En production, poursuivez uniquement si la requête renvoie exactement un enregistrement conforme aux règles opérationnelles. L’absence de résultat doit entraîner une vérification manuelle. Si plusieurs enregistrements sont renvoyés, l’intégration ne doit pas sélectionner automatiquement le premier. L’utilisation de $top=2 permet de détecter ce cas à faible coût.

3. Indiquer que le transporteur est sur le site

Après avoir vérifié la réservation, utilisez l’identifiant renvoyé Id dans l’action liée GateArrival :

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateArrival" \
  -H "Authorization: Bearer ${TOKEN}"

Un appel réussi renvoie 204 No Content. TSC enregistre l’heure réelle d’arrivée et la modification apparaît immédiatement sur la réservation. Les workflows, notifications et intégrations en aval peuvent ensuite suivre la configuration habituelle de l’environnement client.

4. Enregistrer le départ du transporteur

À la sortie, l’application utilise le même identifiant Id. La valeur null indique à TSC d’utiliser l’heure actuelle du serveur :

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateDeparture" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "GateDepartureDateTime": null }'

Si le dispositif d’intégration dispose de sa propre heure d’événement fiable, il peut envoyer une valeur UTC au format ISO 8601 à la place de null, par exemple 2026-09-01T14:32:00Z. Un appel réussi renvoie de nouveau 204 No Content.

Exemple minimal complet en PowerShell

La même procédure peut être écrite dans un court script. En pratique, les appels d’arrivée et de départ sont exécutés à des moments différents, mais utilisent le même identifiant de réservation Id :

$baseUri = 'https://api.tscsandbox.com'
$tenant = '<tenant>'
$reservationNumber = 'R-2026-00421'

$tokenResponse = Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUri/v1/$tenant/Token" `
  -ContentType 'application/json' `
  -Body (@{
    Username = 'api-gatehouse@example.com'
    Password = '<secret-from-vault>'
  } | ConvertTo-Json)

$headers = @{
  Authorization = "Bearer $($tokenResponse.token)"
}

$safeNumber = $reservationNumber.Replace("'", "''")
$filter = [Uri]::EscapeDataString("ReservationNumber eq '$safeNumber'")
$select = 'Id,ReservationNumber,VehicleNumberPlate,Carrier,RealGateVehicleArrival,RealGateVehicleDeparture'
$queryUri = "$baseUri/odata/v1/$tenant/Reservation?`$filter=$filter&`$select=$select&`$top=2"
$result = Invoke-RestMethod -Method Get -Uri $queryUri -Headers $headers
$reservations = @($result.value)

if ($reservations.Count -ne 1) {
  throw "Expected exactly one reservation, returned: $($reservations.Count)."
}

$reservationId = $reservations[0].Id

# When entry is permitted
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateArrival" `
  -Headers $headers

# Later, at the exit
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateDeparture" `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body (@{ GateDepartureDateTime = $null } | ConvertTo-Json)

L’exemple ne contient volontairement aucun mot de passe réel, tenant précis ou donnée client. Une application de production doit également prévoir le stockage sécurisé des secrets, des délais d’expiration, des relances contrôlées, la journalisation d’un identifiant de corrélation ainsi que le traitement de 401, 403, 404, 429 et des autres réponses d’erreur.

Pourquoi ce modèle convient aussi aux ERP et WMS

Le poste de garde constitue un exemple parlant, car le résultat est immédiatement visible. Le même principe fonctionne aussi au sein d’un ERP ou d’un WMS :

  • l’ERP peut synchroniser les sociétés, les commandes et les lignes de commande via OData,
  • le WMS peut charger la réservation en cours et préparer un quai ou une opération d’entrepôt,
  • le poste de garde peut enregistrer l’arrivée et le départ sans passer à une autre application,
  • les outils BI peuvent lire les heures prévues et réelles afin d’analyser l’attente et le débit du site,
  • les webhooks sortants peuvent signaler les changements aux systèmes en aval sans interrogation périodique.

L’intégration n’a donc pas besoin de copier l’ensemble du modèle de données. Chaque système charge uniquement les informations nécessaires à son étape, tandis que TSC reste la source de référence pour la réservation et ses jalons logistiques.

Du prototype à une exploitation sécurisée

Validez la première version dans le sandbox. La documentation API interactive disponible sur api.tscsandbox.com permet de parcourir les endpoints, de saisir un jeton Bearer et d’obtenir immédiatement des exemples d’appels. La procédure exacte de connexion est décrite dans la référence d’authentification, tandis que le guide OData présente les possibilités de filtrage.

En production, respectez quelques règles : un compte dédié par intégration, les autorisations minimales nécessaires, le mot de passe dans un stockage sécurisé, la réutilisation d’un jeton valide, l’exigence d’un résultat unique et le traitement explicite de chaque erreur. Concevez les appels d’arrivée et de départ pour qu’ils puissent être répétés sans risque—après un succès, enregistrez l’identifiant Id ; si le résultat est incertain, rechargez d’abord l’état actuel de la réservation.

Un numéro de réservation, un état à jour dans tout le processus

Le principal avantage ne réside pas dans les quatre requêtes HTTP elles-mêmes. Il vient du fait que le poste de garde, l’entrepôt, l’exploitation transport et l’ERP travaillent avec la même réservation et les mêmes horodatages. La ressaisie manuelle, les vérifications téléphoniques et les mises à jour tardives disparaissent.

Découvrez d’autres possibilités sur la page API & Intégrations Time Slot Control. Pour tester un scénario similaire avec votre ERP, WMS, scanner ou poste de garde, commencez par un processus précis dans le sandbox. La première connexion fonctionnelle ne demande souvent que quelques appels API clairement définis.

Retour aux actualités