OptiRoutes Files API

यह क्या है

OptiRoutes में हर कंपनी का फ़ाइलों का अपना निजी फ़ोल्डर होता है: वह जो डिलीवरी लोड करती है, फ़ोटो और हस्ताक्षर सहित हस्ताक्षरित डिलीवरी नोट (POD), रूट एक्सपोर्ट और दिन के अंत की रिपोर्ट। Files API आपके सिस्टम को बीच में किसी FTP सर्वर के बिना उस फ़ोल्डर को सीधे पढ़ने और उसमें लिखने देता है।

• पता: https://srv2.optiroutes.com/api/v1 — केवल HTTPS।
• एक्सेस: एक API कुंजी, जिसे कंपनी का मैनेजर OptiRoutes में सेटिंग्स → API और फ़ाइलें में बनाता है। OptiRoutes सहायता से अनुरोध करने की ज़रूरत नहीं है।
• हर फ़ाइल प्रकार जिसके साथ सिस्टम आज काम करता है: CSV, JSON, TXT, XLSX/XLS, PDF और चित्र।
• जवाब JSON में होते हैं, फ़ाइल डाउनलोड को छोड़कर, जो स्वयं फ़ाइल लौटाते हैं।

3 चरणों में शुरू करें

1. कुंजी बनाएँ। OptiRoutes में मैनेजर सेटिंग्स → API और फ़ाइलें खोलता है, नई कुंजी पर क्लिक करता है, उसे एक नाम देता है (उदाहरण के लिए "ERP सर्वर"), अनुमतियाँ चुनता है और कुंजी कॉपी करता है। कुंजी केवल एक बार दिखाई जाती है।
2. कनेक्शन जाँचें।

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

3. आज के हस्ताक्षरित POD डाउनलोड करें एक ZIP के रूप में:

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

सुरक्षा — कृपया पढ़ें

• कुंजी को पासवर्ड की तरह संभालें। इसे अपने सर्वर पर किसी गुप्त स्टोर या एनवायरनमेंट वेरिएबल में रखें। इसे कभी भी किसी वेब पेज, मोबाइल ऐप, ईमेल, टिकट या सोर्स कंट्रोल में न डालें।
• न्यूनतम अधिकार। हर सिस्टम को उसकी अपनी कुंजी दें, जिसमें केवल वही अनुमतियाँ हों जिनकी उसे ज़रूरत है: 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 फ़ाइल को वैसे ही लोड करता है जैसे आज करता है (सेटिंग्स → लोडिंग का स्वचालित लोडिंग, या उपयोगकर्ता का "फ़ाइल लोड करें")।

एक डिलीवरी के हस्ताक्षरित 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 Task Scheduler से हर कुछ मिनट में चलाएँ (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>"}।

सीमाएँ

• प्रति कुंजी प्रति मिनट 300 अनुरोध।
• प्रति फ़ाइल 50 MB।
• प्रति कंपनी 20 सक्रिय कुंजियाँ।
• फ़ोल्डर सूची अधिकतम 5,000 प्रविष्टियाँ लौटाती है; अधिक के लिए उप-फ़ोल्डर सूचीबद्ध करें (उदाहरण के लिए POD का एक दिन)।

सहायता

कंपनी का मैनेजर सेटिंग्स → API और फ़ाइलें में हर कुंजी, उसका अंतिम उपयोग और अंतिम कॉल देखता है। किसी अन्य बात के लिए, कंपनी नंबर और कॉल के समय के साथ OptiRoutes सहायता से संपर्क करें — कुंजी स्वयं कभी न भेजें।