OptiRoutes ファイルAPI

概要

OptiRoutesの各社には、専用の非公開ファイルフォルダーがあります。読み込んだ配送ファイル、写真と署名付きの署名済み納品書（POD）、ルートのエクスポート、日次締めレポートが保存されます。ファイルAPIを使うと、FTPサーバーを介さずに、お客様のシステムからこのフォルダーを直接読み書きできます。

• アドレス：https://srv2.optiroutes.com/api/v1（HTTPSのみ）。
• アクセス：会社のマネージャーがOptiRoutesの設定 → APIとファイルで自分で作成するAPIキーを使います。OptiRoutesサポートへの申請は不要です。
• すべてのファイル形式に対応しています（現在システムで扱うもの）：CSV、JSON、TXT、XLSX/XLS、PDF、画像。
• レスポンスはJSONです。ただし、ファイルのダウンロードではファイルそのものが返されます。

3ステップで開始

1. キーを作成します。OptiRoutesで、マネージャーが設定 → APIとファイルを開き、新規キーをクリックして名前（例：「ERPサーバー」）を付け、権限を選択してキーをコピーします。キーが表示されるのは1回のみです。
2. 接続を確認します。

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

3. 本日の署名済みPODを1つのZIPファイルとしてダウンロードします：

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

セキュリティ — 必ずお読みください

• キーはパスワードと同様に扱ってください。シークレットストア、またはサーバー上の環境変数に保管します。Webページ、モバイルアプリ、メール、チケット、ソース管理には決して記載しないでください。
• 最小権限。システムごとに専用のキーを発行し、必要な権限のみを付与します：pod:read（署名済みPODのみ）、files:read（会社のすべてのファイルの読み取り）、files:write（配送ファイルと受信ボックスのファイルのアップロード）。
• アドレスを制限します。サーバーに固定IPアドレスがある場合は、キーに追加してください（「許可するアドレス」）。それ以外のアドレスからの呼び出しは拒否されます。
• 有効期限とローテーション。キーには、一定の日数で期限が切れるよう設定できます。ローテーションの手順：新しいキーを作成し、システムを新しいキーに切り替えてから、古いキーを無効化します。ダウンタイムは発生しません。
• 漏えいの可能性があるキーはただちに無効化してください：設定 → APIとファイル → キーを無効化。30秒以内に使用できなくなります。
• 監査。すべての呼び出しが記録され（時刻、アドレス、ファイル、応答）、同じ画面でマネージャーに表示されます。
• OptiRoutesが保持するのは各キーのフィンガープリント（SHA-256）のみで、キー自体は保持しません。接続はHTTPS（TLS 1.2以上）のみです。
• キーがアクセスできるのは、自社のフォルダーだけです。他社のファイルやシステム内部のフォルダーには、決してアクセスできません。

認証

すべてのリクエストで、次のいずれかのヘッダーにキーを指定します：

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

キーは opr_2813_… の形式です（会社番号に続けて、ランダムな32文字）。

会社のフォルダー

リファレンス

一覧表示のレスポンス例：

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

よくある操作

本日の配送ファイルをアップロードする

# 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は、現在と同じ方法でファイルを読み込みます（設定 → 配送の読み込みの自動読み込み、またはユーザーによる「ファイルの読み込み」）。

1件の配送の署名済み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"

日次締めレポートをダウンロードする

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

FTPのように使う — フォルダー同期スクリプト

これまでFTPを使っていたチームは、自社サーバー上のフォルダーを会社のフォルダーと同期した状態に保てます。スケジュール実行されるタスクが新しいファイル（たとえばPOD）をダウンロードし、ローカルフォルダーに置いたファイルをアップロードします。以下のPowerShellスクリプトは両方を行います。Windowsのタスクスケジューラーで数分おきに実行してください（Linuxではcronでcurlの行を実行します）。

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

会社をFTPからAPIへ移行する

マネージャーが設定 → APIとファイル → 会社のファイルの受け渡し方法：API（推奨）で切り替えます。その時点から、会社のFTPには何も送信されなくなり、すべてのファイルが代わりに会社のフォルダーに保存されます：

新規の会社は、最初からAPIで運用します。FTPに戻す場合も、同じ切り替えで行えます。

旧OptiRoutesサーバーを使用している会社

旧OptiRoutesサーバー（WEB）をまだ使用している会社でも、署名済みPODについてはAPIを利用できます。pod:read 権限を持つキーを作成し、/api/v1/pod、/api/v1/pod/archive、/api/v1/files/download?path=pod/… を使用してください。その他のファイルは、新しいサーバーに移行するまで、現在と同じ方法でやり取りされます。

エラー

エラー時は {"ok": false, "error": "<code>", "message": "<explanation>"} が返されます。

制限

• キーごとに1分あたり300リクエスト。
• 1ファイルあたり50 MB。
• 1社あたり有効なキーは20個まで。
• フォルダーの一覧は最大5,000件まで返されます。それ以上は、サブフォルダー（たとえばPODの1日分）を指定して一覧表示してください。

サポート

会社のマネージャーは、設定 → APIとファイルで、すべてのキー、最後の使用日時、最近の呼び出しを確認できます。その他のご質問は、会社番号と呼び出しの時刻を添えてOptiRoutesサポートまでご連絡ください。キー自体は絶対に送信しないでください。