Torna alle novità

Collegare TSC a ERP, WMS o portineria tramite OData e API

Pavel NOVOTNÝ
Blog
Collegare TSC a ERP, WMS o portineria tramite OData e API

Collegare un sistema di prenotazione a un ERP, a un WMS o a un’applicazione di portineria non deve necessariamente diventare un grande progetto di integrazione. Per un caso pratico all’ingresso bastano quattro chiamate API: ottenere un token Bearer, trovare la prenotazione tramite il suo numero, registrare l’arrivo e, in seguito, la partenza.

L’operatore della portineria non deve conoscere l’identificatore interno della prenotazione in Time Slot Control. Utilizza un dato che l’autista ha già sulla conferma o nel codice QR: ReservationNumber. TSC restituisce tramite OData il record corrispondente e il relativo identificatore Id; lo stesso identificatore Id viene poi utilizzato per le azioni di stato.

OData e API: due parti di un’unica interfaccia

Time Slot Control combina lo standard OData v4 con endpoint API convenzionali. La ripartizione dei compiti è semplice:

  • l’endpoint di autenticazione emette un token JWT Bearer,
  • OData consente di filtrare e caricare soltanto i dati necessari,
  • le azioni OData associate eseguono uno specifico passaggio del processo, ad esempio GateArrival o GateDeparture.

Il token, quindi, non si ottiene con una “query OData”. Viene emesso dall’endpoint di autenticazione della stessa API TSC e successivamente inviato nell’header di ogni richiesta OData. Tramite OData, ERP e WMS possono accedere anche ad aziende, ordini e righe d’ordine; IntegrationId permette di collegare gli identificatori TSC alle chiavi del sistema sorgente.

Cinque passaggi per collegare la portineria a Time Slot Control: numero di prenotazione, token Bearer, query OData, arrivo e partenza

Caso pratico: la portineria registra ingresso e uscita

L’autista arriva in portineria e presenta il numero di prenotazione. L’operatore lo legge con uno scanner oppure lo inserisce nell’applicazione esistente. L’applicazione verifica la prenotazione in TSC, può confrontare targa, vettore e orario pianificato e, una volta autorizzato l’ingresso, registra che il vettore si trova nell’area. All’uscita utilizza lo stesso identificatore Id e indica che il vettore ha lasciato il sito.

Gli esempi seguenti utilizzano il sandbox disponibile all’indirizzo https://api.tscsandbox.com. Sostituite il segnaposto {tenant} con il nome del vostro ambiente. L’API di produzione ha la stessa struttura all’indirizzo https://api.timeslotcontrol.com.

Prima di iniziare

Create in TSC un account API dedicato. L’account deve avere il ruolo di accesso API e soltanto i permessi realmente utilizzati dall’integrazione—in particolare la lettura delle prenotazioni e l’esecuzione delle azioni di arrivo e partenza. Non memorizzate la password nel codice sorgente; utilizzate un gestore di segreti o la configurazione protetta della piattaforma di integrazione.

1. Ottenere un token 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 risposta contiene il token:

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

Utilizzate questo valore nelle chiamate successive come Authorization: Bearer <token>. Non serve creare un token per ogni veicolo. L’integrazione può conservarlo in modo sicuro in memoria e rinnovarlo alla scadenza o dopo una risposta 401 Unauthorized.

2. Caricare la prenotazione tramite ReservationNumber

Un filtro OData individua la prenotazione tramite il suo numero. Con $select, l’applicazione della portineria carica solo i campi necessari:

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"

Una risposta tipica contiene un wrapper OData e l’array 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
    }
  ]
}

In produzione, procedete solo se la query restituisce esattamente un record conforme alle regole operative. Nessun risultato richiede una verifica manuale. Se la query restituisce più record, l’integrazione non deve selezionare automaticamente il primo. L’uso di $top=2 consente di rilevare questa condizione con un costo minimo.

3. Indicare che il vettore è presente nell’area

Dopo aver verificato la prenotazione, utilizzate l’identificatore restituito Id nell’azione associata GateArrival:

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

Una chiamata riuscita restituisce 204 No Content. TSC salva l’orario effettivo di arrivo e la modifica è immediatamente visibile nella prenotazione. Workflow, notifiche e integrazioni successive possono quindi seguire la normale configurazione dell’ambiente del cliente.

4. Registrare la partenza del vettore

All’uscita l’applicazione utilizza lo stesso identificatore Id. Il valore null indica a TSC di utilizzare l’orario corrente del server:

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

Se il dispositivo di integrazione dispone di un proprio orario evento affidabile, può inviare un valore UTC in formato ISO 8601 al posto di null, ad esempio 2026-09-01T14:32:00Z. Una chiamata riuscita restituisce nuovamente 204 No Content.

Esempio minimo completo in PowerShell

La stessa procedura può essere espressa in uno script breve. In pratica, le chiamate di arrivo e partenza vengono eseguite in momenti diversi, ma utilizzano entrambe lo stesso identificatore della prenotazione 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’esempio non contiene volutamente una password reale, un tenant specifico o dati del cliente. Un’applicazione di produzione deve inoltre prevedere l’archiviazione sicura dei segreti, timeout, nuovi tentativi controllati, la registrazione di un identificatore di correlazione e la gestione di 401, 403, 404, 429 e delle altre risposte di errore.

Perché lo stesso modello funziona anche per ERP e WMS

La portineria è un esempio immediato perché il risultato è subito visibile. Lo stesso principio funziona anche all’interno di un ERP o di un WMS:

  • l’ERP può sincronizzare aziende, ordini e righe d’ordine tramite OData,
  • il WMS può caricare la prenotazione corrente e preparare una baia o un’operazione di magazzino,
  • la portineria può registrare arrivo e partenza senza passare a un’altra applicazione,
  • gli strumenti BI possono leggere orari pianificati ed effettivi per analizzare attese e capacità di transito del sito,
  • i webhook in uscita possono notificare i sistemi a valle senza interrogazioni periodiche.

L’integrazione non deve quindi copiare l’intero modello dati. Ogni sistema carica soltanto le informazioni necessarie al proprio passaggio, mentre TSC rimane la fonte autorevole per la prenotazione e le relative tappe logistiche.

Dal prototipo a un esercizio sicuro

Verificate la prima versione nel sandbox. La documentazione API interattiva su api.tscsandbox.com consente di esplorare gli endpoint, inserire un token Bearer e ottenere subito esempi di chiamata. La procedura di accesso è descritta nel riferimento per l’autenticazione, mentre la guida OData illustra le opzioni di filtro.

In produzione, rispettate alcune regole: un account dedicato per ogni integrazione, i soli permessi necessari, la password in un archivio sicuro, il riutilizzo di un token valido, la richiesta di un unico risultato e la gestione esplicita di ogni errore. Progettate le chiamate di arrivo e partenza in modo che possano essere ripetute in sicurezza—dopo il successo, salvate l’identificatore Id; se l’esito è incerto, ricaricate prima lo stato corrente della prenotazione.

Un numero di prenotazione, uno stato aggiornato in tutto il processo

Il vantaggio principale non risiede nelle quattro richieste HTTP. Il punto è che portineria, magazzino, ufficio traffico ed ERP lavorano con la stessa prenotazione e gli stessi timestamp. Scompaiono la trascrizione manuale, le verifiche telefoniche e gli aggiornamenti tardivi dello stato.

Scoprite altre possibilità nella pagina API & Integrazioni Time Slot Control. Per provare un caso analogo con ERP, WMS, scanner o portineria, iniziate da un processo concreto nel sandbox. Il primo collegamento funzionante richiede spesso solo poche chiamate API definite con precisione.

Torna alle novità