Delopt API — Οδηγός για Developers

API διαθέσιμο στην τοποθεσία: api.delopt.transopt.io

Αυθεντικοποίηση

Κάθε αίτημα (εκτός από /health και /demo/optimize) απαιτεί το API key σου στο header:

x-api-key: <το-κλειδί-σου>

Επικοινώνησε με το support@transopt.io για να αποκτήσεις ένα.

Βασική Ροή Εργασίας

1. Υποβολή αιτήματος βελτιστοποίησης

Χρησιμοποίησε το για να δημιουργήσεις το βέλτιστο πλάνο παραδόσεων (dispatch) με βάση τις ενεργές παραγγελίες και τα διαθέσιμα οχήματα.

POST /optimize

Δημιούργησε ένα request body με τρία arrays:

{
  "depots": [
    { "id": "d-0", "lat": 37.871487, "lon": 23.7646273 }
  ],
  "vehicles": [
    { "id": "v-0", "depot_id": "d-0", "capacity": 5 }
  ],
  "orders": [
    {
      "id": "o-100",
      "lat": 37.8644013,
      "lon": 23.7505317,
      "dt_received": "2026-06-25T09:57:35Z",
      "dt_prepared": "2026-06-25T09:59:35Z"
    }
  ]
}

Βασικά query params:

Παράμετρος	Περιγραφή	Default
`dur_optimization`	Πόση ώρα τρέχει ο optimizer. Μεγαλύτερη τιμή = καλύτερες διαδρομές, περισσότερη καθυστέρηση.	`PT1S`
`max_deliveries_per_vehicle`	Μέγιστες παραδόσεις ανά όχημα (1–2).	`1`

Η απόκριση είναι ένα Dispatch αντικείμενο με τρία arrays:

orders — κάθε παραγγελία με το ανατεθειμένο vehicle_id, delivery_id, dt_depart και dt_arrive
vehicles — ώρα αναχώρησης και επιστροφής κάθε οχήματος
deliveries — τα delivery runs, ομαδοποιημένα order_ids ανά δρομολόγιο οχήματος

2. Αναχώρηση μεμονωμένου οχήματος (`POST /depart-vehicle`)

Χρησιμοποίησε το λίγο πριν αναχωρήσει ένα συγκεκριμένο όχημα. Περιλαμβάνει τον αναμενόμενο χρόνο μετακίνησης του οχήματος και τους μεμονωμένους χρόνους άφιξης για κάθε παραγγελία, με βάση την πραγματική ώρα αναχώρησης.

Το request body δέχεται ένα μόνο depot, ένα μόνο όχημα και μια λίστα παραγγελιών:

{
  "depot": { "id": "d-0", "lat": 37.871487, "lon": 23.7646273 },
  "vehicle": { "id": "v-0", "depot_id": "d-0", "capacity": 5 },
  "orders": [
    {
      "id": "o-100",
      "lat": 37.8644013,
      "lon": 23.7505317,
      "dt_received": "2026-06-25T09:57:35Z",
      "dt_prepared": "2026-06-25T09:59:35Z"
    }
  ]
}

Προαιρετικά, μπορείς να περάσεις ένα delivery_id query param για να επισημάνεις το αποτέλεσμα με δικό σου εξωτερικό αναγνωριστικό:

POST /depart-vehicle?delivery_id=my-delivery-123

Η απόκριση είναι ένα VehicleDeparture αντικείμενο:

vehicle — το προγραμματισμένο dt_depart και εκτιμώμενο dt_return του οχήματος
orders — οι παραγγελίες που ανατέθηκαν σε αυτό το δρομολόγιο, με dt_depart, dt_arrive και delivery_id

Δοκίμασέ το χωρίς API key

Το POST /demo/optimize δέχεται το ίδιο request body χωρίς αυθεντικοποίηση. Χρήσιμο για integration testing πριν αποκτήσεις κλειδί.

Αναφορά Πεδίων

Depot

Πεδίο	Υποχρεωτικό	Περιγραφή
`id`	✅	Μοναδικό αναγνωριστικό για το depot (π.χ. `"d-0"`)
`lat`	✅	Γεωγραφικό πλάτος σε δεκαδικές μοίρες (`-90` έως `90`)
`lon`	✅	Γεωγραφικό μήκος σε δεκαδικές μοίρες (`-180` έως `180`)

Vehicle (Όχημα)

Πεδίο	Υποχρεωτικό	Περιγραφή
`id`	✅	Μοναδικό αναγνωριστικό για το όχημα (π.χ. `"v-0"`)
`depot_id`	✅	ID του depot όπου σταθμεύει το όχημα
`capacity`	✅	Αριθμός παραγγελιών που μπορεί να μεταφέρει ταυτόχρονα
`lat`	➖	Τρέχον γεωγραφικό πλάτος του οχήματος. Αν παραληφθεί, χρησιμοποιείται η τοποθεσία του depot
`lon`	➖	Τρέχον γεωγραφικό μήκος του οχήματος. Αν παραληφθεί, χρησιμοποιείται η τοποθεσία του depot
`dt_return`	➖	Πότε το όχημα είναι διαθέσιμο εκ νέου. Ο engine δεν αναθέτει δρομολόγιο πριν από αυτή την ώρα

Order (Παραγγελία)

Πεδίο	Υποχρεωτικό	Περιγραφή
`id`	✅	Μοναδικό αναγνωριστικό για την παραγγελία (π.χ. `"o-100"`)
`lat`	✅	Γεωγραφικό πλάτος παράδοσης σε δεκαδικές μοίρες
`lon`	✅	Γεωγραφικό μήκος παράδοσης σε δεκαδικές μοίρες
`dt_received`	➖	Πότε ελήφθη η παραγγελία. ISO 8601 timestamp
`dt_prepared`	➖	Πότε είναι έτοιμη η παραγγελία για παραλαβή. Ο engine δεν αποστέλλει πριν από αυτή την ώρα
`dt_arrive_at`	➖	Αυστηρή προθεσμία — η παραγγελία πρέπει να παραδοθεί έως αυτή την ώρα
`dur_wait_target`	➖	Στόχος μέγιστου χρόνου αναμονής από την παραγγελία έως την παράδοση. Default: `PT15M`
`dur_degrade_start`	➖	Πόση ώρα μετά τη φόρτωση αρχίζει η υποβάθμιση της ποιότητας του φαγητού. Default: `PT1H`
`priority`	➖	Αν `true`, η παραγγελία αντιμετωπίζεται ως επείγουσα και αναχωρεί το συντομότερο δυνατό. Default: `false`
`address`	➖	Διεύθυνση παράδοσης σε αναγνώσιμη μορφή. Μεταφέρεται αυτούσια στην απόκριση, δεν χρησιμοποιείται από τον engine
`items`	➖	Λίστα αναγνωριστικών ή περιγραφών αντικειμένων της παραγγελίας. Μεταφέρεται αυτούσια στην απόκριση

Συμβάσεις Πεδίων

Πεδία `dt_` — Timestamps

Όλα τα πεδία με πρόθεμα dt_ είναι ISO 8601 timestamps και πρέπει να συμπεριλαμβάνουν timezone. Συνιστάται UTC.

2026-06-25T10:00:00+00:00   ✅
2026-06-25T10:00:00Z        ✅
2026-06-25T10:00:00         ❌ λείπει το timezone

Πεδία `dur_` — Διάρκειες

Όλα τα πεδία με πρόθεμα dur_ αντιπροσωπεύουν διάρκεια και δέχονται οποιαδήποτε από τις δύο μορφές:

Μορφή	Παράδειγμα	Σημασία
ISO 8601 duration	`PT30M`	30 λεπτά
ISO 8601 duration	`PT1H30M`	1 ώρα 30 λεπτά
Δευτερόλεπτα	`1800`	30 λεπτά

Συμβουλές

Το dt_prepared πρέπει να είναι ≥ dt_received — ο engine δεν αποστέλλει πριν η παραγγελία είναι έτοιμη
Τα lat/lon του οχήματος είναι προαιρετικά — αν παραληφθούν, χρησιμοποιείται η τοποθεσία της αποθήκης ως σημείο εκκίνησης
Το dt_return σε ένα όχημα ενημερώνει τον engine ότι το όχημα είναι απασχολημένο μέχρι εκείνη την ώρα