Dokumentácia API

Autentifikácia

Každá požiadavka potrebuje váš API kľúč v hlavičke Authorization (odporúčané) alebo ako parameter ?key=.

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Obálka odpovede

{
  "ok": true,
  "api_version": "v1",
  "product": "queue",
  "attribution": "Data by nakordoni.eu",
  "terms": "https://nakordoni.eu/en/p/developer_api_terms",
  "data": { ... },
  "usage": { "limit": 1000, "used": 42, "reset": "2026-06-06T00:00:00Z" }
}

Chyby vracajú ok:false s error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, not_approved, bad_request, duplicate_request, market_not_allowed, internal_error, status_unavailable, timeout) a HTTP stavom 400/401/403/404/429/500/503/504. Hlavičky obmedzenia rýchlosti X-Devapi-Limit a X-Devapi-Remaining sa odosielajú pri každej meranej odpovedi. ok:false je rozhodujúce — data pri neúspešnom volaní nikdy nečítajte. Objekt usage je v každom spoplatnenom produkte; /status je verejný a nespoplatnený, preto usage nevracia.

Kvóty

Denné počítadlá sa resetujú o polnoci UTC. E-mail dostanete pri 80 % a 100 % kvóty.

Platené plány zvyšujú každý z týchto limitov. Aktuálne plány a ich limity: Plány

Ukážky kódu

curl

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer $NKD_API_KEY"

JavaScript (fetch)

const res = await fetch('https://nakordoni.eu/api/v1/data/forecast?ppid=id_13&prediction_steps=24', {
  headers: { Authorization: `Bearer ${process.env.NKD_API_KEY}` }
});
const { ok, data, error, usage } = await res.json();
if (!ok) throw new Error(error?.code ?? res.status);
console.log(`forecast points: ${data.length}, calls left today: ${usage.limit - usage.used}`);

Python (requests)

import os, requests

r = requests.get(
    "https://nakordoni.eu/api/v1/data/stats",
    params={"ppid": "id_15", "compare": 1},
    headers={"Authorization": f"Bearer {os.environ['NKD_API_KEY']}"},
    timeout=15,
)
payload = r.json()
print(payload["data"]["daily"], payload["usage"])

Excel (Power Query)

Získajte živé údaje o frontách, predpovediach či zákazoch pre nákladné vozidlá priamo do zošita pomocou vstavaného JSON konektora Power Query — bez kódu, s obnovou podľa plánu. Rovnaký vzor Headers funguje pre každý produkt tohto API — stačí zmeniť URL.

Data → Get Data → From Other Sources → Blank Query, then Home → Advanced Editor and paste:

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/queue",
        [Query = [ppid = "id_13"], Headers = [Authorization = "Bearer " & ApiKey]])),
    data = Source[data],
    AsTable = Record.ToTable(data)
in
    AsTable

Kľúč API uchovávajte vnútri M-dotazu (Home → Advanced Editor), nie v bunke hárka — Power Query blokuje webovú požiadavku zostavenú z iného dotazu alebo bunky ("Formula.Firewall"), pokiaľ nie je úroveň ochrany súkromia nastavená na Organizational.

Viacero hraničných priechodov v jednej tabuľke (flotilové dashboardy) — e.g. every truck crossing UA→PL (crossing_type=9; in v3 that one code covers both freight lanes):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v4/data/border/1/2/9",
        [Headers = [Authorization = "Bearer " & ApiKey]])),
    checkpoints = Source[data],
    AsTable = Table.FromRecords(checkpoints)
in
    AsTable

Data → Refresh All v Exceli alebo naplánovaná obnova v Power BI / Excel Online udržiava čísla aktuálne — bez kódu na dopytovanie (polling).

Integrácia s ERP (BAS / BAF a platformy rodiny 1C)

BAS / BAF a ďalšie platformy rodiny 1C môžu volať toto API priamo z naplánovanej úlohy — HTTPConnection plus ReadJSON, bez medzivrstvy a bez ďalšej služby. Najčastejšie nasadenie udržiava aktuálny register informácií s cenami palív v EÚ.

Aktualizácia registra informácií (ceny palív, všetky krajiny jedným volaním)

// Scheduled job — runs once a day
Connection = New HTTPConnection("nakordoni.eu", 443, , , , 30, New OpenSSLSecureConnection);

Headers = New Map;
Headers.Insert("Authorization", "Bearer NKD-DEV-XXXX-XXXX-XXXX");

Request  = New HTTPRequest("/api/v1/data/fuel", Headers);
Response = Connection.Get(Request);

Reader = New JSONReader;
Reader.SetString(Response.GetBodyAsString("UTF-8"));
Answer = ReadJSON(Reader, True);
Reader.Close();

If Answer["ok"] <> True Then
    // Answer["error"]["code"] says why; Answer["usage"] holds your quota state
    Return;
EndIf;

For Each Row In Answer["data"] Do
    Record = InformationRegisters.FuelPrices.CreateRecordManager();
    Record.Period   = CurrentSessionDate();
    Record.Country  = Row["country"];    // "PL", "DE", "SK", "RO", ...
    Record.Diesel   = Row["diesel"];
    Record.Petrol   = Row["petrol"];
    Record.LPG      = Row["lpg"];
    Record.Currency = Row["currency"];
    Record.Write();
EndDo;

Tri veci treba trafiť: odovzdajte New OpenSSLSecureConnection na porte 443, inak požiadavka padne na TLS; volajte /api/v1/data/fuel bez parametra country, aby jedna požiadavka vrátila všetky krajiny namiesto volania na každú zvlášť; a overte ok skôr, než siahnete na data — chyby prichádzajú ako ok:false s error.code, nie ako výnimka. Ukážka používa anglickú sadu kľúčových slov platformy; lokalizované ekvivalenty (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) sa správajú rovnako.

Ceny palív sa v zdrojoch menia raz denne, takže naplánovaná úloha raz či dvakrát denne stačí a zostáva hlboko v bezplatnej kvóte Explorer. Živé údaje o radoch (queue, multi, border) sa menia každých pár minút — tie sťahujte vlastným tempom a pomocou multi načítajte až 5 hraničných priechodov jednou požiadavkou namiesto cyklu.

MCP server

Uprednostňujete volanie nástrojov pred REST? Prevádzkujeme skutočný MCP server (prenos Streamable HTTP), ktorý sprístupňuje bezpečnú, len na čítanie určenú podmnožinu tohto API ako MCP nástroje — rovnaký API kľúč, rovnaká kvóta, len iný prenos.

Endpoint: https://nakordoni.eu/mcp · Server card: /.well-known/mcp/server-card.json

get_api_status      — no key required
list_checkpoints     — country, lang
get_border_queue     — origin, destination, crossing_type, lang
get_live_queue       — ppid, lang
get_queue_forecast   — ppid, prediction_steps

Konfigurácia klienta (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "nakordoni": {
      "url": "https://nakordoni.eu/mcp",
      "headers": { "Authorization": "Bearer NKD-DEV-XXXX-XXXX-XXXX" }
    }
  }
}

OAuth pre integrácie (Home Assistant a ďalšie)

Integrácie, ktorých používatelia potrebujú každý vlastný kľúč (vlastné integrácie Home Assistant, desktopové a mobilné aplikácie), môžu používateľovi umožniť prihlásiť sa namiesto vkladania kľúča. Tok je OAuth 2.0 authorization code pre verejných klientov s PKCE (S256) — client secret neexistuje. Prístupový token, ktorý vraciame, je vlastný kľúč NKD-DEV používateľa, ktorý potom posielate v hlavičke Bearer presne ako doteraz.

Klientov si nemožno vytvoriť samoobslužne: požiadajte o nich na stránke Integrácie, každú integráciu kontrolujeme ručne a vydávame client ID s povolenými presmerovacími URI. Kľúče vydané cez schváleného klienta sa okamžite aktivujú pre trhy schválené pre danú integráciu. Požiadať o klienta integrácie →

• Autorizačný kód platí 60 sekúnd, je jednorazový a viazaný na klienta, používateľa, presmerovacie URI a PKCE challenge.
• Kľúč sa vracia iba v tele odpovede s tokenom (access_token) — nikdy v URL. Uchovávajte ho ako heslo.
• expires_in je 30 dní; obnovenie vráti rovnaký kľúč, kým je aktívny. Ak používateľ kľúč odvolá alebo vygeneruje nový, obnovenie zlyhá s invalid_grant a volania API vrátia 401 — spustite opätovnú autentifikáciu.
• Požiadavky majú obmedzenú frekvenciu na IP adresu a denný limit na klienta; chyby zodpovedajú RFC 6749 (error, error_description).
• Každý používateľ dostane najviac vlastný limit krajín: ak integrácia obsahuje viac krajín, než má používateľ voľných miest, vyberie si ich na stránke súhlasu (markets=DE,AT v /oauth/authorize ich predvyberie). Obe odpovede token vracajú aj markets_approved (schválené krajiny používateľa), markets_allowed (jeho limit; null = bez limitu), markets_available (vaše krajiny, ktoré ešte nemá) a upgrade_url (kde pridá „Extra krajiny“).

curl -X POST https://api.nakordoni.dev/oauth/token \
  -d grant_type=authorization_code -d client_id=nkd_xxxxxxxxxxxxxxxxxxxxxxxx \
  -d code=CODE -d code_verifier=VERIFIER \
  -d redirect_uri=https://my.home-assistant.io/redirect/oauth

{"access_token":"NKD-DEV-XXXX-XXXX-XXXX","token_type":"Bearer","expires_in":2592000,
 "refresh_token":"nkdrt_…","scope":"data","markets_approved":["DE"]}

Home Assistant

Použite config_entry_oauth2_flow s LocalOAuth2ImplementationWithPkce (client_secret prázdny) a presmerovacím URI https://my.home-assistant.io/redirect/oauth, ktoré je vopred zaregistrované pre klientov Home Assistant. Kľúč čítajte z entry.data["token"]["access_token"] a API ďalej volajte s hlavičkou Authorization: Bearer. Pri odpovedi 401 z API vyvolajte ConfigEntryAuthFailed, aby Home Assistant ponúkol opätovnú autentifikáciu.

from homeassistant.helpers import config_entry_oauth2_flow

impl = config_entry_oauth2_flow.LocalOAuth2ImplementationWithPkce(
    hass, DOMAIN, client_id="nkd_xxxxxxxxxxxxxxxxxxxxxxxx",
    authorize_url="https://api.nakordoni.dev/oauth/authorize",
    token_url="https://api.nakordoni.dev/oauth/token",
)
config_entry_oauth2_flow.async_register_implementation(hass, DOMAIN, impl)

Integrácie: zobrazte zostávajúce limity

GET /api/v2/account/usage — Koľko vám práve zostáva z limitov pre kľúč, ktorým voláte: plán, limit za sekundu a pre každú triedu dennej kvóty (cheap, heavy, route) limit, spotreba, zostatok a čas resetu (polnoc UTC); aj vaše krajiny tak, ako ich vidí tento kľúč, a kde prejsť na vyšší plán. Nepočíta sa, 30 volaní za minútu na kľúč.

Kľúče integrácií (OAuth) môžu vždy volať GET /api/v2/account/usage bez ohľadu na produkty povolené integrácii. Čísla zodpovedajú hlavičkám X-Devapi-Limit a X-Devapi-Remaining; X-Devapi-Reset uvádza čas resetu ako Unix timestamp.

{"ok":true,"api_version":"v2","product":"account-usage","data":{
 "plan":{"slug":"explorer","name":"Explorer"},"qps":2,
 "quotas":{"cheap":{"limit":1000,"used":42,"remaining":958,"reset_at":"2026-10-17T00:00:00Z"},"heavy":{…},"route":{…}},
 "markets":{"approved":["DE"],"allowed":1,"available":["AT"],"key_bound":true},
 "pass":{"active":true,"expires_at":"2026-10-19T14:05:00Z","days_left":3},"upgrade_url":"https://nakordoni.eu/en/developers/billing",
 "pass_url":"https://nakordoni.eu/en/developers/billing?section=trip-pass#trip-pass"}}

Keď dosiahnete limit, chyba povie, kam ísť: 429 quota_exceeded vracia aj error.reset_at (polnoc UTC) a error.upgrade_url; 403 market_not_allowed a 403 integration_product_not_allowed vracajú error.upgrade_url. Kľúče integrácií dostanú aj error.pass_url (Trip Pass, nižšie).

Home Assistant: dopytujte /account/usage najviac raz za 15 minút a sprístupnite senzor „zostávajúce volania“ z quotas.cheap.remaining. Medzi dopytmi čítajte X-Devapi-Remaining z bežných volaní. Pri 429 quota_exceeded alebo 403 market_not_allowed vytvorte repair issue s odkazom na error.upgrade_url a pozastavte volania do reset_at.

Trip Pass

Používatelia integrácií si môžu na stránke fakturácie kúpiť Trip Pass (1, 3, 7 alebo 14 dní, jednorazová platba). Kým je aktívny, kľúč integrácie dostane všetky krajiny integrácie, viac volaní trasy pre kamióny a dát denne a vyššiu frekvenciu; produkty integrácie, limity predpovedí a oneskorenie dát sa nemenia. Vývojárske kľúče toho istého účtu sa nikdy nezvyšujú.

Pre kľúče integrácie vracia account/usage pass: {active, expires_at, days_left} a pass_url (sekcia Trip Pass na stránke fakturácie); 429 quota_exceeded a 403 market_not_allowed / integration_product_not_allowed obsahujú to isté error.pass_url. Pre iné kľúče sú obe null.

Country and vehicle-type codes

Border endpoints address countries and vehicle types by numeric id: /api/v1/data/border/{origin}/{destination}/{crossing_type}. destination also accepts a comma-separated list or the word all. The ids are stable and are the same in every product that takes an origin, a destination or a crossing_type.

Country ids

The border products accept the ids marked as origins below; the neighbours column is what destination=all expands to for that origin. Ids without neighbours are countries we name in responses but hold no crossings for yet. The Checkpoints Directory returns the origin, destination and crossing_type of every crossing we actually serve, so it stays the authoritative list.

Vehicle types (crossing_type)

The label in this table is the crossing_type_label the API returns with every response, in the language you request. Types outside the accepted list belong to crossings the directory carries but the border products do not answer for — ferry (10-13), freight up to 3.5 t (14) and rail (15) — and asking for one returns 400, not an empty result. Read crossing_type from the Checkpoints Directory rather than assuming: a crossing returns data only for the types it actually has.

Produkty

Vyberte si endpoint pre jeho úplnú referenciu, parametre, verzie a živý sandbox.

Štandardný využíva štandardnú dátovú kvótu  ·  Ťažký využíva kvótu prognóz a štatistík — pozri Kvóty  ·  Trasa pre nákladné vozidlá čerpá z vlastnej kvóty trás pre nákladné vozidlá — pozri Kvóty

Fronty na hranici

Predpovede a štatistiky

Palivo a lokality

Zmenárne

Cestovné plánovanie

Logistika

Vodiči a cesty

Your Fleet (NakBus Live)

AI asistent

Ostatné

Export historických údajov

Schválení vývojári si môžu stiahnuť zverejnenú históriu hraničných radov spriemerovanú po hodinách pre najviac 5 priechodov (posuvné okno až 90 dní) ako gzipovaný CSV, NDJSON alebo JSON. Je to funkcia dostupná len v portáli — NIE endpoint API; exporty si zostavujete a sťahujete v záložke „Export údajov“ vo svojom účte.

Prístup udeľujeme na požiadanie: otvorte tiket Údaje a napíšte nám, ktoré priechody, aké časové okno a na aký účel. Po schválení sa vo vašom účte objaví záložka Export údajov. Predvolený limit: 1 export/deň, každý najviac 5 priechodov — požiadajte nás o navýšenie.

Polia — jeden riadok na priechod a UTC hodinu

Exportujú sa len zverejnené údaje, ktoré prejdú našimi kontrolami anomálií a kvality (žiadne surové údaje z jednotlivých hlásení). Všetky časové značky sú v UTC. Súbory uchovávame 10 dní.

Pôvod: každý súbor má v hlavičke vložený podpísaný odtlačok (sha256 + HMAC), takže o ľubovoľnej kópii sa dá neskôr potvrdiť, že ide o pravé údaje nakordoni.eu, a overiť, či nebola pozmenená — aj po stiahnutí.

# sha256: 3f9c…   # signature: e87b…
ppid,checkpoint_name,hour_utc,direction,vehicle_type,avg_queue_length,avg_wait_minutes,sample_count
id_10,Hrushiv,2026-06-12T02:00:00Z,UA->PL,car,11,,4

Čo môžete vytvoriť

Tie isté dátové produkty vykresľujú vizuály na nakordoni.eu — grafy týždenných predpovedí, hodinové profily radov, živé stavové karty. Ukážka toho, čo obsahujú API predpovedí a štatistík:

Uvedenie zdroja

Integrácie plánu Explorer musia zobrazovať viditeľný odkaz „Data by nakordoni.eu“ všade, kde sa údaje zobrazujú. Vďaka tomu zostáva bezplatný plán bezplatný.

Presný kód

Skopírujte tento úryvok bez zmien. Odkaz musí zostať indexovateľný: viditeľný, jednoduchý HTML odkaz <a href> vedľa údajov, ktorý môže Google indexovať a nasledovať — NEPRIDÁVAJTE rel="nofollow", rel="sponsored" ani rel="ugc" a neskrývajte ho cez CSS. Odkaz pridaný cez JavaScript je v poriadku, ak sa zobrazí na stránke, ktorú Google vykreslí (Podmienky Developer API v1.0, časť 8.1).

<a href="https://nakordoni.eu/" title="Border queues, forecasts &amp; statistics">Data by nakordoni.eu</a>

Kompaktný drobný variant (napr. pod grafom alebo widgetom):

<p style="font-size:12px;margin:4px 0">
  Data by <a href="https://nakordoni.eu/">nakordoni.eu</a>
</p>

Môžete odkazovať na svoju jazykovú verziu, napr. https://nakordoni.eu/sk/ — počíta sa akýkoľvek viditeľný bežný HTML odkaz na nakordoni.eu. Text odkazu "Data by nakordoni.eu" musí zostať v angličtine.

Kde umiestniť

• Priamo vedľa alebo pod blokom dát (tabuľka, graf, widget, odpoveď) — na rovnakej obrazovke, viditeľné bez ďalších klikov.
• Na každej stránke alebo obrazovke aplikácie, kde sa zobrazujú naše dáta — nielen na stránke "o nás".
• Čitateľná veľkosť a kontrast: aspoň ~11px, neskryté, nezbalené, nie vo farbe pozadia.
• Natívne mobilné aplikácie bez HTML odkazov: zobrazte text "Data by nakordoni.eu" na obrazovke s dátami a klikateľný odkaz umiestnite na informačnú obrazovku.

Atribúciu pravidelne overujeme na "stránke, kde sa údaje používajú", ktorú ste uviedli pri registrácii. Chýbajúca alebo skrytá atribúcia v bezplatnom pláne Explorer vedie najprv k pripomienke, potom k pozastaveniu kľúča. Zákazníci s plateným plánom môžu atribúciu vynechať.

Kontrola prebieha zhruba raz týždenne prostredníctvom nášho overovacieho robota, ktorého user agent obsahuje NakordoniComplianceBot/1.0. Otvára len stránky uvedené vo vašom paneli vývojára, nesleduje ďalšie odkazy a pri týchto stránkach ignoruje robots.txt, pretože práve ich ste nás požiadali kontrolovať. Ak ochrana proti botom alebo firewall blokuje neznáme crawlery, povoľte tento user agent — ak stránku neotvoríme, napíšeme vám v tikete.

Licencia dát a trhy

Váš API kľúč udeľuje licenciu na použitie našich dát iba v krajinách, ktoré ste deklarovali pri registrácii. Každú deklaráciu overujeme pred udelením plného prístupu, pretože naše dáta sú náš vlastný produkt a nelicencujeme ich na trhy bez toho, aby sme vedeli, kde budú zverejnené.

• Deklarujte každú krajinu, ktorú obsluhuje váš web, aplikácia alebo produkt. Zoznam môžete kedykoľvek zmeniť v paneli; zmena vráti váš účet do kontroly.
• Kým vaše trhy nie sú schválené, kľúč beží so zníženými limitmi — polovicou limitu plánu Starter. Platí to bez ohľadu na to, aký plán máte.
• Môžeme schváliť len niektoré z krajín, ktoré ste požiadali. Schválený zoznam, nie ten požiadaný, určuje, ktoré krajiny pokrýva vaša licencia.
• Zverejnenie alebo ďalšie šírenie našich dát na nedeklarovanom trhu, alebo ich ďalší predaj ako konkurenčný dátový tok, porušuje tieto podmienky a môže bez upozornenia pozastaviť váš kľúč.
• Niektoré plány sú dostupné iba vo vybraných regiónoch. Dostupnosť závisí od trhov, ktoré deklarujete.
• Úplnou dohodou sú Podmienky Developer API. Majú prednosť pred týmto zhrnutím; záväzná je anglická verzia.

Aktualita údajov

Aktuálnosť vašich údajov závisí od vášho plánu. V samotnej odpovedi nie je žiadne označenie — každý plán vracia rovnaké polia, rovnaké typy a rovnakú štruktúru odpovede.

• Platené plány — Student, Starter, Pro a Pro MAX: živá telemetria, bez oneskorenia.
• Bezplatný plán Explorer: snímka za posledných 15 až 30 minút. Presný posun sa líši od požiadavky k požiadavke.

Oneskorená odpoveď nikdy nie je chyba ani problém s limitom — je to úplná, platná odpoveď so staršími číslami. Opakovanie požiadavky novšie údaje nevráti.

Ak vaša aplikácia potrebuje aktuálne údaje, každý platený plán vracia telemetriu v reálnom čase.

Získajte svoj bezplatný API kľúč