OptiRoutes failų API

Kas tai

Kiekviena OptiRoutes įmonė turi savo privatų failų aplanką: įkeliamus pristatymus, pasirašytus važtaraščius (POD) su jų nuotraukomis ir parašais, maršrutų eksportus ir dienos pabaigos ataskaitas. Failų API leidžia Jūsų sistemoms tiesiogiai skaityti ir rašyti tą aplanką, be jokio tarpinio FTP serverio.

• Adresas: https://srv2.optiroutes.com/api/v1 – tik HTTPS.
• Prieiga: API raktas, kurį įmonės vadovas sukuria OptiRoutes skiltyje Nustatymai → API ir failai. Kreiptis į OptiRoutes pagalbos tarnybą nereikia.
• Visi failų tipai, su kuriais sistema dirba šiandien: CSV, JSON, TXT, XLSX/XLS, PDF ir vaizdai.
• Atsakymai pateikiami JSON formatu, išskyrus failų atsisiuntimus, kurie grąžina patį failą.

Pradžia per 3 žingsnius

1. Sukurkite raktą. OptiRoutes sistemoje vadovas atidaro Nustatymai → API ir failai, spusteli Naujas raktas, suteikia jam pavadinimą (pavyzdžiui, „ERP serveris“), pasirenka teises ir nukopijuoja raktą. Raktas rodomas vieną kartą.
2. Patikrinkite ryšį.

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

3. Atsisiųskite šiandienos pasirašytus POD vienu ZIP failu:

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

Sauga – perskaitykite

• Saugokite raktą kaip slaptažodį. Laikykite jį slaptų duomenų saugykloje arba aplinkos kintamajame savo serveryje. Niekada nedėkite jo į tinklalapį, mobiliąją programėlę, el. laišką, užklausą ar išeities kodo saugyklą.
• Mažiausios teisės. Kiekvienai sistemai suteikite atskirą raktą tik su jai reikalingomis teisėmis: pod:read (tik pasirašyti POD), files:read (skaityti visus įmonės failus), files:write (įkelti pristatymus ir gautųjų failus).
• Apribokite adresus. Kai Jūsų serveris turi fiksuotą IP adresą, pridėkite jį prie rakto („Leidžiami adresai“). Užklausa iš bet kurio kito adreso atmetama.
• Galiojimas ir keitimas. Raktas gali nustoti galioti po tam tikro dienų skaičiaus. Norėdami pakeisti: sukurkite naują raktą, perjunkite į jį savo sistemą, tada atšaukite senąjį – prastovos nėra.
• Iš karto atšaukite raktą, kuris galėjo nutekėti: Nustatymai → API ir failai → Atšaukti. Jis nustoja veikti per 30 sekundžių.
• Auditas. Kiekviena užklausa registruojama (laikas, adresas, failas, atsakymas) ir rodoma vadovui tame pačiame ekrane.
• OptiRoutes saugo tik kiekvieno rakto kontrolinę sumą (SHA-256), niekada paties rakto. Ryšiai – tik HTTPS (TLS 1.2+).
• Raktas pasiekia tik savo įmonės aplanką. Kitų įmonių failų ir vidinių sistemos aplankų pasiekti niekada negalima.

Autentifikavimas

Siųskite raktą kiekvienoje užklausoje vienoje iš šių antraščių:

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

Raktas atrodo taip: opr_2813_… (įmonės kodas, tada 32 atsitiktiniai simboliai).

Įmonės aplankas

Žinynas

Sąrašo atsakymo pavyzdys:

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

Dažnos užduotys

Įkelti šiandienos pristatymų failą

# 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 įkelia failą taip, kaip įkelia šiandien (automatinis įkėlimas skiltyje Nustatymai → Pristatymų įkėlimas arba naudotojo „Įkelti failą“).

Atsisiųsti vieno pristatymo pasirašytus 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"

Atsisiųsti dienos pabaigos ataskaitą

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

Darbas kaip su FTP – aplanko sinchronizavimo scenarijus

Su FTP dirbusios komandos gali savo serveryje laikyti aplanką, sinchronizuojamą su įmonės aplanku: suplanuota užduotis atsisiunčia naujus failus (pavyzdžiui, POD) ir įkelia failus, kuriuos įdedate į vietinį aplanką. Toliau pateiktas PowerShell scenarijus atlieka abu veiksmus; paleiskite jį kas kelias minutes per Windows užduočių planuoklį (Linux sistemoje naudokite curl eilutes su 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
}

Įmonės perkėlimas iš FTP į API

Vadovas perjungia skiltyje Nustatymai → API ir failai → Failai keliauja per: API. Nuo tos akimirkos į įmonės FTP niekas nesiunčiama, o kiekvienas failas yra įmonės aplanke:

Naujos įmonės nuo pat pradžių dirba su API. Grįžtama į FTP tuo pačiu jungikliu.

Įmonės, naudojančios senąjį OptiRoutes serverį

Įmonė, vis dar dirbanti su senuoju OptiRoutes serveriu (WEB), gali naudoti API savo pasirašytiems POD: sukurkite raktą su teise pod:read ir naudokite /api/v1/pod, /api/v1/pod/archive ir /api/v1/files/download?path=pod/…. Kiti jos failai toliau keliauja kaip šiandien, kol įmonė pereis į naująjį serverį.

Klaidos

Klaidos atveju grąžinama {"ok": false, "error": "<code>", "message": "<explanation>"}.

Ribos

• 300 užklausų per minutę vienam raktui.
• 50 MB vienam failui.
• 20 aktyvių raktų vienai įmonei.
• Aplanko sąrašas grąžina iki 5 000 įrašų; norėdami daugiau, išvardykite poaplankius (pavyzdžiui, vienos dienos POD).

Pagalba

Įmonės vadovas mato kiekvieną raktą, paskutinį jo naudojimą ir paskutines užklausas skiltyje Nustatymai → API ir failai. Dėl visų kitų klausimų kreipkitės į OptiRoutes pagalbos tarnybą, nurodydami įmonės kodą ir užklausos laiką – niekada nesiųskite paties rakto.