API за файлове на OptiRoutes

Какво представлява

Всяка компания в OptiRoutes има собствена лична папка с файлове: поръчките, които зарежда, подписаните стокови разписки (POD) със снимките и подписите им, експортите на маршрути и отчетите за края на деня. 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 използвайте редовете с curl с 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
}

Преминаване на компания от FTP към API

Мениджърът превключва в Настройки → API и файлове → Файловете се движат чрез: API. От този момент нищо не се изпраща към FTP на компанията и всеки файл е в папката на компанията:

Новите компании работят с API от самото начало. Връщането към FTP става със същия превключвател.

Компании на стария сървър на OptiRoutes

Компания, която все още работи със стария сървър на OptiRoutes (WEB), може да използва API за подписаните си POD: създайте ключ с правото 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, като посочите номера на компанията и часа на извикването — никога не изпращайте самия ключ.