API dei file di OptiRoutes

Che cos'è

Ogni azienda in OptiRoutes ha una propria cartella privata di file: gli ordini che carica, le bolle di consegna firmate (POD) con le relative foto e firme, le esportazioni dei percorsi e i report di fine giornata. L'API dei file permette ai tuoi sistemi di leggere e scrivere direttamente in quella cartella, senza un server FTP nel mezzo.

• Indirizzo: https://srv2.optiroutes.com/api/v1 — solo HTTPS.
• Accesso: una chiave API che il manager dell'azienda crea in OptiRoutes, in Impostazioni → API e file. Non serve alcuna richiesta al supporto di OptiRoutes.
• Tutti i tipi di file con cui il sistema lavora oggi: CSV, JSON, TXT, XLSX/XLS, PDF e immagini.
• Le risposte sono in JSON, tranne i download dei file, che restituiscono il file stesso.

Inizia in 3 passaggi

1. Crea una chiave. In OptiRoutes il manager apre Impostazioni → API e file, fa clic su Nuova chiave, le assegna un nome (ad esempio «server ERP»), sceglie i permessi e copia la chiave. La chiave viene mostrata una sola volta.
2. Verifica la connessione.

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

3. Scarica i POD firmati di oggi in un unico file ZIP:

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

Sicurezza — da leggere con attenzione

• Tratta la chiave come una password. Conservala in un archivio di segreti o in una variabile d'ambiente sul tuo server. Non inserirla mai in una pagina web, in un'app mobile, in un'e-mail, in un ticket o nel controllo di versione.
• Privilegio minimo. Assegna a ogni sistema una chiave propria, con i soli permessi di cui ha bisogno: pod:read (solo POD firmati), files:read (lettura di tutti i file dell'azienda), files:write (caricamento di ordini e file nella casella di ingresso).
• Limita gli indirizzi. Se il tuo server ha un indirizzo IP fisso, aggiungilo alla chiave («Indirizzi consentiti»). Una chiamata da qualsiasi altro indirizzo viene rifiutata.
• Scadenza e rotazione. Una chiave può scadere dopo un certo numero di giorni. Per la rotazione: crea una nuova chiave, passa il tuo sistema alla nuova chiave e poi revoca quella vecchia — senza alcuna interruzione.
• Revoca subito una chiave che potrebbe essere stata divulgata: Impostazioni → API e file → Revoca la chiave. Smette di funzionare entro 30 secondi.
• Audit. Ogni chiamata viene registrata (ora, indirizzo, file, risposta) e mostrata al manager nella stessa schermata.
• OptiRoutes conserva solo un'impronta (SHA-256) di ciascuna chiave, mai la chiave stessa. Le connessioni sono solo HTTPS (TLS 1.2+).
• Una chiave raggiunge solo la cartella della propria azienda. I file delle altre aziende e le cartelle interne del sistema non sono mai raggiungibili.

Autenticazione

Invia la chiave in ogni richiesta, in una di queste intestazioni:

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

Una chiave ha questo aspetto: opr_2813_… (il numero dell'azienda, seguito da 32 caratteri casuali).

La cartella dell'azienda

Riferimento

Esempio di risposta di un elenco:

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

Operazioni comuni

Caricare il file degli ordini di oggi

# 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 carica il file come lo carica oggi (con il caricamento automatico di Impostazioni → Caricamento, oppure con «Carica file» dell'utente).

Scaricare i POD firmati di un ordine

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"

Scaricare il report di fine giornata

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

Lavorare come con FTP — uno script di sincronizzazione della cartella

I team che lavoravano con FTP possono mantenere una cartella sul proprio server sincronizzata con la cartella dell'azienda: un'attività pianificata scarica i nuovi file (ad esempio i POD) e carica i file che depositi in una cartella locale. Lo script PowerShell qui sotto fa entrambe le cose; eseguilo ogni pochi minuti dall'Utilità di pianificazione di Windows (su Linux usa le righe curl con 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
}

Passare un'azienda da FTP all'API

Il manager passa all'API in Impostazioni → API e file → Come si spostano i file dell'azienda: API (consigliato). Da quel momento non viene inviato più nulla all'FTP dell'azienda, e ogni file si trova invece nella cartella dell'azienda:

Le nuove aziende lavorano con l'API fin dall'inizio. Tornare a FTP si fa con lo stesso interruttore.

Aziende sul vecchio server di OptiRoutes

Un'azienda che lavora ancora con il vecchio server di OptiRoutes (WEB) può usare l'API per i propri POD firmati: crea una chiave con il permesso pod:read e usa /api/v1/pod, /api/v1/pod/archive e /api/v1/files/download?path=pod/…. Gli altri suoi file continuano a muoversi come oggi, finché l'azienda non passa al nuovo server.

Errori

Un errore risponde con {"ok": false, "error": "<code>", "message": "<explanation>"}.

Limiti

• 300 richieste al minuto per chiave.
• 50 MB per file.
• 20 chiavi attive per azienda.
• L'elenco di una cartella restituisce fino a 5.000 voci; per averne di più, elenca le sottocartelle (ad esempio un giorno di POD).

Assistenza

Il manager dell'azienda vede ogni chiave, il suo ultimo utilizzo e le ultime chiamate in Impostazioni → API e file. Per qualsiasi altra necessità, contatta il supporto di OptiRoutes indicando il numero dell'azienda e l'ora della chiamata — non inviare mai la chiave stessa.