OptiRoutes Files API

Mi ez?

Az OptiRoutesban minden cégnek saját, privát fájlmappája van: az általa betöltött rendelések, az aláírt szállítólevelek (POD) a fotóikkal és aláírásaikkal, az útvonal-exportok és a napzárási jelentések. A Files API lehetővé teszi, hogy az Ön rendszerei közvetlenül olvassák és írják ezt a mappát, köztes FTP-szerver nélkül.

• Cím: https://srv2.optiroutes.com/api/v1 — csak HTTPS.
• Hozzáférés: egy API-kulcs, amelyet a cég vezetője hoz létre az OptiRoutesban, a Beállítások → API és fájlok menüpontban. Nem kell az OptiRoutes ügyfélszolgálatához fordulni.
• Minden fájltípus, amellyel a rendszer ma dolgozik: CSV, JSON, TXT, XLSX/XLS, PDF és képek.
• A válaszok JSON formátumúak, kivéve a fájlletöltéseket, amelyek magát a fájlt adják vissza.

Kezdés 3 lépésben

1. Hozzon létre egy kulcsot. Az OptiRoutesban a vezető megnyitja a Beállítások → API és fájlok menüpontot, az Új kulcs gombra kattint, nevet ad neki (például „ERP-szerver”), kiválasztja a jogosultságokat, és kimásolja a kulcsot. A kulcs csak egyszer jelenik meg.
2. Ellenőrizze a kapcsolatot.

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

3. Töltse le a mai aláírt POD-okat egyetlen ZIP-fájlként:

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

Biztonság — kérjük, olvassa el

• Kezelje a kulcsot jelszóként. Tárolja titkos tárolóban vagy környezeti változóban a szerverén. Soha ne tegye weboldalba, mobilalkalmazásba, e-mailbe, hibajegybe vagy verziókezelőbe.
• Legkisebb jogosultság. Minden rendszernek adjon saját kulcsot, csak a szükséges jogosultságokkal: pod:read (csak aláírt POD-ok), files:read (a cég összes fájljának olvasása), files:write (rendelések és beérkező fájlok feltöltése).
• Korlátozza a címeket. Ha a szerverének fix IP-címe van, adja hozzá a kulcshoz („Engedélyezett címek”). Bármely más címről érkező hívást a rendszer elutasít.
• Lejárat és csere. A kulcs megadott számú nap után lejárhat. Cseréhez: hozzon létre új kulcsot, állítsa át rá a rendszerét, majd vonja vissza a régit — így nincs leállás.
• Azonnal vonja vissza azt a kulcsot, amely kiszivároghatott: Beállítások → API és fájlok → Visszavonás. 30 másodpercen belül megszűnik működni.
• Naplózás. Minden hívás naplózásra kerül (idő, cím, fájl, válasz), és ugyanazon a képernyőn megjelenik a vezetőnek.
• Az OptiRoutes minden kulcsnak csak az ujjlenyomatát (SHA-256) tárolja, magát a kulcsot soha. A kapcsolatok kizárólag HTTPS-en (TLS 1.2+) futnak.
• Egy kulcs csak a saját cégének mappáját éri el. Más cégek fájljai és a rendszer belső mappái soha nem érhetők el.

Hitelesítés

Minden kérésben küldje el a kulcsot, az alábbi fejlécek egyikében:

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

Egy kulcs így néz ki: opr_2813_… (a cégszám, majd 32 véletlenszerű karakter).

A cég mappája

Referencia

Példaválasz egy listázásra:

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

Gyakori feladatok

A mai rendelési fájl feltöltése

# 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"

Az OptiRoutes ugyanúgy tölti be a fájlt, mint ma (a Beállítások → Betöltés automatikus betöltésével vagy a felhasználó „Fájl betöltése” műveletével).

Egy rendelés aláírt POD-jainak letöltése

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"

A napzárási jelentés letöltése

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

Munka az FTP-hez hasonlóan — mappaszinkronizáló szkript

Az FTP-vel dolgozó csapatok szinkronban tarthatnak egy mappát a saját szerverükön a cég mappájával: egy ütemezett feladat letölti az új fájlokat (például a POD-okat), és feltölti azokat a fájlokat, amelyeket egy helyi mappába tesz. Az alábbi PowerShell-szkript mindkettőt elvégzi; futtassa néhány percenként a Windows Feladatütemezőből (Linuxon használja a curl-sorokat crontabbal).

# 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
}

Egy cég átállítása FTP-ről az API-ra

A vezető a Beállítások → API és fájlok → A fájlok mozgatása: API menüpontban vált. Ettől a pillanattól semmi sem kerül a cég FTP-jére, és minden fájl helyette a cég mappájában van:

Az új cégek kezdettől az API-val dolgoznak. Az FTP-re való visszaváltás ugyanezzel a kapcsolóval történik.

A régi OptiRoutes-szerveren lévő cégek

Az a cég, amely még a régi OptiRoutes-szerverrel (WEB) dolgozik, az aláírt POD-jaihoz használhatja az API-t: hozzon létre egy pod:read jogosultságú kulcsot, és használja a /api/v1/pod, a /api/v1/pod/archive és a /api/v1/files/download?path=pod/… hívást. A többi fájlja továbbra is úgy mozog, mint ma, amíg a cég át nem költözik az új szerverre.

Hibák

Hiba esetén a válasz: {"ok": false, "error": "<code>", "message": "<explanation>"}.

Korlátok

• Kulcsonként percenként 300 kérés.
• Fájlonként 50 MB.
• Cégenként 20 aktív kulcs.
• Egy mappalistázás legfeljebb 5000 bejegyzést ad vissza; többhöz listázza az almappákat (például egy nap POD-jait).

Segítség

A cég vezetője a Beállítások → API és fájlok menüpontban látja az összes kulcsot, azok utolsó használatát és a legutóbbi hívásokat. Minden más esetben forduljon az OptiRoutes ügyfélszolgálatához a cégszámmal és a hívás időpontjával — magát a kulcsot soha ne küldje el.