Examples: curl, JavaScript, Python

The examples read the API address and key from ORDA_API and ORDA_KEY.

curl

curl -s -H "X-Api-Key: $ORDA_KEY" "$ORDA_API/orders?date=2026-11-20&limit=500"
curl -s -H "X-Api-Key: $ORDA_KEY" "$ORDA_API/orders/external/SO-00001"
curl -s -H "X-Api-Key: $ORDA_KEY" "$ORDA_API/plans?date=2026-11-20"

JavaScript (Node.js 18+, no libraries)

const API = process.env.ORDA_API; // e.g. https://api.ordatms.kz/api/v1
const KEY = process.env.ORDA_KEY;

async function orda(method, path, body, { idempotencyKey, attempts = 5 } = {}) {
  for (let i = 0; ; i++) {
    const res = await fetch(`${API}${path}`, {
      method,
      headers: {
        'X-Api-Key': KEY,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
        ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    }).catch((e) => ({ ok: false, status: 0, error: e }));
    const retry = res.status === 0 || res.status === 429 || res.status >= 500;
    if (!retry || i + 1 >= attempts) {
      if (!res.ok) throw new Error(`Orda ${method} ${path}: ${res.status} ${res.error ?? (await res.text())}`);
      return res.status === 204 ? null : res.json();
    }
    const wait = Number(res.headers?.get('retry-after')) || 2 ** i;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

// Export orders in batches of 1000 and report failed rows
export async function exportOrders(orders, batchId) {
  for (let i = 0; i < orders.length; i += 1000) {
    const part = orders.slice(i, i + 1000);
    const r = await orda('POST', '/orders/bulk', { orders: part }, { idempotencyKey: `${batchId}-${i / 1000}` });
    for (const row of r.results.filter((x) => x.result === 'error'))
      console.warn(`Order ${row.externalId}: ${row.error.code} — ${row.error.message}`);
  }
}

// Routes of approved plans
export async function approvedRoutes(date) {
  const plans = await orda('GET', `/plans?date=${date}`);
  const approved = plans.filter((p) => p.status === 'approved');
  return Promise.all(approved.map((p) => orda('GET', `/plans/${p.id}`)));
}

Python 3 (requests)

import os, time, requests

API, KEY = os.environ["ORDA_API"], os.environ["ORDA_KEY"]
session = requests.Session()
session.headers["X-Api-Key"] = KEY

def orda(method, path, json=None, idempotency_key=None, attempts=5):
    headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
    for i in range(attempts):
        try:
            r = session.request(method, API + path, json=json, headers=headers, timeout=60)
        except requests.ConnectionError:
            r = None
        if r is not None and r.status_code < 500 and r.status_code != 429:
            r.raise_for_status()
            return None if r.status_code == 204 else r.json()
        time.sleep(int(r.headers.get("Retry-After", 2 ** i)) if r is not None else 2 ** i)
    raise RuntimeError(f"Orda {method} {path}: retries exhausted")

orders = [{
    "externalId": "SO-00001", "number": "SO-00001", "deliveryDate": "2026-11-20",
    "customerExternalId": "K-001", "weightKg": 120, "amount": 15000, "paymentType": "cash",
}]
result = orda("POST", "/orders/bulk", {"orders": orders}, idempotency_key="export-2026-11-20-1")
for row in result["results"]:
    if row["result"] == "error":
        print(row["externalId"], row["error"]["code"], row["error"]["message"])

Receiving webhooks

# FastAPI
from fastapi import FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["ORDA_WEBHOOK_SECRET"]
seen = set()  # in production: a table of processed event ids

@app.post("/orda/webhook")
async def orda_webhook(request: Request):
    raw = await request.body()
    if not verify_orda_signature(raw, request.headers.get("Orda-Signature", ""), SECRET):
        return Response(status_code=401)
    event = await request.json()
    if event["id"] not in seen:
        seen.add(event["id"])
        # enqueue: update the document event["data"]["externalId"]
    return Response(status_code=204)

verify_orda_signature is on the Webhooks page (also Node.js and PHP).

Postman / Insomnia / client generation

Import openapi.json (Postman → Import → Link) or generate a client: npx @openapitools/openapi-generator-cli generate -i openapi.json -g python -o orda-client.