API αρχείων OptiRoutes

Τι είναι

Κάθε εταιρεία στο OptiRoutes έχει τον δικό της ιδιωτικό φάκελο αρχείων: τις παραδόσεις που φορτώνει, τα υπογεγραμμένα δελτία παράδοσης (POD) με τις φωτογραφίες και τις υπογραφές τους, τις εξαγωγές διαδρομών και τις αναφορές τέλους ημέρας. Το API αρχείων επιτρέπει στα συστήματά σας να διαβάζουν και να γράφουν απευθείας σε αυτόν τον φάκελο, χωρίς ενδιάμεσο διακομιστή FTP.

• Διεύθυνση: https://srv2.optiroutes.com/api/v1 — μόνο HTTPS.
• Πρόσβαση: ένα κλειδί API που δημιουργεί ο ίδιος ο διευθυντής της εταιρείας στο OptiRoutes, στις Ρυθμίσεις → API και αρχεία. Δεν χρειάζεται αίτημα προς την υποστήριξη του OptiRoutes.
• Όλοι οι τύποι αρχείων με τους οποίους εργάζεται σήμερα το σύστημα: CSV, JSON, TXT, XLSX/XLS, PDF και εικόνες.
• Οι απαντήσεις είναι σε JSON, εκτός από τις λήψεις αρχείων, που επιστρέφουν το ίδιο το αρχείο.

Ξεκινήστε με 3 βήματα

1. Δημιουργήστε ένα κλειδί. Στο OptiRoutes, ο διευθυντής ανοίγει τις Ρυθμίσεις → API και αρχεία, επιλέγει Νέο κλειδί, του δίνει ένα όνομα (για παράδειγμα «διακομιστής ERP»), επιλέγει τα δικαιώματα και αντιγράφει το κλειδί. Το κλειδί εμφανίζεται μόνο μία φορά.
2. Ελέγξτε τη σύνδεση.

   curl -H "Authorization: Bearer $OPTIROUTES_KEY" https://srv2.optiroutes.com/api/v1/me

3. Κατεβάστε τα υπογεγραμμένα POD της ημέρας σε ένα ενιαίο ZIP:

   curl -H "Authorization: Bearer $OPTIROUTES_KEY" -o pod.zip "https://srv2.optiroutes.com/api/v1/pod/archive?date=$(date +%F)"

Ασφάλεια — παρακαλούμε διαβάστε

• Αντιμετωπίστε το κλειδί σαν κωδικό πρόσβασης. Φυλάξτε το σε χώρο αποθήκευσης μυστικών ή σε μεταβλητή περιβάλλοντος στον διακομιστή σας. Μην το τοποθετείτε ποτέ σε ιστοσελίδα, εφαρμογή για κινητά, email, αίτημα υποστήριξης ή σύστημα ελέγχου εκδόσεων.
• Ελάχιστα δικαιώματα. Δώστε σε κάθε σύστημα δικό του κλειδί με μόνο τα δικαιώματα που χρειάζεται: pod:read (μόνο υπογεγραμμένα POD), files:read (ανάγνωση όλων των αρχείων της εταιρείας), files:write (μεταφόρτωση παραδόσεων και αρχείων του εισερχόμενου φακέλου).
• Περιορίστε τις διευθύνσεις. Όταν ο διακομιστής σας έχει σταθερή διεύθυνση IP, προσθέστε την στο κλειδί («Επιτρεπόμενες διευθύνσεις»). Κάθε κλήση από άλλη διεύθυνση απορρίπτεται.
• Λήξη και εναλλαγή. Ένα κλειδί μπορεί να λήξει μετά από έναν αριθμό ημερών. Για την εναλλαγή: δημιουργήστε νέο κλειδί, μεταφέρετε το σύστημά σας σε αυτό και έπειτα ανακαλέστε το παλιό — χωρίς διακοπή λειτουργίας.
• Ανακαλέστε αμέσως ένα κλειδί που ενδέχεται να διέρρευσε: Ρυθμίσεις → API και αρχεία → Ανάκληση κλειδιού. Παύει να λειτουργεί εντός 30 δευτερολέπτων.
• Έλεγχος. Κάθε κλήση καταγράφεται (ώρα, διεύθυνση, αρχείο, απάντηση) και εμφανίζεται στον διευθυντή στην ίδια οθόνη.
• Το OptiRoutes διατηρεί μόνο ένα αποτύπωμα (SHA-256) κάθε κλειδιού, ποτέ το ίδιο το κλειδί. Οι συνδέσεις γίνονται μόνο μέσω HTTPS (TLS 1.2+).
• Ένα κλειδί έχει πρόσβαση μόνο στον φάκελο της δικής του εταιρείας. Τα αρχεία άλλων εταιρειών και οι εσωτερικοί φάκελοι του συστήματος δεν είναι ποτέ προσβάσιμα.

Ταυτοποίηση

Στείλτε το κλειδί σε κάθε αίτημα, σε μία από αυτές τις κεφαλίδες:

Authorization: Bearer opr_2813_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
X-API-Key: opr_2813_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ένα κλειδί μοιάζει με opr_2813_… (ο αριθμός της εταιρείας, και μετά 32 τυχαίοι χαρακτήρες).

Ο φάκελος της εταιρείας

Αναφορά

Παράδειγμα απάντησης για μια λίστα:

{
  "ok": true,
  "folder": "pod/2026/10/11/",
  "items": [
    { "name": "12345_sign_2026_10_11.pdf", "path": "pod/2026/10/11/12345_sign_2026_10_11.pdf",
      "type": "file", "size": 84213, "modified": "2026-10-11T09:14:02.000Z" }
  ]
}

Συνηθισμένες εργασίες

Μεταφόρτωση του αρχείου παραδόσεων της ημέρας

# curl (Linux / macOS / Windows 10+)
curl -X PUT -H "Authorization: Bearer $OPTIROUTES_KEY" \
     --data-binary @orders.csv -H "Content-Type: text/csv" \
     "https://srv2.optiroutes.com/api/v1/files?path=orders_files/$(date +%F).csv"

# PowerShell
Invoke-RestMethod -Method Put -InFile .\orders.csv -ContentType 'text/csv' `
  -Headers @{ Authorization = "Bearer $env:OPTIROUTES_KEY" } `
  -Uri "https://srv2.optiroutes.com/api/v1/files?path=orders_files/$(Get-Date -f yyyy-MM-dd).csv"

Το OptiRoutes φορτώνει το αρχείο όπως το φορτώνει σήμερα (με την αυτόματη φόρτωση των Ρυθμίσεων → Φόρτωση παραδόσεων, ή με τη «Φόρτωση αρχείου» του χρήστη).

Λήψη των υπογεγραμμένων POD μιας παράδοσης

curl -H "Authorization: Bearer $OPTIROUTES_KEY" "https://srv2.optiroutes.com/api/v1/pod?date=2026-10-11&order=12345"
# then, for each item:
curl -H "Authorization: Bearer $OPTIROUTES_KEY" -OJ "https://srv2.optiroutes.com/api/v1/files/download?path=pod/2026/10/11/12345_sign_2026_10_11.pdf"

Λήψη της αναφοράς τέλους ημέρας

curl -H "Authorization: Bearer $OPTIROUTES_KEY" "https://srv2.optiroutes.com/api/v1/files?folder=reports/2026/10/"
curl -H "Authorization: Bearer $OPTIROUTES_KEY" -OJ "https://srv2.optiroutes.com/api/v1/files/download?path=reports/2026/10/report_2026_10_11.csv"

Python

import os, datetime, requests

BASE = "https://srv2.optiroutes.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['OPTIROUTES_KEY']}"}

# upload today's orders
day = datetime.date.today().isoformat()
with open("orders.csv", "rb") as f:
    r = requests.put(f"{BASE}/files", params={"path": f"orders_files/{day}.csv"},
                     data=f, headers={**H, "Content-Type": "text/csv"}, timeout=60)
r.raise_for_status()

# download every signed POD of the day
pods = requests.get(f"{BASE}/pod", params={"date": day}, headers=H, timeout=60).json()["items"]
for p in pods:
    if p["kind"] == "signed_pdf":
        data = requests.get(f"{BASE}/files/download", params={"path": p["path"]}, headers=H, timeout=60)
        open(p["name"], "wb").write(data.content)

C# (.NET)

using var http = new HttpClient { BaseAddress = new Uri("https://srv2.optiroutes.com/api/v1/") };
http.DefaultRequestHeaders.Authorization =
    new("Bearer", Environment.GetEnvironmentVariable("OPTIROUTES_KEY"));

// upload today's orders
var day = DateTime.Today.ToString("yyyy-MM-dd");
using var content = new ByteArrayContent(File.ReadAllBytes("orders.csv"));
content.Headers.ContentType = new("text/csv");
(await http.PutAsync($"files?path=orders_files/{day}.csv", content)).EnsureSuccessStatusCode();

// the day's PODs as one ZIP
var zip = await http.GetByteArrayAsync($"pod/archive?date={day}");
File.WriteAllBytes($"pod-{day}.zip", zip);

Node.js

const BASE = 'https://srv2.optiroutes.com/api/v1';
const H = { Authorization: `Bearer ${process.env.OPTIROUTES_KEY}` };
const day = new Date().toISOString().slice(0, 10);

// list and download the day's signed PODs (Node 18+)
const { items } = await (await fetch(`${BASE}/pod?date=${day}`, { headers: H })).json();
for (const p of items.filter((i) => i.kind === 'signed_pdf')) {
  const res = await fetch(`${BASE}/files/download?path=${encodeURIComponent(p.path)}`, { headers: H });
  await require('fs/promises').writeFile(p.name, Buffer.from(await res.arrayBuffer()));
}

Εργασία όπως με το FTP — ένα σενάριο συγχρονισμού φακέλου

Οι ομάδες που δούλευαν με FTP μπορούν να διατηρούν έναν φάκελο στον δικό τους διακομιστή συγχρονισμένο με τον φάκελο της εταιρείας: μια προγραμματισμένη εργασία κατεβάζει τα νέα αρχεία (για παράδειγμα τα POD) και ανεβάζει τα αρχεία που τοποθετείτε σε έναν τοπικό φάκελο. Το σενάριο PowerShell παρακάτω κάνει και τα δύο· εκτελέστε το κάθε λίγα λεπτά από τον Προγραμματιστή εργασιών των Windows (στο Linux χρησιμοποιήστε τις γραμμές curl με cron).

# optiroutes-sync.ps1 — download new PODs, upload what is in .\outbox (run every 5 minutes)
$Base  = 'https://srv2.optiroutes.com/api/v1'
$H     = @{ Authorization = "Bearer $env:OPTIROUTES_KEY" }
$Local = 'C:\OptiRoutes'
New-Item -ItemType Directory -Force "$Local\pod", "$Local\outbox", "$Local\sent" | Out-Null

# 1. today's and yesterday's PODs -> C:\OptiRoutes\pod\YYYY-MM-DD\
foreach ($d in (Get-Date), (Get-Date).AddDays(-1)) {
  $day = $d.ToString('yyyy-MM-dd'); $dir = "$Local\pod\$day"
  New-Item -ItemType Directory -Force $dir | Out-Null
  $list = Invoke-RestMethod -Headers $H -Uri "$Base/pod?date=$day"
  foreach ($f in $list.items) {
    $dest = Join-Path $dir $f.name
    if (-not (Test-Path $dest)) {
      Invoke-WebRequest -Headers $H -OutFile $dest -Uri ("$Base/files/download?path=" + [uri]::EscapeDataString($f.path))
    }
  }
}

# 2. every file in C:\OptiRoutes\outbox -> orders_files/, then moved to C:\OptiRoutes\sent
Get-ChildItem "$Local\outbox" -File | ForEach-Object {
  Invoke-RestMethod -Method Put -Headers $H -InFile $_.FullName -ContentType 'application/octet-stream' `
    -Uri ("$Base/files?path=" + [uri]::EscapeDataString("orders_files/" + $_.Name)) | Out-Null
  Move-Item $_.FullName "$Local\sent\" -Force
}

Μετάβαση μιας εταιρείας από το FTP στο API

Ο διευθυντής κάνει την αλλαγή στις Ρυθμίσεις → API και αρχεία → Πώς μετακινούνται τα αρχεία της εταιρείας: API (συνιστάται). Από εκείνη τη στιγμή δεν αποστέλλεται τίποτα στο FTP της εταιρείας και κάθε αρχείο βρίσκεται αντίθετα στον φάκελο της εταιρείας:

Οι νέες εταιρείες δουλεύουν με το API από την αρχή. Η επιστροφή στο FTP γίνεται με τον ίδιο διακόπτη.

Εταιρείες στον παλιό διακομιστή του OptiRoutes

Μια εταιρεία που εξακολουθεί να εργάζεται με τον παλιό διακομιστή του OptiRoutes (WEB) μπορεί να χρησιμοποιεί το API για τα υπογεγραμμένα POD της: δημιουργήστε ένα κλειδί με το δικαίωμα pod:read και χρησιμοποιήστε τα /api/v1/pod, /api/v1/pod/archive και /api/v1/files/download?path=pod/…. Τα υπόλοιπα αρχεία της συνεχίζουν να μετακινούνται όπως σήμερα, μέχρι η εταιρεία να μεταβεί στον νέο διακομιστή.

Σφάλματα

Ένα σφάλμα απαντά με {"ok": false, "error": "<code>", "message": "<explanation>"}.

Όρια

• 300 αιτήματα ανά λεπτό για κάθε κλειδί.
• 50 MB ανά αρχείο.
• 20 ενεργά κλειδιά ανά εταιρεία.
• Η λίστα ενός φακέλου επιστρέφει έως 5.000 καταχωρίσεις· για περισσότερες, εμφανίστε τους υποφακέλους (για παράδειγμα μία ημέρα POD).

Βοήθεια

Ο διευθυντής της εταιρείας βλέπει κάθε κλειδί, την τελευταία χρήση του και τις τελευταίες κλήσεις στις Ρυθμίσεις → API και αρχεία. Για οτιδήποτε άλλο, επικοινωνήστε με την υποστήριξη του OptiRoutes αναφέροντας τον αριθμό της εταιρείας και την ώρα της κλήσης — μην στέλνετε ποτέ το ίδιο το κλειδί.