OptiRoutes Files API

Apa itu

Setiap perusahaan di OptiRoutes memiliki folder file pribadinya sendiri: pesanan yang dimuatnya, surat jalan yang ditandatangani (POD) beserta foto dan tanda tangannya, ekspor rute, dan laporan akhir hari. Files API memungkinkan sistem Anda membaca dan menulis folder tersebut secara langsung, tanpa server FTP di antaranya.

• Alamat: https://srv2.optiroutes.com/api/v1 — hanya HTTPS.
• Akses: kunci API yang dibuat oleh manajer perusahaan di OptiRoutes, di Pengaturan → API & file. Tidak perlu permintaan ke dukungan OptiRoutes.
• Setiap jenis file yang digunakan sistem saat ini: CSV, JSON, TXT, XLSX/XLS, PDF, dan gambar.
• Jawaban berupa JSON, kecuali unduhan file, yang mengembalikan file itu sendiri.

Mulai dalam 3 langkah

1. Buat kunci. Di OptiRoutes, manajer membuka Pengaturan → API & file, mengklik Kunci baru, memberinya nama (misalnya "server ERP"), memilih izin, dan menyalin kunci. Kunci hanya ditampilkan sekali.
2. Periksa koneksi.

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

3. Unduh POD yang ditandatangani hari ini sebagai satu ZIP:

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

Keamanan — harap dibaca

• Perlakukan kunci seperti kata sandi. Simpan di penyimpanan rahasia atau variabel lingkungan di server Anda. Jangan pernah menaruhnya di halaman web, aplikasi seluler, email, tiket, atau kontrol sumber.
• Hak akses minimum. Berikan setiap sistem kuncinya sendiri dengan hanya izin yang dibutuhkannya: pod:read (hanya POD yang ditandatangani), files:read (membaca setiap file perusahaan), files:write (mengunggah pesanan dan file kotak masuk).
• Batasi alamat. Jika server Anda memiliki alamat IP tetap, tambahkan ke kunci ("Alamat yang diizinkan"). Panggilan dari alamat lain mana pun akan ditolak.
• Masa berlaku dan rotasi. Kunci dapat kedaluwarsa setelah sejumlah hari. Untuk merotasi: buat kunci baru, alihkan sistem Anda ke kunci tersebut, lalu cabut kunci lama — tanpa waktu henti.
• Segera cabut kunci yang mungkin bocor: Pengaturan → API & file → Cabut. Kunci berhenti berfungsi dalam 30 detik.
• Audit. Setiap panggilan dicatat (waktu, alamat, file, jawaban) dan ditampilkan kepada manajer di layar yang sama.
• OptiRoutes hanya menyimpan sidik jari (SHA-256) dari setiap kunci, tidak pernah kunci itu sendiri. Koneksi hanya melalui HTTPS (TLS 1.2+).
• Kunci hanya dapat mengakses folder perusahaannya sendiri. File perusahaan lain dan folder internal sistem tidak pernah dapat diakses.

Autentikasi

Kirim kunci di setiap permintaan, di salah satu header berikut:

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

Kunci terlihat seperti opr_2813_… (nomor perusahaan, lalu 32 karakter acak).

Folder perusahaan

Referensi

Contoh jawaban daftar:

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

Tugas umum

Unggah file pesanan hari ini

# 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 memuat file seperti cara memuatnya saat ini (pemuatan otomatis di Pengaturan → Pemuatan, atau "Muat file" oleh pengguna).

Unduh POD yang ditandatangani untuk satu pesanan

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"

Unduh laporan akhir hari

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

Bekerja seperti FTP — skrip sinkronisasi folder

Tim yang biasa bekerja dengan FTP dapat menjaga folder di server mereka sendiri tetap sinkron dengan folder perusahaan: tugas terjadwal mengunduh file baru (misalnya POD) dan mengunggah file yang Anda letakkan di folder lokal. Skrip PowerShell di bawah melakukan keduanya; jalankan setiap beberapa menit dari Windows Task Scheduler (di Linux gunakan baris curl dengan 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
}

Memindahkan perusahaan dari FTP ke API

Manajer beralih di Pengaturan → API & file → File berpindah melalui: API. Sejak saat itu tidak ada yang dikirim ke FTP perusahaan, dan setiap file berada di folder perusahaan sebagai gantinya:

Perusahaan baru bekerja dengan API sejak awal. Kembali ke FTP menggunakan sakelar yang sama.

Perusahaan di server OptiRoutes lama

Perusahaan yang masih bekerja dengan server OptiRoutes lama (WEB) dapat menggunakan API untuk POD yang ditandatangani: buat kunci dengan izin pod:read dan gunakan /api/v1/pod, /api/v1/pod/archive, serta /api/v1/files/download?path=pod/…. File lainnya tetap berpindah seperti saat ini, sampai perusahaan pindah ke server baru.

Kesalahan

Kesalahan dijawab dengan {"ok": false, "error": "<code>", "message": "<explanation>"}.

Batasan

• 300 permintaan per menit per kunci.
• 50 MB per file.
• 20 kunci aktif per perusahaan.
• Daftar folder mengembalikan hingga 5.000 entri; untuk lebih banyak, buat daftar subfolder (misalnya POD satu hari).

Bantuan

Manajer perusahaan melihat setiap kunci, penggunaan terakhirnya, dan panggilan terakhir di Pengaturan → API & file. Untuk hal lainnya, hubungi dukungan OptiRoutes dengan menyebutkan nomor perusahaan dan waktu panggilan — jangan pernah mengirimkan kunci itu sendiri.