Centrum pre vývojárov

REST API Dokumentácia

Preskúmajte, testujte a integrujte naše RESTful koncové body. Kompletné Swagger UI s interaktívnym tvorcom požiadaviek a podporou autentifikácie.

REST API

GraphQL API Dokumentácia

Dopytujte sa presne na údaje, ktoré potrebujete, pomocou nášho GraphQL API. Interaktívny playground s prieskumníkom schémy a testovaním operácií.

GraphQL

MCP stĺpec

AI agenti a MCP klienti: setup, bezpečnostné profily, schválenia a živé nástroje.

MCP

Integračné príručky

Štyri samostatné cesty. Každá je sama osebe kompletná: prihlásenie, cenová ponuka, rezervácia, štítok alebo platba, sledovanie a zoznam testov. Zostaňte na ceste, ktorú ste otvorili.

Expedícia

Vyzdvihnutie a doručenie (vlastná flotila)

Vytvorenie objednávky vyzdvihnutia alebo doručenia, tlač miestneho štítku, sledovanie a príjem udalostí — vlastná flotila, od začiatku do konca. Cenová ponuka je voliteľná.

Vyzdvihnutie alebo doručenie → miestny štítok → sledovanie → udalosti

FLOTILA

Štítky dopravcu

Zoznam spôsobov prepravy, sadzba, rezervácia štítku dopravcu, stiahnutie PDF a sledovanie zásielky.

Spôsoby → sadzba → nákup → PDF → sledovanie

ŠTÍTKY

Prepravné služby

Vlastné prepravné služby firmy: zoznam, odhad, objednávka, platba a sledovanie.

Služby → odhad → vytvorenie → platba → sledovanie

SLUŽBY

Skladovanie a výdaj

Naskladnite tovar, zaplaťte a na tejto ceste ho neskôr odošlite.

Naskladnenie → platba → výber → výdaj → sledovanie

SKLAD

MCP stĺpec

MCP 47 tools

Špecializovaná príručka pre AI agentov a MCP klientov: servery User vs Developer, least-privilege profily, dry-run, schválenia a živý katalóg.

Profily a scopes Ľudské schválenia Dry-run zápisy Developer MCP

Webhooky — Sprievodca Integráciou Webhook

Prijímajte udalosti v reálnom čase od Superroute — objednávky, zmeny stavu, aktualizácie sledovania. S podpísanými payload-mi, automatickými opakovaniami a vstavaným debugerom.

WEBHOOKS

OTEP — Otvorte protokol sledovania udalostí

Jedna udalosť. Nekonečné cesty. — Vlastné doručovanie, doručovanie treťou stranou a zásielky dopravcov sa zlučujú do jednej usporiadanej časovej osi udalostí pre každé sledovacie číslo.

OTEP

Sprievodca novinkami integrácie

Všetky novinky v API a webhookoch — idempotentné zrušenie, feedy na odsúhlasenie, podpisy v2, nové udalosti — s príkladmi na skopírovanie. Všetko plne spätne kompatibilné.

NEW

Postman Collection

Vždy aktuálna kolekcia generovaná naživo z API dokumentácie — importujte ju do Postmana a začnite volať API.

JSON

Slovník a tok stavov objednávok

Úplný slovník stavov objednávok a diagramy prechodov, generované naživo z nasadeného kódu.

MARKDOWN

Kódy sledovacích udalostí

Zákaznícke kódy sledovacích udalostí (strana vyzdvihnutia a doručenia), mapovanie OTEP, bežné toky a návod na vlastnú stránku sledovania s verejným API.

TRACKING

Začíname

Získajte API token

Prihláste sa a prejdite do Nastavenia → API kľúče na vygenerovanie osobného prístupového tokenu.

Vyberte API

Použite REST pre štandardné CRUD operácie, GraphQL pre flexibilné dátové dotazy alebo MCP na pripojenie AI asistentov priamo k vašim logistickým dátam.

Začnite vyvíjať

Otvorte interaktívnu dokumentáciu na testovanie endpointov v prehliadači a skopírujte úryvky kódu do svojej aplikácie.

Autentifikácia

Všetky tri API používajú rovnaký Bearer token (získaný cez prihlasovací endpoint). Niektoré endpointy sú verejné a nevyžadujú autentifikáciu — vrátane prihlásenia, verejného sledovania a samoregistrácie vodičov.

Získajte token cez prihlasovací endpoint:

                # POST /api/v1/user/login

                { "email": "you@example.com", "password": "••••••••" }

Hlavička požiadavky

Authorization: Bearer YOUR_ACCESS_TOKEN

REST Vyžadované pre väčšinu endpointov. Prihlásenie, verejné sledovanie a samoregistrácia vodičov sú verejné (token nie je potrebný).

GQL Vyžadovaný pre autentifikované operácie. Verejné operácie (prihlásenie, sledovanie) fungujú bez tokenu.

MCP Voliteľný. Verejné nástroje fungujú bez tokenu; platný token sprístupní personalizované dáta.

Základné URL

REST API https://api.superlabel.ca/api
GraphQL https://api.superlabel.ca/api/graphql
MCP https://api.superlabel.ca/mcp

Ktoré API mám použiť?

REST API

Štandardné CRUD operácie, webhoky, správa objednávok/trás

GraphQL

Flexibilné dotazy, vlastné správy, vnorené dotazy

MCP

Integrácia AI asistenta (Claude, Cursor, Copilot atď.)

AI integrácia

Dajte vášmu AI asistentovi logistické superschopnosti. Pripojte sa cez MCP bez kódovania, volajte naše API priamo z vášho AI agenta alebo si stiahnite súbor zručností pre kompletné sémantické vedenie.

Dostupné schopnosti

Verejné sledovanie

Vyhľadajte stav doručenia, časovú os udalostí a doklad o doručení (podpis/fotografia) akéhokoľvek balíka podľa sledovacieho čísla.

VEREJNÉ

Prevádzkové udalosti

Získajte kompletný audit trail objednávok — kto zmenil aký stav, kedy, kde, s GPS súradnicami a priloženými fotografiami.

VYŽADOVANÁ AUTENTIFIKÁCIA

Služba štítkov

Získajte cenové ponuky od prepravcov, vytvárajte prepravné štítky, sťahujte PDF štítkov, rušte zásielky a odosielasajte manifesty na konci dňa.

VYŽADOVANÁ AUTENTIFIKÁCIA

Lokálne doručenie

Vytvárajte objednávky na doručenie/vyzdvihnutie, zostavujte optimalizované trasy pre viacerých vodičov a spravujte kompletný workflow doručenia poslednej míle.

VYŽADOVANÁ AUTENTIFIKÁCIA

END USER Používateľský MCP server

Pre AI asistentov používaných vašimi zákazníkmi. Vložte konfiguráciu a váš AI môže okamžite sledovať balíky — nie je potrebné kódovanie.

ENDPOINT

https://api.superlabel.ca/mcp

Dostupné nástroje (47 živých nástrojov)

track_package Track a package by its tracking number. Returns delivery status, trackin... VEREJNÉ

otep_tracking Get the unified OTEP (Open Tracking Event Protocol) timeline for a track... VEREJNÉ

get_capabilities List MCP tools available to the current connection, with risk level, req... VEREJNÉ

get_orders List orders with filtering and pagination. Returns order details includi... AUTH

get_order_detail Get full details of a specific order by ID, including address, status, p... AUTH

find_order Fuzzy-find orders across tracking number, external tracking, ref, recipi... AUTH

get_operation_events Get the full audit trail for orders — every status change, who performed... AUTH

create_order Create a delivery/pickup order. D=delivery (warehouse→customer), P=picku... AUTH

cancel_order Cancel an existing order by order ID. Only works for orders not yet deli... confirm

bulk_create_orders Create up to 100 delivery orders in one call. Returns a per-order succes... confirm

reroute_to_address Change the delivery address of an order that has not been picked up yet:... confirm

update_delivery_instruction Update only the delivery_instruction field on an existing order (PATCH).... AUTH

update_order_note Update only the internal note field on an existing order (PATCH). AUTH

update_time_window_by_refs Bulk-update delivery time windows (and optional schedule_date) for order... AUTH

hold_order Put an order on HOLD so it is not dispatched until release_order. HIGH-R... confirm

release_order Release an order from HOLD back to NEW_ORDER. HIGH-RISK: requires confir... confirm

propose_write Queue a write/high-risk tool for human approval instead of executing it.... AUTH

list_pending_approvals List pending MCP write approvals for this business (or mine_only). AUTH

approve_pending_write Approve and execute a pending write proposal. HIGH-RISK: requires confir... confirm

reject_pending_write Reject a pending write proposal without executing it. AUTH

get_routes List delivery routes with their status, assigned driver, and order count... AUTH

get_route_detail Get one route with its stop/order list. Prefer this over get_routes when... AUTH

get_drivers List drivers for the authenticated business (ids, names, capacity defaul... AUTH

get_driver_routes_today Orders assigned to a driver on a given date (defaults to today). Useful... AUTH

get_build_route_options List routing engines, balance modes, capacity types, and defaults before... AUTH

build_route Build/optimize a delivery route (POST /api/v3/client/build-route). HIGH-... confirm

order_snapshot One-call order context for support: order detail + operation events + pu... AUTH

list_exceptions List failed/returned/exception-like orders for a schedule date (default... AUTH

get_shipping_methods List available shipping carriers/methods. Returns IDs and names — use th... AUTH

get_shipping_rate Get a shipping cost quote. Dry-run — no label created. Returns rate opti... AUTH

create_shipping_label Book a shipment with a carrier and generate a shipping label with tracki... AUTH

quote_and_ship One-shot: rate across all enabled carriers, pick the best one by strateg... AUTH

compare_all_carriers Get rate quotes from every enabled carrier for the same shipment, in one... AUTH

search_address Search and resolve addresses by postal code or free-text query. Returns... AUTH

daily_digest One-call summary of today's logistics activity: total orders, by status,... AUTH

get_orders_summary Aggregate order metrics over a time window: counts by status, top carrie... AUTH

get_account_credits Get the authenticated customer's wallet balance, currency, and recent to... AUTH

get_warehouses List WMS warehouses available to the authenticated business. AUTH

get_inventory Query WMS inventory (POST /api/v1/wms/inventory). Pass filters supported... AUTH

list_datasets List custom datasets available to the business. AUTH

get_dataset Get one dataset by id (metadata/columns). AUTH

list_dataset_groups List groups inside a dataset. AUTH

search_dataset_records Search records across groups in a dataset (POST .../search). AUTH

list_alliances List alliances the authenticated business belongs to. AUTH

get_alliance Get one alliance by id. AUTH

list_alliance_members List members of an alliance. AUTH

list_accessible_clients List clients accessible via alliance partnerships. AUTH

// .mcp.json — ops agent s úzkym profilom
{
  "mcpServers": {
    "superroute": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp",
      "headers": {
        "Authorization": "Bearer <token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

DEVELOPER Vývojársky MCP server

Pre AI asistentov kódovania (Claude Code, Cursor atď.), ktorí vám pomáhajú vytvárať integrácie so Superroute. Váš AI môže priamo volať API, testovať koncové body a generovať integračný kód.

ENDPOINT

https://api.superlabel.ca/mcp/developer

Dostupné nástroje (25 živých nástrojov)

track_package Sledovať balík podľa sledovacieho čísla VEREJNÉ

get_operation_events Získať audit trail objednávky AUTH

get_shipping_methods Zoznam dostupných prepravcov AUTH

get_shipping_rate Získať cenovú ponuku prepravnej sadzby AUTH

create_shipping_label Vytvoriť prepravný štítok AUTH

get_shipping_label Detaily štítku a stiahnutie AUTH

create_order Vytvoriť objednávku doručenia/vyzdvihnutia AUTH

build_route Stavať optimalizované doručovacie trasy AUTH

get_build_route_options Get available options for building routes: routing engines with their balance modes, capacity ty... AUTH

get_api_endpoints Search the complete Superroute REST API catalog (the same OpenAPI spec that powers /api/document... VEREJNÉ

get_graphql_operations Search the Superroute GraphQL catalog — every query and mutation, grouped by category, each with... VEREJNÉ

run_graphql_query Execute a query or mutation against the Superroute GraphQL endpoint (POST /api/graphql) and retu... AUTH

get_otep_tracking Get a package's tracking history as an OTEP (Open Tracking Event Protocol) document — the normal... VEREJNÉ

validate_otep_payload Run an OTEP document or event through the live conformance validator (POST /api/v1/otep/validate... VEREJNÉ

check_skill_update Check if a newer version of the Superroute AI integration skill file is available. Returns curre... VEREJNÉ

get_integration_guide Získať sprievodcu integráciou VEREJNÉ

get_otep_guide Get the OTEP (Open Tracking Event Protocol) development guide — the What/When/Where/Why event mo... VEREJNÉ

get_webhook_guide Príručka webhook integrácie VEREJNÉ

verify_webhook_signature Verify whether an incoming webhook signature is valid. Pass the raw payload (string or JSON obje... VEREJNÉ

test_webhook_delivery Fire a real, properly-signed test webhook from Superroute servers to a URL the developer provide... AUTH

get_webhook_settings Read the caller's own webhook configuration — every per-event callback URL, the behaviour flags,... AUTH

update_webhook_settings Self-serve update of the caller's webhook configuration (PUT /api/v1/webhook-settings). Partial:... AUTH

get_order_audit_timeline Chronological audit timeline of ONE order across every source: web actions, driver app scans, wa... AUTH

get_webhook_delivery_logs List recorded webhook delivery attempts for the caller — event type, target URL, HTTP status, at... AUTH

replay_webhook_delivery Re-send a webhook that was already logged, by delivery-log id (get the id from get_webhook_deliv... AUTH

// .mcp.json — preferovaný connection Bearer
{
  "mcpServers": {
    "superroute-dev": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp/developer",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Po 2026-12-31 neposielajte api_token v argumentoch. Použite Authorization na MCP pripojení.

User MCP slúži na správu Superroute agentmi; Developer MCP na integrácie. Úplný model je v MCP stĺpci. Otvoriť MCP stĺpec →

AI Koncové body zisťovania nástrojov

Opisy štruktúrovaných schopností pre agentov AI, systémy na volanie nástrojov LLM a klientov MCP. Všetky koncové body sú verejné, nevyžaduje sa žiadna autentifikácia.

PRIMARY AI Manifest nástrojov

Kompletný manifest s definíciami nástrojov, schémami, autorizačnými informáciami a pracovnými postupmi.

GET https://api.superlabel.ca/api/.well-known/ai-tools.json

K dispozícii aj: /llms.txt

FORMAT Multiformátový export

Získajte definície nástrojov vo formáte natívnom pre vašu platformu AI.

# OpenAI function calling
GET https://api.superlabel.ca/api/ai/tools?format=openai

# Anthropic Claude tool_use
GET https://api.superlabel.ca/api/ai/tools?format=anthropic

# MCP tools/list
GET https://api.superlabel.ca/api/ai/tools?format=mcp

# LangChain StructuredTool
GET https://api.superlabel.ca/api/ai/tools?format=langchain

REST OpenAPI + AI rozšírenia

Špecifikácia OpenAPI obohatená o rozšírenia x-ai-* (názvy nástrojov, kedy ich použiť, kategórie).

GET https://api.superlabel.ca/api/ai/tools/openapi

GQL GraphQL + AI Rady

Dokumenty GraphQL obohatené o aiHints na operáciu (kedy použiť, súvisiace pracovné postupy).

GET https://api.superlabel.ca/api/ai/tools/graphql

Rýchla integrácia

Python (OpenAI SDK )

import requests, json
tools = requests.get(
  "https://api.superlabel.ca/api/ai/tools?format=openai"
).json()["tools"]

# Pass to OpenAI
response = client.chat.completions.create(
  model="gpt-4",
  messages=messages,
  tools=tools
)

Python (Claude SDK )

import requests, anthropic
tools = requests.get(
  "https://api.superlabel.ca/api/ai/tools?format=anthropic"
).json()["tools"]

# Pass to Claude
response = client.messages.create(
  model="claude-sonnet-4-20250514",
  messages=messages,
  tools=tools
)

Node.js (načítanie)

const res = await fetch(
  "https://api.superlabel.ca/api/ai/tools?format=openai"
);
const { tools } = await res.json();

// Use with any LLM SDK
console.log(`Loaded ${tools.length} tools`);

Súhrn schopností: Pre zjednodušený prehľad (iba kategórie a názvy nástrojov) použite GET https://api.superlabel.ca/api/ai/capabilities

AI Tools Playground

Testujte nástroje Superroute AI priamo vo svojom prehliadači. Vyberte nástroj, vyplňte parametre a pozrite si živú odpoveď API.

Vyberte položku Nástroj

track_package

Telo žiadosti ( JSON )

odpoveď

Kliknutím na „Spustiť“ spustíte nástroj...

Vyvíjajte s REST alebo GraphQL

Pre vývojárov, ktorí vytvárajú vlastných AI agentov, chatbotov alebo programatické integrácie. Volajte naše API priamo z vášho kódu s úplným prístupom ku všetkým logistickým schopnostiam.

REST REST API koncové body

# Sledovať balík (verejné)
GET https://api.superlabel.ca/api/v1/tracking/{number}

# Prevádzkové udalosti
POST https://api.superlabel.ca/api/v1/tracking/operationevents

# Získať prepravnú sadzbu
POST https://api.superlabel.ca/api/v1/labelservice/rate

# Vytvoriť prepravný štítok
POST https://api.superlabel.ca/api/v1/labelservice/submitOrder

# Vytvoriť objednávku doručenia
POST https://api.superlabel.ca/api/v1/client/orderCreate

# Zostaviť optimalizovanú trasu
POST https://api.superlabel.ca/api/v3/client/build-route

# Nastaviť webhooky
PUT https://api.superlabel.ca/api/v1/webhook-settings

# Otvorená časová os sledovania (OTEP)
GET https://api.superlabel.ca/api/v1/otep/trackings/{number}

Kompletná dokumentácia

GQL GraphQL operácie

# Jeden koncový bod
POST https://api.superlabel.ca/api/graphql

# Dostupné operácie
trackingPublic       ← Sledovať balík (verejné)
trackingOperationevents ← Prevádzkové udalosti
labelserviceRate      ← Získať prepravnú sadzbu
labelserviceSubmitOrder ← Vytvoriť prepravný štítok
clientOrderCreate     ← Vytvoriť objednávku doručenia
clientBuildRoute      ← Zostaviť optimalizovanú trasu
webhookSettingsUpdate ← Nastaviť webhooky
otepTracking          ← Otvorená časová os sledovania (OTEP)

Kompletná dokumentácia

Pre väčšinu AI integrácií odporúčame REST API — je jednoduchšie na ladenie a každý endpoint je samostatný. GraphQL použite, keď potrebujete flexibilné dotazy alebo chcete získať vnorené dáta v jednej požiadavke.

Superroute AI integračná zručnosť

Komplexný súbor zručností s hlbokými znalosťami logistickej domény — čo robí každé API, kedy ho použiť, čo parametre znamenajú v reálnom obchodnom kontexte, ako interpretovať výsledky a ako sa schopnosti navzájom kombinujú.

Stiahnuť súbor zručností (.md)

Ako používať súbor zručností

Claude Code

1 Stiahnite vyššie uvedený súbor
2 Umiestnite ho do adresára .claude/skills/ vášho projektu
3 Zadajte /integrate v Claude Code pre spustenie interaktívneho sprievodcu

mkdir -p .claude/skills
cp superroute-ai-integration.md .claude/skills/

Cursor

1 Stiahnite vyššie uvedený súbor
2 Umiestnite ho do adresára .cursor/rules/ vášho projektu
3 Cursor ho automaticky použije ako kontext, keď sa opýtate na integráciu so Superroute

mkdir -p .cursor/rules
cp superroute-ai-integration.md .cursor/rules/

Iné AI nástroje

1 Stiahnite vyššie uvedený súbor
2 Vložte obsah do systémového promptu alebo znalostnej bázy vášho AI nástroja
3 AI použije sémantické popisy na vedenie integrácie

# Alebo vložte do systémového promptu
cat superroute-ai-integration.md

Udržujte súbor zručností aktuálny

RÝCHLO Aktualizácia jedným príkazom

Stiahnite najnovšiu verziu súboru zručností priamo zo servera.

# Claude Code
curl -sS https://api.superlabel.ca/api/ai-skill -o .claude/skills/superroute-ai-integration.md

# Cursor
curl -sS https://api.superlabel.ca/api/ai-skill -o .cursor/rules/superroute-ai-integration.md

API API kontroly verzie

Skontrolujte najnovšiu verziu na serveri pred stiahnutím. Porovnajte hash s lokálnym súborom.

GET https://api.superlabel.ca/api/ai-skill/version

Odpoveď:
{ "version": "1.0.0", "hash": "abc123...", "download_url": "..." }

MCP Automatická aktualizácia cez MCP

Ak máte pripojený vývojársky MCP server, váš AI asistent môže kontrolovať aktualizácie pomocou nástroja check_skill_update. Zadajte MD5 hash lokálneho súboru.

// Volanie cez vývojársky MCP Server
{
  "method": "tools/call",
  "params": {
    "name": "check_skill_update",
    "arguments": { "current_hash": "your_local_file_md5_hash" }
  }
}

CRON Skript automatickej aktualizácie (Cron / CI)

Pridajte tento skript do CI pipeline alebo cron úlohy, aby bol súbor zručností vždy aktuálny.

#!/bin/bash
# auto-update-skill.sh
SKILL_FILE=".claude/skills/superroute-ai-integration.md"
BASE_URL="https://api.superlabel.ca"

mkdir -p "$(dirname "$SKILL_FILE")"
LOCAL_HASH=$(md5sum "$SKILL_FILE" 2>/dev/null | cut -d' ' -f1)
SERVER_HASH=$(curl -s "$BASE_URL/api/ai-skill/version" | python3 -c "import sys,json; print(json.load(sys.stdin)['hash'])")

if [ "$LOCAL_HASH" != "$SERVER_HASH" ]; then
  curl -sS "$BASE_URL/api/ai-skill" -o "$SKILL_FILE"
  echo "Updated!"
fi

Súbor zručností presahuje API dokumentáciu — naučí vášho AI asistenta obchodný význam každého parametra, ako interpretovať odpovede a ako kombinovať schopnosti pre komplexné logistické workflow.