OptiRoutes Datei-API

Was es ist

Jedes Unternehmen in OptiRoutes hat seinen eigenen privaten Dateiordner: die geladenen Lieferungen, die unterschriebenen Lieferscheine (POD) mit Fotos und Unterschriften, die Routenexporte und die Tagesabschlussberichte. Über die Datei-API können Ihre Systeme diesen Ordner direkt lesen und beschreiben, ganz ohne FTP-Server dazwischen.

• Adresse: https://srv2.optiroutes.com/api/v1 — ausschließlich HTTPS.
• Zugriff: ein API-Schlüssel, den der Manager des Unternehmens selbst in OptiRoutes unter Einstellungen → API und Dateien erstellt. Eine Anfrage an den OptiRoutes-Support ist nicht nötig.
• Alle Dateitypen, mit denen das System heute arbeitet: CSV, JSON, TXT, XLSX/XLS, PDF und Bilder.
• Antworten erfolgen als JSON, mit Ausnahme von Datei-Downloads, die die Datei selbst zurückgeben.

In 3 Schritten starten

1. Schlüssel erstellen. In OptiRoutes öffnet der Manager Einstellungen → API und Dateien, klickt auf Neuer Schlüssel, vergibt einen Namen (zum Beispiel „ERP-Server“), wählt die Berechtigungen und kopiert den Schlüssel. Der Schlüssel wird nur einmal angezeigt.
2. Verbindung prüfen.

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

3. Die unterschriebenen PODs von heute laden, als eine ZIP-Datei:

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

Sicherheit — bitte lesen

• Behandeln Sie den Schlüssel wie ein Passwort. Bewahren Sie ihn in einem Secret-Speicher oder in einer Umgebungsvariablen auf Ihrem Server auf. Legen Sie ihn niemals auf einer Webseite, in einer mobilen App, in einer E-Mail, in einem Ticket oder in der Versionsverwaltung ab.
• Minimale Berechtigungen. Geben Sie jedem System einen eigenen Schlüssel mit genau den Berechtigungen, die es braucht: pod:read (nur unterschriebene PODs), files:read (alle Dateien des Unternehmens lesen), files:write (Lieferungen und Dateien für den Posteingang hochladen).
• Adressen einschränken. Hat Ihr Server eine feste IP-Adresse, tragen Sie sie im Schlüssel ein („Zulässige Adressen“). Ein Aufruf von jeder anderen Adresse wird abgelehnt.
• Ablauf und Austausch. Ein Schlüssel kann nach einer bestimmten Anzahl von Tagen ablaufen. So tauschen Sie ihn aus: neuen Schlüssel erstellen, Ihr System darauf umstellen, dann den alten widerrufen — ganz ohne Ausfallzeit.
• Sofort widerrufen: einen Schlüssel, der womöglich offengelegt wurde — Einstellungen → API und Dateien → Schlüssel widerrufen. Er funktioniert danach innerhalb von 30 Sekunden nicht mehr.
• Protokollierung. Jeder Aufruf wird protokolliert (Zeit, Adresse, Datei, Antwort) und dem Manager auf demselben Bildschirm angezeigt.
• OptiRoutes speichert von jedem Schlüssel nur einen Fingerabdruck (SHA-256), niemals den Schlüssel selbst. Verbindungen sind ausschließlich über HTTPS (TLS 1.2+) möglich.
• Ein Schlüssel erreicht nur den Ordner des eigenen Unternehmens. Dateien anderer Unternehmen und die internen Ordner des Systems sind nie erreichbar.

Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage in einem dieser Header:

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

Ein Schlüssel sieht so aus: opr_2813_… (die Unternehmensnummer, danach 32 Zufallszeichen).

Der Unternehmensordner

Referenz

Beispielantwort einer Auflistung:

{
  "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" }
  ]
}

Häufige Aufgaben

Die Lieferungsdatei von heute hochladen

# 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 lädt die Datei so, wie es sie heute lädt (über das automatische Laden unter Einstellungen → Lieferungen laden oder über „Datei laden“ des Benutzers).

Die unterschriebenen PODs einer Lieferung herunterladen

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"

Den Tagesabschlussbericht herunterladen

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()));
}

Wie bei FTP arbeiten — ein Skript zur Ordnersynchronisierung

Teams, die bisher mit FTP gearbeitet haben, können einen Ordner auf dem eigenen Server mit dem Unternehmensordner synchron halten: Eine geplante Aufgabe lädt neue Dateien herunter (zum Beispiel die PODs) und lädt die Dateien hoch, die Sie in einem lokalen Ordner ablegen. Das PowerShell-Skript unten erledigt beides; führen Sie es alle paar Minuten über die Windows-Aufgabenplanung aus (unter Linux verwenden Sie die curl-Zeilen mit 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
}

Ein Unternehmen von FTP auf die API umstellen

Der Manager stellt unter Einstellungen → API und Dateien → Wie die Dateien des Unternehmens übertragen werden: API (empfohlen) um. Ab diesem Moment wird nichts mehr an den FTP-Server des Unternehmens gesendet, und jede Datei liegt stattdessen im Unternehmensordner:

Neue Unternehmen arbeiten von Anfang an mit der API. Die Rückkehr zu FTP erfolgt über denselben Schalter.

Unternehmen auf dem alten OptiRoutes-Server

Ein Unternehmen, das noch mit dem alten OptiRoutes-Server (WEB) arbeitet, kann die API für seine unterschriebenen PODs nutzen: Erstellen Sie einen Schlüssel mit der Berechtigung pod:read und verwenden Sie /api/v1/pod, /api/v1/pod/archive und /api/v1/files/download?path=pod/…. Seine übrigen Dateien werden weiterhin wie bisher übertragen, bis das Unternehmen auf den neuen Server umzieht.

Fehler

Ein Fehler wird beantwortet mit {"ok": false, "error": "<code>", "message": "<explanation>"}.

Limits

• 300 Anfragen pro Minute und Schlüssel.
• 50 MB pro Datei.
• 20 aktive Schlüssel pro Unternehmen.
• Eine Ordnerauflistung liefert bis zu 5.000 Einträge; für mehr listen Sie Unterordner auf (zum Beispiel einen Tag PODs).

Hilfe

Der Manager des Unternehmens sieht unter Einstellungen → API und Dateien jeden Schlüssel, seine letzte Verwendung und die letzten Aufrufe. Bei allen anderen Fragen wenden Sie sich mit der Unternehmensnummer und der Uhrzeit des Aufrufs an den OptiRoutes-Support — senden Sie niemals den Schlüssel selbst.