OptiRoutes Files API

Čo to je

Každá spoločnosť v OptiRoutes má vlastný súkromný priečinok súborov: objednávky, ktoré načítava, podpísané dodacie listy (POD) s ich fotografiami a podpismi, exporty trás a zostavy na konci dňa. Files API umožňuje vašim systémom čítať a zapisovať do tohto priečinka priamo, bez servera FTP medzi tým.

• Adresa: https://srv2.optiroutes.com/api/v1 – len HTTPS.
• Prístup: kľúč API, ktorý vytvorí manažér spoločnosti v OptiRoutes v Nastavenia → API a súbory. Nie je potrebná žiadna žiadosť na podporu OptiRoutes.
• Každý typ súboru, s ktorým systém dnes pracuje: CSV, JSON, TXT, XLSX/XLS, PDF a obrázky.
• Odpovede sú vo formáte JSON, okrem sťahovania súborov, ktoré vracia samotný súbor.

Začnite v 3 krokoch

1. Vytvorte kľúč. V OptiRoutes manažér otvorí Nastavenia → API a súbory, klikne na Nový kľúč, pomenuje ho (napríklad „Server ERP“), vyberie oprávnenia a skopíruje kľúč. Kľúč sa zobrazí len raz.
2. Overte pripojenie.

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

3. Stiahnite dnešné podpísané POD ako jeden ZIP:

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

Zabezpečenie – prečítajte si

• S kľúčom zaobchádzajte ako s heslom. Uchovávajte ho v trezore tajomstiev alebo v premennej prostredia na svojom serveri. Nikdy ho nedávajte na webovú stránku, do mobilnej aplikácie, e-mailu, tiketu ani do správy zdrojového kódu.
• Najnižšie oprávnenia. Dajte každému systému vlastný kľúč len s oprávneniami, ktoré potrebuje: pod:read (len podpísané POD), files:read (čítanie všetkých súborov spoločnosti), files:write (nahrávanie objednávok a súborov do inboxu).
• Obmedzte adresy. Keď má váš server pevnú IP adresu, pridajte ju ku kľúču („Povolené adresy“). Volanie z akejkoľvek inej adresy sa odmietne.
• Platnosť a obmena. Kľúč môže po určitom počte dní vypršať. Obmena: vytvorte nový kľúč, prepnite naň svoj systém a potom starý zrušte – bez výpadku.
• Okamžite zrušte kľúč, ktorý mohol uniknúť: Nastavenia → API a súbory → Zrušiť. Prestane fungovať do 30 sekúnd.
• Audit. Každé volanie sa zaznamená (čas, adresa, súbor, odpoveď) a zobrazí sa manažérovi na tej istej obrazovke.
• OptiRoutes uchováva len odtlačok (SHA-256) každého kľúča, nikdy samotný kľúč. Pripojenia sú len cez HTTPS (TLS 1.2+).
• Kľúč má prístup len do priečinka vlastnej spoločnosti. K súborom iných spoločností a interným priečinkom systému sa nikdy nedostane.

Overenie

Kľúč posielajte v každej požiadavke v jednej z týchto hlavičiek:

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

Kľúč vyzerá ako opr_2813_… (číslo spoločnosti, potom 32 náhodných znakov).

Priečinok spoločnosti

Referencia

Príklad odpovede výpisu:

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

Bežné úlohy

Nahranie dnešného súboru objednávok

# 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 načíta súbor tak, ako ho načítava dnes (automatické načítanie v Nastavenia → Načítanie alebo „Načítať súbor“ používateľa).

Stiahnutie podpísaných POD jednej objednávky

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"

Stiahnutie zostavy na konci dňa

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

Práca ako s FTP – skript na synchronizáciu priečinka

Tímy, ktoré pracovali s FTP, môžu udržiavať priečinok na vlastnom serveri synchronizovaný s priečinkom spoločnosti: naplánovaná úloha sťahuje nové súbory (napríklad POD) a nahráva súbory, ktoré vložíte do lokálneho priečinka. Skript PowerShell nižšie robí oboje; spúšťajte ho každých niekoľko minút z Plánovača úloh Windows (v Linuxe použite riadky curl s 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
}

Presun spoločnosti z FTP na API

Manažér prepne v Nastavenia → API a súbory → Súbory sa presúvajú cez: API. Od tej chvíle sa na FTP spoločnosti nič neposiela a každý súbor je namiesto toho v priečinku spoločnosti:

Nové spoločnosti pracujú s API od začiatku. Návrat na FTP je ten istý prepínač.

Spoločnosti na starom serveri OptiRoutes

Spoločnosť, ktorá ešte pracuje so starým serverom OptiRoutes (WEB), môže použiť API pre svoje podpísané POD: vytvorte kľúč s oprávnením pod:read a použite /api/v1/pod, /api/v1/pod/archive a /api/v1/files/download?path=pod/…. Jej ostatné súbory sa naďalej presúvajú ako dnes, kým spoločnosť neprejde na nový server.

Chyby

Chyba vráti {"ok": false, "error": "<code>", "message": "<explanation>"}.

Limity

• 300 požiadaviek za minútu na kľúč.
• 50 MB na súbor.
• 20 aktívnych kľúčov na spoločnosť.
• Výpis priečinka vráti najviac 5 000 položiek; pre viac vypíšte podpriečinky (napríklad jeden deň POD).

Pomoc

Manažér spoločnosti vidí každý kľúč, jeho posledné použitie a posledné volania v Nastavenia → API a súbory. Pri čomkoľvek inom kontaktujte podporu OptiRoutes s číslom spoločnosti a časom volania – nikdy neposielajte samotný kľúč.