Η σύνδεση ενός συστήματος κρατήσεων με ERP, WMS ή εφαρμογή φυλακίου δεν χρειάζεται να ξεκινήσει ως μεγάλο έργο διασύνδεσης. Για ένα πρακτικό σενάριο εισόδου αρκούν τέσσερις κλήσεις API: λήψη Bearer token, εντοπισμός της κράτησης από τον αριθμό της, καταγραφή της άφιξης και αργότερα καταγραφή της αναχώρησης.

Το προσωπικό ασφαλείας δεν χρειάζεται να γνωρίζει το εσωτερικό αναγνωριστικό της κράτησης στο Time Slot Control. Χρησιμοποιεί μια τιμή που έχει ήδη ο οδηγός στην επιβεβαίωση ή στον κωδικό QR: ReservationNumber. Το TSC επιστρέφει μέσω OData την αντίστοιχη εγγραφή και το αναγνωριστικό της Id· το ίδιο αναγνωριστικό Id χρησιμοποιείται στη συνέχεια για τις ενέργειες αλλαγής κατάστασης.

OData και API: δύο μέρη της ίδιας διεπαφής

Το Time Slot Control συνδυάζει το πρότυπο OData v4 με συμβατικά API endpoints. Οι αρμοδιότητές τους είναι σαφείς:

το endpoint ελέγχου ταυτότητας εκδίδει ένα JWT Bearer token,
το OData φιλτράρει τα δεδομένα και ανακτά μόνο τα απαραίτητα πεδία,
οι δεσμευμένες ενέργειες OData εκτελούν ένα συγκεκριμένο βήμα της διαδικασίας, όπως GateArrival ή GateDeparture.

Επομένως, το token δεν λαμβάνεται μέσω «ερωτήματος OData». Εκδίδεται από το endpoint ελέγχου ταυτότητας του ίδιου API του TSC και στη συνέχεια αποστέλλεται στην κεφαλίδα κάθε αιτήματος OData. Μέσω OData διατίθενται επίσης σε συστήματα ERP και WMS εταιρείες, παραγγελίες και γραμμές παραγγελιών· το πεδίο IntegrationId συνδέει τα αναγνωριστικά του TSC με τα κλειδιά του συστήματος προέλευσης.

Πέντε βήματα για τη σύνδεση ενός φυλακίου με το Time Slot Control: αριθμός κράτησης, Bearer token, ερώτημα OData, άφιξη και αναχώρηση

Πρακτικό σενάριο: το φυλάκιο καταγράφει την είσοδο και την αναχώρηση

Ο οδηγός φτάνει στο φυλάκιο και παρουσιάζει τον αριθμό κράτησης. Ο χειριστής τον σαρώνει ή τον πληκτρολογεί στην υπάρχουσα εφαρμογή. Η εφαρμογή επαληθεύει την κράτηση στο TSC, μπορεί να ελέγξει την πινακίδα κυκλοφορίας, τον μεταφορέα και την προγραμματισμένη ώρα και, μόλις εγκριθεί η είσοδος, καταγράφει ότι ο μεταφορέας βρίσκεται στις εγκαταστάσεις. Στην έξοδο χρησιμοποιεί το ίδιο αναγνωριστικό Id και επισημαίνει ότι ο μεταφορέας αποχώρησε από τις εγκαταστάσεις.

Τα παρακάτω παραδείγματα χρησιμοποιούν το δοκιμαστικό περιβάλλον στη διεύθυνση https://api.tscsandbox.com. Αντικαταστήστε το σύμβολο κράτησης θέσης {tenant} με το όνομα του περιβάλλοντός σας. Το παραγωγικό API έχει την ίδια δομή στη διεύθυνση https://api.timeslotcontrol.com.

Πριν ξεκινήσετε

Δημιουργήστε στο TSC έναν αποκλειστικό λογαριασμό API. Ο λογαριασμός χρειάζεται τον ρόλο πρόσβασης API και μόνο τα δικαιώματα που χρησιμοποιεί πραγματικά η διασύνδεση, ιδιαίτερα το δικαίωμα ανάγνωσης κρατήσεων και εκτέλεσης των ενεργειών άφιξης και αναχώρησης. Μην αποθηκεύετε τον κωδικό πρόσβασης απευθείας στον πηγαίο κώδικα· χρησιμοποιήστε διαχειριστή μυστικών ή την ασφαλή διαμόρφωση της πλατφόρμας διασύνδεσης.

1. Λάβετε Bearer token

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

Η απόκριση περιέχει το token:

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

Χρησιμοποιήστε αυτή την τιμή στις επόμενες κλήσεις ως Authorization: Bearer <token>. Δεν χρειάζεται να δημιουργείτε ξεχωριστό token για κάθε όχημα. Η διασύνδεση μπορεί να το διατηρεί με ασφάλεια στη μνήμη και να το ανανεώνει όταν λήξει ή μετά από απόκριση 401 Unauthorized.

2. Ανακτήστε την κράτηση μέσω ReservationNumber

Ένα φίλτρο OData εντοπίζει την κράτηση από τον αριθμό της. Με το $select, η εφαρμογή του φυλακίου ανακτά μόνο τα πεδία που χρειάζεται:

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"

Μια τυπική απόκριση περιλαμβάνει το περίβλημα OData και έναν πίνακα 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
    }
  ]
}

Στο παραγωγικό περιβάλλον, συνεχίστε μόνο όταν το ερώτημα επιστρέφει ακριβώς μία εγγραφή και αυτή πληροί τους επιχειρησιακούς κανόνες. Αν δεν υπάρχει αντιστοίχιση, απαιτείται χειροκίνητος έλεγχος. Αν επιστραφούν περισσότερες εγγραφές, η διασύνδεση δεν πρέπει να επιλέξει αυτόματα την πρώτη. Με το $top=2, ο εντοπισμός αυτής της κατάστασης απαιτεί ελάχιστους πόρους.

3. Επισημάνετε ότι ο μεταφορέας βρίσκεται στις εγκαταστάσεις

Αφού επαληθεύσετε την κράτηση, χρησιμοποιήστε το αναγνωριστικό Id που επιστράφηκε στη δεσμευμένη ενέργεια GateArrival:

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

Μια επιτυχημένη κλήση επιστρέφει 204 No Content. Το TSC αποθηκεύει την πραγματική ώρα άφιξης και η αλλαγή εμφανίζεται αμέσως στην κράτηση. Οι επόμενες ροές εργασίας, οι ειδοποιήσεις και οι διασυνδέσεις μπορούν στη συνέχεια να λειτουργήσουν σύμφωνα με τη συνήθη διαμόρφωση του περιβάλλοντος του πελάτη.

4. Κατά την έξοδο, επισημάνετε ότι ο μεταφορέας αποχώρησε

Στην έξοδο, η εφαρμογή χρησιμοποιεί το ίδιο αναγνωριστικό Id. Η τιμή null υποδεικνύει στο TSC να χρησιμοποιήσει την τρέχουσα ώρα του διακομιστή:

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

Αν η συσκευή διασύνδεσης διαθέτει δική της αξιόπιστη ώρα συμβάντος, μπορεί να στείλει αντί για null μια τιμή UTC σε μορφή ISO 8601, για παράδειγμα 2026-09-01T14:32:00Z. Η επιτυχημένη κλήση επιστρέφει ξανά 204 No Content.

Πλήρες ελάχιστο παράδειγμα PowerShell

Η ίδια διαδικασία μπορεί να αποτυπωθεί σε ένα σύντομο script. Στην πράξη, οι κλήσεις άφιξης και αναχώρησης εκτελούνται σε διαφορετικούς χρόνους, αλλά και οι δύο χρησιμοποιούν το ίδιο αναγνωριστικό κράτησης 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)

Το παράδειγμα σκόπιμα δεν περιέχει πραγματικό κωδικό πρόσβασης, tenant ή δεδομένα πελάτη. Μια παραγωγική εφαρμογή πρέπει επίσης να προσθέσει ασφαλή αποθήκευση μυστικών, χρονικά όρια, ελεγχόμενες επαναλήψεις, καταγραφή correlation ID και διαχείριση των αποκρίσεων 401, 403, 404, 429 καθώς και άλλων σφαλμάτων.

Γιατί το ίδιο μοτίβο λειτουργεί για ERP και WMS

Το φυλάκιο είναι ένα σαφές παράδειγμα, επειδή το αποτέλεσμα είναι άμεσα ορατό. Η ίδια αρχή λειτουργεί και μέσα σε ERP ή WMS:

το ERP μπορεί να συγχρονίζει εταιρείες, παραγγελίες και γραμμές παραγγελιών μέσω OData,
το WMS μπορεί να ανακτά την τρέχουσα κράτηση και να προετοιμάζει μια ράμπα ή εργασία αποθήκης,
το φυλάκιο μπορεί να καταγράφει άφιξη και αναχώρηση χωρίς μετάβαση σε άλλη εφαρμογή,
τα εργαλεία BI μπορούν να διαβάζουν προγραμματισμένους και πραγματικούς χρόνους για την αξιολόγηση της αναμονής και της δυναμικότητας των εγκαταστάσεων,
τα εξερχόμενα webhooks μπορούν να ενημερώνουν τα επόμενα συστήματα για αλλαγές χωρίς τακτικό polling.

Επομένως, η διασύνδεση δεν χρειάζεται να αντιγράψει ολόκληρο το μοντέλο δεδομένων. Κάθε σύστημα ανακτά μόνο τα δεδομένα που απαιτούνται για το δικό του βήμα, ενώ το TSC παραμένει η έγκυρη πηγή δεδομένων για την κράτηση και τα ορόσημα της διαδικασίας logistics.

Από το πρωτότυπο σε ασφαλή παραγωγική λειτουργία

Επαληθεύστε την πρώτη έκδοση στο δοκιμαστικό περιβάλλον. Η διαδραστική τεκμηρίωση API στη διεύθυνση api.tscsandbox.com επιτρέπει να περιηγηθείτε στα endpoints, να εισαγάγετε Bearer token και να λάβετε αμέσως παραδείγματα κλήσεων. Η ακριβής διαδικασία σύνδεσης περιγράφεται στην τεκμηρίωση ελέγχου ταυτότητας, ενώ ο οδηγός OData εξηγεί τις επιλογές φιλτραρίσματος.

Για παραγωγική εγκατάσταση, ακολουθήστε μερικούς κανόνες: χρησιμοποιήστε έναν αποκλειστικό λογαριασμό για κάθε διασύνδεση, εκχωρήστε τα ελάχιστα απαιτούμενα δικαιώματα, φυλάξτε τον κωδικό πρόσβασης σε ασφαλή αποθήκευση, επαναχρησιμοποιήστε ένα έγκυρο token, απαιτήστε ακριβώς ένα αποτέλεσμα ερωτήματος και διαχειριστείτε ρητά κάθε κατάσταση σφάλματος. Σχεδιάστε τις κλήσεις άφιξης και αναχώρησης έτσι ώστε να μπορούν να επαναληφθούν με ασφάλεια: μετά την επιτυχία αποθηκεύστε το αναγνωριστικό Id· αν το αποτέλεσμα είναι αβέβαιο, ανακτήστε την τρέχουσα κατάσταση της κράτησης πριν προσπαθήσετε ξανά.

Ένας αριθμός κράτησης, μία ενημερωμένη κατάσταση σε όλη τη διαδικασία

Το κύριο όφελος δεν είναι τα ίδια τα τέσσερα αιτήματα HTTP. Είναι ότι το φυλάκιο, η αποθήκη, το τμήμα διακίνησης και το ERP εργάζονται με την ίδια κράτηση και τις ίδιες χρονικές σημάνσεις. Εξαλείφονται η χειροκίνητη επανεισαγωγή, η τηλεφωνική επαλήθευση και οι καθυστερημένες ενημερώσεις κατάστασης.

Δείτε περισσότερες επιλογές στη σελίδα API και διασυνδέσεις του Time Slot Control. Για να δοκιμάσετε ένα παρόμοιο σενάριο για το ERP, το WMS, τον σαρωτή ή το φυλάκιό σας, ξεκινήστε με μία συγκεκριμένη διαδικασία στο δοκιμαστικό περιβάλλον. Για την πρώτη λειτουργική σύνδεση συχνά αρκούν λίγες, με ακρίβεια καθορισμένες κλήσεις API.