API de fichiers OptiRoutes

Présentation

Chaque entreprise dans OptiRoutes dispose de son propre dossier de fichiers privé : les commandes qu’elle charge, les bons de livraison signés (POD) avec leurs photos et leurs signatures, les exports de tournées et les rapports de fin de journée. L’API de fichiers permet à vos systèmes de lire et d’écrire directement dans ce dossier, sans serveur FTP intermédiaire.

• Adresse : https://srv2.optiroutes.com/api/v1 — HTTPS uniquement.
• Accès : une clé d’API que le responsable de l’entreprise crée lui-même dans OptiRoutes, sous Paramètres → API et fichiers. Aucune demande auprès du support OptiRoutes n’est nécessaire.
• Tous les types de fichiers avec lesquels le système travaille aujourd’hui : CSV, JSON, TXT, XLSX/XLS, PDF et images.
• Les réponses sont au format JSON, sauf les téléchargements de fichiers, qui renvoient le fichier lui-même.

Démarrer en 3 étapes

1. Créer une clé. Dans OptiRoutes, le responsable ouvre Paramètres → API et fichiers, clique sur Nouvelle clé, lui donne un nom (par exemple « serveur ERP »), choisit les autorisations et copie la clé. La clé n’est affichée qu’une seule fois.
2. Vérifier la connexion.

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

3. Télécharger les POD signés du jour dans un seul fichier ZIP :

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

Sécurité — à lire attentivement

• Traitez la clé comme un mot de passe. Conservez-la dans un coffre de secrets ou dans une variable d’environnement sur votre serveur. Ne la placez jamais dans une page web, une application mobile, un e-mail, un ticket ou un gestionnaire de versions.
• Principe du moindre privilège. Donnez à chaque système sa propre clé, avec uniquement les autorisations dont il a besoin : pod:read (POD signés uniquement), files:read (lecture de tous les fichiers de l’entreprise), files:write (envoi des commandes et des fichiers de la boîte de dépôt).
• Limitez les adresses. Lorsque votre serveur a une adresse IP fixe, ajoutez-la à la clé (« Adresses autorisées »). Tout appel provenant d’une autre adresse est refusé.
• Expiration et rotation. Une clé peut expirer au bout d’un certain nombre de jours. Pour effectuer une rotation : créez une nouvelle clé, basculez votre système dessus, puis révoquez l’ancienne — sans aucune interruption.
• Révoquez immédiatement une clé susceptible d’avoir fuité : Paramètres → API et fichiers → Révoquer la clé. Elle cesse de fonctionner en moins de 30 secondes.
• Audit. Chaque appel est journalisé (heure, adresse, fichier, réponse) et affiché au responsable sur ce même écran.
• OptiRoutes ne conserve qu’une empreinte (SHA-256) de chaque clé, jamais la clé elle-même. Les connexions se font uniquement en HTTPS (TLS 1.2+).
• Une clé n’accède qu’au dossier de sa propre entreprise. Les fichiers des autres entreprises et les dossiers internes du système sont inaccessibles.

Authentification

Envoyez la clé dans chaque requête, dans l’un de ces en-têtes :

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

Une clé ressemble à opr_2813_… (le numéro de l’entreprise, puis 32 caractères aléatoires).

Le dossier de l’entreprise

Référence

Exemple de réponse d’un listing :

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

Tâches courantes

Envoyer le fichier des commandes du jour

# 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 charge le fichier comme il le fait aujourd’hui (par le chargement automatique de Paramètres → Chargement des livraisons, ou par « Charger un fichier » de l’utilisateur).

Télécharger les POD signés d’une commande

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"

Télécharger le rapport de fin de journée

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

Travailler comme avec FTP — un script de synchronisation de dossier

Les équipes qui travaillaient avec FTP peuvent garder un dossier de leur propre serveur synchronisé avec le dossier de l’entreprise : une tâche planifiée télécharge les nouveaux fichiers (par exemple les POD) et envoie ceux que vous déposez dans un dossier local. Le script PowerShell ci-dessous fait les deux ; exécutez-le toutes les quelques minutes depuis le Planificateur de tâches de Windows (sous Linux, utilisez les lignes curl avec 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
}

Faire passer une entreprise de FTP à l’API

Le responsable bascule dans Paramètres → API et fichiers → Comment circulent les fichiers de l'entreprise : API (recommandé). À partir de ce moment, plus rien n’est envoyé au FTP de l’entreprise, et chaque fichier se trouve à la place dans le dossier de l’entreprise :

Les nouvelles entreprises travaillent avec l’API dès le départ. Le retour à FTP se fait avec le même commutateur.

Entreprises sur l’ancien serveur OptiRoutes

Une entreprise qui travaille encore avec l’ancien serveur OptiRoutes (WEB) peut utiliser l’API pour ses POD signés : créez une clé avec l’autorisation pod:read et utilisez /api/v1/pod, /api/v1/pod/archive et /api/v1/files/download?path=pod/…. Ses autres fichiers continuent de circuler comme aujourd’hui, jusqu’à ce que l’entreprise passe au nouveau serveur.

Erreurs

Une erreur renvoie {"ok": false, "error": "<code>", "message": "<explanation>"}.

Limites

• 300 requêtes par minute et par clé.
• 50 Mo par fichier.
• 20 clés actives par entreprise.
• Le listing d’un dossier renvoie jusqu’à 5 000 entrées ; pour en obtenir davantage, listez les sous-dossiers (par exemple une journée de POD).

Aide

Le responsable de l’entreprise voit chaque clé, sa dernière utilisation et les derniers appels dans Paramètres → API et fichiers. Pour tout autre besoin, contactez le support OptiRoutes en indiquant le numéro de l’entreprise et l’heure de l’appel — n’envoyez jamais la clé elle-même.