OptiRoutes Files API

Wat het is

Elk bedrijf in OptiRoutes heeft een eigen, privémap met bestanden: de leveringen die het laadt, de ondertekende afleverbonnen (POD) met hun foto's en handtekeningen, de route-exports en de rapporten aan het einde van de dag. Met de Files API kunnen uw systemen die map rechtstreeks lezen en beschrijven, zonder FTP-server ertussen.

• Adres: https://srv2.optiroutes.com/api/v1 — alleen HTTPS.
• Toegang: een API-sleutel die de manager van het bedrijf in OptiRoutes aanmaakt, in Instellingen → API en bestanden. Er is geen aanvraag bij support van OptiRoutes nodig.
• Elk bestandstype waarmee het systeem nu werkt: CSV, JSON, TXT, XLSX/XLS, PDF en afbeeldingen.
• Antwoorden zijn JSON, behalve bij het downloaden van bestanden, die het bestand zelf teruggeven.

Beginnen in 3 stappen

1. Maak een sleutel aan. In OptiRoutes opent de manager Instellingen → API en bestanden, klikt op Nieuwe sleutel, geeft deze een naam (bijvoorbeeld "ERP-server"), kiest de rechten en kopieert de sleutel. De sleutel wordt één keer getoond.
2. Controleer de verbinding.

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

3. Download de ondertekende POD's van vandaag als één ZIP:

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

Beveiliging — lees dit

• Behandel de sleutel als een wachtwoord. Bewaar deze in een geheimenkluis of een omgevingsvariabele op uw server. Zet de sleutel nooit in een webpagina, een mobiele app, een e-mail, een ticket of broncodebeheer.
• Minimale rechten. Geef elk systeem een eigen sleutel met alleen de rechten die het nodig heeft: pod:read (alleen ondertekende POD's), files:read (elk bestand van het bedrijf lezen), files:write (leveringen en bestanden voor de inbox uploaden).
• Beperk de adressen. Als uw server een vast IP-adres heeft, voegt u dit aan de sleutel toe ("Toegestane adressen"). Een aanroep vanaf een ander adres wordt geweigerd.
• Vervaldatum en vervanging. Een sleutel kan na een aantal dagen verlopen. Om te vervangen: maak een nieuwe sleutel aan, zet uw systeem over op die sleutel en trek daarna de oude in — zonder onderbreking.
• Trek direct in een sleutel die mogelijk is gelekt: Instellingen → API en bestanden → Intrekken. Deze werkt binnen 30 seconden niet meer.
• Controle. Elke aanroep wordt vastgelegd (tijd, adres, bestand, antwoord) en aan de manager getoond in hetzelfde scherm.
• OptiRoutes bewaart alleen een vingerafdruk (SHA-256) van elke sleutel, nooit de sleutel zelf. Verbindingen gaan alleen via HTTPS (TLS 1.2+).
• Een sleutel bereikt alleen de map van het eigen bedrijf. Bestanden van andere bedrijven en de interne mappen van het systeem zijn nooit bereikbaar.

Authenticatie

Stuur de sleutel bij elke aanvraag mee, in een van deze headers:

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

Een sleutel ziet eruit als opr_2813_… (het bedrijfsnummer, gevolgd door 32 willekeurige tekens).

De bedrijfsmap

Naslag

Voorbeeldantwoord van een overzicht:

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

Veelvoorkomende taken

Het leveringsbestand van vandaag uploaden

# 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 laadt het bestand zoals het dat nu doet (het automatisch laden van Instellingen → Laden, of "Bestand laden" door de gebruiker).

De ondertekende POD's van één levering downloaden

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"

Het rapport van het einde van de dag downloaden

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

Werken zoals met FTP — een script om mappen te synchroniseren

Teams die met FTP werkten, kunnen een map op hun eigen server gesynchroniseerd houden met de bedrijfsmap: een geplande taak downloadt nieuwe bestanden (bijvoorbeeld de POD's) en uploadt de bestanden die u in een lokale map zet. Het PowerShell-script hieronder doet beide; voer het om de paar minuten uit via Windows Taakplanner (gebruik op Linux de curl-regels met 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
}

Een bedrijf overzetten van FTP naar de API

De manager schakelt over in Instellingen → API en bestanden → Bestanden uitwisselen via: API. Vanaf dat moment wordt er niets meer naar de FTP van het bedrijf gestuurd en staat elk bestand in plaats daarvan in de bedrijfsmap:

Nieuwe bedrijven werken vanaf het begin met de API. Terugschakelen naar FTP gaat met dezelfde schakelaar.

Bedrijven op de oude OptiRoutes-server

Een bedrijf dat nog met de oude OptiRoutes-server (WEB) werkt, kan de API gebruiken voor de ondertekende POD's: maak een sleutel aan met het recht pod:read en gebruik /api/v1/pod, /api/v1/pod/archive en /api/v1/files/download?path=pod/…. De andere bestanden worden uitgewisseld zoals nu, totdat het bedrijf naar de nieuwe server overstapt.

Fouten

Een fout geeft {"ok": false, "error": "<code>", "message": "<explanation>"} terug.

Limieten

• 300 aanvragen per minuut per sleutel.
• 50 MB per bestand.
• 20 actieve sleutels per bedrijf.
• Een mapoverzicht geeft maximaal 5.000 items terug; vraag submappen op (bijvoorbeeld één dag aan POD's) voor meer.

Hulp

De manager van het bedrijf ziet elke sleutel, het laatste gebruik en de laatste aanroepen in Instellingen → API en bestanden. Neem voor al het andere contact op met support van OptiRoutes, met het bedrijfsnummer en het tijdstip van de aanroep — stuur nooit de sleutel zelf.