API de arquivos do OptiRoutes

O que é

Cada empresa no OptiRoutes tem a sua própria pasta privada de arquivos: os pedidos que ela carrega, as notas de entrega assinadas (POD) com suas fotos e assinaturas, as exportações de rotas e os relatórios de fim de dia. A API de arquivos permite que os seus sistemas leiam e gravem diretamente nessa pasta, sem um servidor FTP no meio.

• Endereço: https://srv2.optiroutes.com/api/v1 — somente HTTPS.
• Acesso: uma chave de API que o gestor da empresa cria no OptiRoutes, em Configurações → API e arquivos. Não é preciso fazer nenhuma solicitação ao suporte do OptiRoutes.
• Todos os tipos de arquivo com os quais o sistema trabalha hoje: CSV, JSON, TXT, XLSX/XLS, PDF e imagens.
• As respostas são em JSON, exceto os downloads de arquivos, que retornam o próprio arquivo.

Comece em 3 passos

1. Crie uma chave. No OptiRoutes, o gestor abre Configurações → API e arquivos, clica em Nova chave, dá um nome a ela (por exemplo, “servidor do ERP”), escolhe as permissões e copia a chave. A chave é exibida uma única vez.
2. Verifique a conexão.

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

3. Baixe os POD assinados de hoje em um único ZIP:

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

Segurança — leia com atenção

• Trate a chave como uma senha. Guarde-a em um cofre de segredos ou em uma variável de ambiente no seu servidor. Nunca a coloque em uma página da web, em um aplicativo móvel, em um e-mail, em um chamado ou no controle de versão.
• Privilégio mínimo. Dê a cada sistema a sua própria chave, apenas com as permissões de que ele precisa: pod:read (somente POD assinados), files:read (leitura de todos os arquivos da empresa), files:write (envio de pedidos e de arquivos da caixa de entrada).
• Limite os endereços. Quando o seu servidor tiver um endereço IP fixo, adicione-o à chave (“Endereços permitidos”). Uma chamada vinda de qualquer outro endereço é recusada.
• Validade e rotação. Uma chave pode expirar depois de um número de dias. Para fazer a rotação: crie uma nova chave, mude o seu sistema para ela e depois revogue a antiga — sem nenhuma indisponibilidade.
• Revogue imediatamente uma chave que possa ter vazado: Configurações → API e arquivos → Revogar chave. Ela deixa de funcionar em até 30 segundos.
• Auditoria. Cada chamada é registrada (hora, endereço, arquivo, resposta) e exibida ao gestor na mesma tela.
• O OptiRoutes guarda apenas uma impressão digital (SHA-256) de cada chave, nunca a chave em si. As conexões são somente por HTTPS (TLS 1.2+).
• Uma chave alcança apenas a pasta da própria empresa. Os arquivos de outras empresas e as pastas internas do sistema nunca podem ser acessados.

Autenticação

Envie a chave em todas as solicitações, em um destes cabeçalhos:

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

Uma chave tem este formato: opr_2813_… (o número da empresa, seguido de 32 caracteres aleatórios).

A pasta da empresa

Referência

Exemplo de resposta de uma listagem:

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

Tarefas comuns

Enviar o arquivo de pedidos de hoje

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

O OptiRoutes carrega o arquivo da mesma forma que carrega hoje (pelo carregamento automático de Configurações → Carregamento de pedidos, ou por “Carregar arquivo” do usuário).

Baixar os POD assinados de um pedido

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"

Baixar o relatório de fim de dia

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

Trabalhar como com FTP — um script de sincronização de pasta

As equipes que trabalhavam com FTP podem manter uma pasta no próprio servidor sincronizada com a pasta da empresa: uma tarefa agendada baixa os arquivos novos (por exemplo, os POD) e envia os arquivos que você coloca em uma pasta local. O script PowerShell abaixo faz as duas coisas; execute-o a cada poucos minutos pelo Agendador de Tarefas do Windows (no Linux, use as linhas de curl com 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
}

Migrar uma empresa do FTP para a API

O gestor faz a troca em Configurações → API e arquivos → Como os arquivos da empresa circulam: API (recomendado). A partir desse momento, nada mais é enviado ao FTP da empresa, e cada arquivo fica, em vez disso, na pasta da empresa:

As empresas novas trabalham com a API desde o início. Voltar para o FTP é feito pela mesma chave de alternância.

Empresas no servidor antigo do OptiRoutes

Uma empresa que ainda trabalha com o servidor antigo do OptiRoutes (WEB) pode usar a API para os seus POD assinados: crie uma chave com a permissão pod:read e use /api/v1/pod, /api/v1/pod/archive e /api/v1/files/download?path=pod/…. Os demais arquivos continuam circulando como hoje, até que a empresa migre para o novo servidor.

Erros

Um erro responde com {"ok": false, "error": "<code>", "message": "<explanation>"}.

Limites

• 300 solicitações por minuto por chave.
• 50 MB por arquivo.
• 20 chaves ativas por empresa.
• A listagem de uma pasta retorna até 5.000 entradas; para obter mais, liste as subpastas (por exemplo, um dia de POD).

Ajuda

O gestor da empresa vê cada chave, o seu último uso e as últimas chamadas em Configurações → API e arquivos. Para qualquer outro assunto, entre em contato com o suporte do OptiRoutes informando o número da empresa e o horário da chamada — nunca envie a chave em si.