API-dokumentáció

Hitelesítés

Minden kérésnek tartalmaznia kell az API-kulcsodat az Authorization fejlécben (ajánlott) vagy ?key= paraméterként.

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

Válaszburok

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

A hibák ok:false választ adnak error.code értékkel (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) és 400/401/403/404/429/500/503/504 HTTP-státusszal. Az X-Devapi-Limit és X-Devapi-Remaining sebességkorlát-fejléceket minden mért válaszban elküldjük. Az ok:false a mérvadó — sikertelen hívásnál soha ne dolgozza fel a data mezőt. A usage objektum minden díjköteles termékben szerepel; a /status nyilvános és díjmentes, ezért nem ad vissza usage mezőt.

Kvóták

A napi számlálók éjfélkor (UTC) nullázódnak. A kvóta 80%-ánál és 100%-ánál e-mailt kapsz.

A fizetős csomagok mindegyik korlátot megemelik. Az aktuális csomagok és kereteik: Csomagok

Kódminták

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)

Kérjen le élő sorállási, előrejelzési vagy teherautó-tilalmi adatokat közvetlenül egy munkafüzetbe a Power Query beépített JSON-konnektorával — kód nélkül, ütemezett frissítéssel. Ugyanaz a Headers-minta minden API-termékhez működik — csak az URL-t kell módosítani.

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

Az API-kulcsot az M-lekérdezésen belül tárolja (Home → Advanced Editor), ne egy munkalapcellában — a Power Query blokkolja a más lekérdezésből vagy cellából épített webes kérést ("Formula.Firewall"), hacsak az adatvédelmi szint nincs Organizational-ra állítva.

Több határátkelő egy táblázatban (flottapanelek) — 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

A Data → Refresh All az Excelben, vagy egy ütemezett frissítés a Power BI-ban / Excel Online-ban naprakészen tartja az adatokat — lekérdező (polling) kód nélkül.

ERP-integráció (BAS / BAF és 1C-családú platformok)

A BAS / BAF és a többi 1C-családú platform közvetlenül egy ütemezett feladatból hívhatja ezt az API-t — HTTPConnection és ReadJSON, köztes réteg és külön szolgáltatás nélkül. A leggyakoribb megoldás egy információs regisztert tart naprakészen az uniós üzemanyagárakkal.

Információs regiszter frissítése (üzemanyagárak, minden ország egyetlen hívásban)

// 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;

Három dolgot kell eltalálni: adja át a New OpenSSLSecureConnection értéket a 443-as porton, különben a kérés elhasal a TLS-en; a /api/v1/data/fuel végpontot country paraméter nélkül hívja, így egyetlen kérés minden országot visszaad, ország per hívás helyett; és ellenőrizze az ok mezőt, mielőtt a data mezőhöz nyúlna — a hibák ok:false formában, error.code kóddal érkeznek, nem kivételként. A minta a platform angol kulcsszókészletét használja; a honosított megfelelők (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) ugyanúgy működnek.

Az üzemanyagárak a forrásnál naponta egyszer változnak, ezért egy napi egy- vagy kétszeri ütemezett feladat bőven elég, és messze az ingyenes Explorer kereten belül marad. Az élő sorállási adatok (queue, multi, border) percenként változnak — ezeket saját ütem szerint kérdezze le, és a multi végponttal olvasson be akár 5 határátkelőt egyetlen kérésben, ciklus helyett.

MCP-szerver

Inkább eszközhívást használna REST helyett? Egy valódi MCP-szervert (Streamable HTTP átvitel) üzemeltetünk, amely ennek az API-nak egy biztonságos, csak olvasható részhalmazát MCP-eszközökként teszi elérhetővé — ugyanaz az API-kulcs, ugyanaz a kvóta, csak más átvitel.

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

Kliens konfiguráció (Claude Desktop / Claude Code):

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

OAuth integrációkhoz (Home Assistant és mások)

Azok az integrációk, amelyeknél minden felhasználónak saját kulcs kell (Home Assistant egyedi integrációk, asztali és mobilalkalmazások), kulcs beillesztése helyett bejelentkeztethetik a felhasználót. A folyamat OAuth 2.0 authorization code nyilvános kliensekhez PKCE-vel (S256) — nincs client secret. Az általunk visszaadott hozzáférési token a felhasználó saját NKD-DEV kulcsa, amelyet a szokásos módon Bearer fejlécben küldesz.

A kliensek nem önkiszolgálóak: igényeld az Integrációk oldalon, minden integrációt kézzel ellenőrzünk, és client ID-t adunk ki az engedélyezett átirányítási URI-kkal. A jóváhagyott kliensen keresztül kiadott kulcsok azonnal aktiválódnak az adott integrációhoz jóváhagyott piacokra. Integrációs kliens igénylése →

• Az authorization code 60 másodpercig érvényes, egyszer használható, és a klienshez, a felhasználóhoz, az átirányítási URI-hoz és a PKCE challenge-hez van kötve.
• A kulcsot kizárólag a token válasz törzse (access_token) adja vissza — soha nem URL-ben. Kezeld jelszóként.
• Az expires_in értéke 30 nap; a frissítés ugyanazt a kulcsot adja vissza, amíg az aktív. Ha a felhasználó visszavonja vagy újragenerálja a kulcsot, a frissítés invalid_grant hibával elbukik, az API-hívások pedig 401-et adnak — indítsd el az újrahitelesítést.
• A kérések IP-nként sebességkorlátozottak, kliensenként pedig naponta korlátozottak; a hibák az RFC 6749 szerintiek (error, error_description).
• Minden felhasználó legfeljebb a saját országkeretét kapja: ha az integráció több országot tartalmaz, mint ahány szabad helye van, a hozzájárulási oldalon választ (a /oauth/authorize markets=DE,AT paramétere előre kijelöli őket). Mindkét token-válasz visszaadja a markets_approved (a felhasználó jóváhagyott országai), markets_allowed (kerete; null = korlátlan), markets_available (az Ön országai, amelyek még nincsenek meg neki) és upgrade_url (ahol „Extra országokat” adhat hozzá) mezőt is.

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

Használd a config_entry_oauth2_flow-t a LocalOAuth2ImplementationWithPkce-vel (client_secret üres) és a https://my.home-assistant.io/redirect/oauth átirányítási URI-val, amely előre regisztrált a Home Assistant kliensekhez. Olvasd ki a kulcsot az entry.data["token"]["access_token"]-ből, és továbbra is Authorization: Bearer fejléccel hívd az API-t. Ha az API 401-et ad, emeld a ConfigEntryAuthFailed-et, hogy a Home Assistant újrahitelesítést ajánljon fel.

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ációk: a fennmaradó keretek megjelenítése

GET /api/v2/account/usage — Mennyi maradt most a kereteiből a hívó kulcsnál: csomag, másodpercenkénti korlát, és minden napi kvótaosztályra (cheap, heavy, route) a keret, felhasznált, maradék és a nullázás ideje (éjfél UTC); továbbá az országai, ahogy ez a kulcs látja, és hol válthat nagyobb csomagra. Nem számít bele, kulcsonként percenként 30 hívás.

Az integrációs (OAuth) kulcsok mindig hívhatják a GET /api/v2/account/usage végpontot, függetlenül attól, milyen termékeket enged az integráció. A számok megegyeznek az X-Devapi-Limit és X-Devapi-Remaining fejlécekkel; az X-Devapi-Reset Unix időbélyegként adja meg a nullázás idejét.

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

Ha elér egy korlátot, a hiba megmondja, hová menjen: a 429 quota_exceeded visszaadja az error.reset_at (éjfél UTC) és az error.upgrade_url mezőt is; a 403 market_not_allowed és a 403 integration_product_not_allowed az error.upgrade_url-t adja vissza. Az integrációs kulcsok error.pass_url-t is kapnak (Trip Pass, lent).

Home Assistant: a /account/usage végpontot legfeljebb 15 percenként kérdezze le, és adjon „maradék hívások” szenzort a quotas.cheap.remaining alapján. A lekérdezések között a normál hívások X-Devapi-Remaining fejlécét olvassa. 429 quota_exceeded vagy 403 market_not_allowed esetén hozzon létre repair issue-t error.upgrade_url linkkel, és szüneteltesse a hívásokat reset_at-ig.

Trip Pass

Az integrációk felhasználói a számlázási oldalon vásárolhatnak Trip Passt (1, 3, 7 vagy 14 nap, egyszeri fizetés). Amíg aktív, az integrációs kulcs megkapja az integráció összes országát, több napi kamionútvonal- és adathívást és magasabb kérésszámot; az integráció termékei, az előrejelzési korlátok és az adatkésleltetés nem változnak. Ugyanazon fiók fejlesztői kulcsai soha nem emelkednek.

Integrációs kulcsoknál az account/usage visszaadja a pass: {active, expires_at, days_left} és a pass_url mezőt (a számlázási oldal Trip Pass része); a 429 quota_exceeded és a 403 market_not_allowed / integration_product_not_allowed ugyanazt az error.pass_url-t tartalmazza. Más kulcsoknál mindkettő 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.

Termékek

Válassz egy végpontot a teljes referenciához, a paraméterekhez, a verziókhoz és az élő sandboxhoz.

Alapvető a standard adatkvótát használja  ·  Nehéz a prognózis és statisztikai kvóta alapján — lásd Kvóták  ·  Teherautós útvonal saját teherautós útvonal-kvótából fogyaszt — lásd Kvóták

Határvárakozás

Előrejelzések és statisztikák

Üzemanyag és helyszínek

Pénzváltók

Utazástervezés

Logisztika

Sofőrök és utak

Your Fleet (NakBus Live)

AI Asszisztens

Egyéb

Történeti adatok exportja

A jóváhagyott fejlesztők legfeljebb 5 határátkelőre letölthetik az óránként átlagolt, közzétett határsor-előzményeket (legfeljebb 90 napos gördülő ablak) gzippelt CSV, NDJSON vagy JSON formátumban. Ez kizárólag portálfunkció — NEM API-végpont; az exportokat a fiókod „Adatexport” fülén állítod össze és töltöd le.

A hozzáférést kérésre adjuk meg: nyiss egy Adat jegyet, és írd meg, mely határátkelőkre, milyen időszakra és milyen célra van szükséged. Jóváhagyás után az Adatexport fül megjelenik a fiókodban. Alapértelmezett korlát: napi 1 export, egyenként legfeljebb 5 határátkelővel — kérésre megemeljük.

Mezők — határátkelőnként és UTC-óránként egy sor

Kizárólag közzétett adatokat exportálunk, amelyek átmennek az anomália- és adatminőség-ellenőrzéseinken (nyers, bejelentésenkénti adat nincs). Minden időbélyeg UTC. A fájlokat 10 napig őrizzük meg.

Eredet: minden fájl fejléce tartalmaz egy aláírt ujjlenyomatot (sha256 + HMAC), így bármelyik másolatról később igazolható, hogy valódi nakordoni.eu adat, és ellenőrizhető, nem módosították-e — még letöltés után is.

# 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

Mit építhetsz

Ugyanezek az adattermékek jelenítik meg a nakordoni.eu vizuális elemeit — heti előrejelzési diagramokat, óránkénti sorprofilokat, élő státuszkártyákat. Ízelítő abból, amit az előrejelzési és statisztikai API-k tartalmaznak:

Forrásmegjelölés

Az Explorer csomagú integrációknak látható „Data by nakordoni.eu” hivatkozást kell megjeleníteniük mindenhol, ahol az adatok megjelennek. Ez tartja ingyenesen az ingyenes csomagot.

A pontos kód

Másolja be ezt a kódrészletet változtatás nélkül. A linknek indexelhetőnek kell maradnia: egy látható, egyszerű HTML <a href> az adatok mellett, amelyet a Google indexelni és követni tud — NE adjon hozzá rel="nofollow", rel="sponsored" vagy rel="ugc" attribútumot, és ne rejtse el CSS-sel. A JavaScripttel beszúrt link is megfelelő, ha megjelenik a Google által renderelt oldalon (Developer API Feltételek v1.0, 8.1. szakasz).

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

Kompakt, apróbetűs változat (pl. diagram vagy widget alatt):

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

Hivatkozhat a saját nyelvi változatra is, pl. https://nakordoni.eu/hu/ — bármely látható, egyszerű HTML link a nakordoni.eu felé megfelel. A "Data by nakordoni.eu" horgonyszövegnek angolul kell maradnia.

Hová helyezze

• Közvetlenül az adatblokk mellé vagy alá (táblázat, diagram, widget, válasz) — ugyanazon a képernyőn, külön kattintás nélkül láthatóan.
• Minden oldalon vagy alkalmazás-képernyőn, ahol adataink megjelennek — nem csak egy "rólunk" oldalon.
• Olvasható méret és kontraszt: legalább ~11px, nem rejtett, nem összecsukott, nem háttérszínű.
• HTML-linkek nélküli natív mobilappok: jelenítse meg a "Data by nakordoni.eu" szöveget az adatképernyőn, a kattintható linket pedig az infó képernyőre tegye.

Rendszeresen ellenőrizzük az attribúciót a regisztrációkor megadott "az adatokat használó oldalon". A hiányzó vagy elrejtett attribúció az ingyenes Explorer csomagban először figyelmeztetést, majd a kulcs felfüggesztését vonja maga után. A fizetős csomagok ügyfelei elhagyhatják az attribúciót.

Az ellenőrzés nagyjából hetente egyszer történik az ellenőrzőnkkel, amelynek user agentje tartalmazza a NakordoniComplianceBot/1.0 azonosítót. Csak a fejlesztői felületén felsorolt oldalakat nyitja meg, más linkeket nem követ, és ezeknél az oldalaknál figyelmen kívül hagyja a robots.txt-t, mert éppen ezek ellenőrzését kérte. Ha botvédelem vagy tűzfal tiltja az ismeretlen crawlereket, engedélyezze ezt a user agentet — ha egy oldalt nem tudunk megnyitni, jegyben írunk Önnek.

Adatlicenc és piacok

API-kulcsa kizárólag azokban az országokban jogosít fel adataink használatára, amelyeket a regisztrációkor megadott. Minden nyilatkozatot megvizsgálunk, mielőtt teljes hozzáférést biztosítanánk, mert adataink saját termékünk, és nem licenceljük piacokra anélkül, hogy tudnánk, hol jelenik meg.

• Jelentse be minden országot, amelyet webhelye, alkalmazása vagy terméke kiszolgál. A listát bármikor módosíthatja az irányítópultján; a módosítás visszahelyezi fiókját elbírálásra.
• Amíg piacai jóváhagyásra nem kerülnek, kulcsa csökkentett limitekkel fut — a Starter csomag keretének felével. Ez bármely csomagra vonatkozik, amelyet használ.
• Csak néhány, az általad megadott országot engedélyezhetjük. Az engedélyezett lista, nem pedig a kért lista határozza meg, hogy mely országokat fedik le a licenced.
• Adataink közzététele vagy továbbterjesztése be nem jelentett piacon, illetve versengő adatfolyamként történő továbbértékesítése megsérti ezeket a feltételeket, és figyelmeztetés nélkül felfüggesztheti kulcsát.
• Egyes csomagok csak bizonyos régiókban érhetők el. A rendelkezésre állás az Ön által megadott piacoktól függ.
• A teljes megállapodás a Developer API Feltételek. Ez elsőbbséget élvez ezzel az összefoglalóval szemben; a kötelező érvényű változat az angol.

Adatok frissessége

Az adatok frissessége a csomagjától függ. A válaszban nincs erre vonatkozó jelölés — minden csomag ugyanazokat a mezőket, ugyanazokat a típusokat és ugyanazt a válaszszerkezetet adja vissza.

• Fizetős csomagok — Student, Starter, Pro és Pro MAX: élő telemetria, késleltetés nélkül.
• Ingyenes Explorer csomag: pillanatkép az elmúlt 15–30 percből. A pontos eltolás kérésenként változik.

A késleltetett válasz soha nem hiba és nem kvótaprobléma — teljes értékű, érvényes válasz, csak régebbi számokkal. Az ismételt lekérdezés nem ad frissebb adatot.

Ha az alkalmazásának aktuális adatokra van szüksége, bármelyik fizetős csomag valós idejű telemetriát ad.

Szerezd meg ingyenes API-kulcsod