Documentație API

Autentificare

Fiecare cerere are nevoie de cheia ta API în antetul Authorization (recomandat) sau ca parametru ?key=.

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

Structura răspunsului

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

Erorile returnează ok:false cu 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) și status HTTP 400/401/403/404/429/500/503/504. Anteturile de limitare a ratei X-Devapi-Limit și X-Devapi-Remaining sunt trimise la fiecare răspuns contorizat. ok:false este determinant — nu citiți niciodată data la un apel eșuat. Obiectul usage este prezent în fiecare produs contorizat; /status este public și necontorizat, deci nu returnează usage.

Cote

Contoarele zilnice se resetează la miezul nopții UTC. Primești un email la 80% și 100% din cotă.

Planurile plătite ridică fiecare dintre aceste limite. Planurile actuale și limitele lor: Planuri

Mostre de cod

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)

Preluați date live despre cozi, prognoze sau interdicții pentru camioane direct într-un registru de lucru cu conectorul JSON încorporat al Power Query — fără cod, cu reîmprospătare programată. Același model de Headers funcționează pentru orice produs din acest API — schimbați doar URL-ul.

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

Păstrați cheia API în interiorul interogării M (Home → Advanced Editor), nu într-o celulă a foii de calcul — Power Query blochează o solicitare web construită dintr-o altă interogare sau celulă ("Formula.Firewall"), decât dacă nivelul de confidențialitate este setat la Organizational.

Mai multe puncte de trecere într-un singur tabel (dashboard-uri de flotă) — 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 în Excel sau o reîmprospătare programată în Power BI / Excel Online menține datele actualizate — fără cod de polling.

Integrare ERP (BAS / BAF și platforme din familia 1C)

BAS / BAF și alte platforme din familia 1C pot apela acest API direct dintr-o sarcină programată — HTTPConnection plus ReadJSON, fără middleware și fără serviciu suplimentar de găzduit. Cel mai frecvent scenariu ține la zi un registru de informații cu prețurile carburanților din UE.

Actualizarea unui registru de informații (prețuri carburanți, toate țările într-un singur apel)

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

Trei lucruri de făcut corect: transmiteți New OpenSSLSecureConnection pe portul 443, altfel cererea cade pe TLS; apelați /api/v1/data/fuel fără parametrul country, ca o singură cerere să întoarcă toate țările în loc de un apel pe fiecare țară; și verificați ok înainte de a atinge data — erorile revin ca ok:false cu error.code, nu ca excepție. Exemplul folosește setul englez de cuvinte-cheie al platformei; echivalentele localizate (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) se comportă identic.

Prețurile carburanților se schimbă la sursă o dată pe zi, așa că o sarcină programată o dată sau de două ori pe zi este suficientă și rămâne mult sub cota gratuită Explorer. Datele de coadă în timp real (queue, multi, border) se schimbă la câteva minute — interogați-le după propriul ritm și folosiți multi ca să citiți până la 5 de puncte de trecere într-o singură cerere, în loc de buclă.

Server MCP

Preferați apelarea de instrumente în locul REST? Rulăm un server MCP real (transport Streamable HTTP), care expune un subset sigur, doar pentru citire, al acestui API sub formă de instrumente MCP — aceeași cheie API, aceeași cotă, doar un transport diferit.

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

Configurare client (Claude Desktop / Claude Code):

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

OAuth pentru integrări (Home Assistant și altele)

Integrările ai căror utilizatori au nevoie fiecare de propria cheie (integrări personalizate Home Assistant, aplicații desktop și mobile) pot lăsa utilizatorul să se autentifice în loc să lipească o cheie. Fluxul este OAuth 2.0 authorization code pentru clienți publici cu PKCE (S256) — nu există client secret. Tokenul de acces returnat de noi este propria cheie NKD-DEV a utilizatorului, pe care o trimiți apoi ca antet Bearer exact ca până acum.

Clienții nu se creează singur: solicită unul pe pagina Integrări, verificăm manual fiecare integrare și emitem un client ID cu URI-urile de redirecționare permise. Cheile emise printr-un client aprobat sunt activate instant pentru piețele aprobate acelei integrări. Solicită un client de integrare →

• Codul de autorizare este valabil 60 de secunde, de unică folosință și legat de client, utilizator, URI-ul de redirecționare și PKCE challenge.
• Cheia este returnată doar în corpul răspunsului cu token (access_token) — niciodată într-un URL. Păstrează-o ca pe o parolă.
• expires_in este de 30 de zile; o reîmprospătare returnează aceeași cheie cât timp este activă. Dacă utilizatorul revocă sau regenerează cheia, reîmprospătarea eșuează cu invalid_grant, iar apelurile API returnează 401 — pornește reautentificarea.
• Cererile au limită de frecvență per IP și plafon zilnic per client; erorile respectă RFC 6749 (error, error_description).
• Fiecare utilizator primește cel mult propria alocare de țări: dacă integrarea are mai multe țări decât locurile libere ale utilizatorului, acesta le alege pe pagina de consimțământ (trimiteți markets=DE,AT la /oauth/authorize pentru preselecție). Ambele răspunsuri token returnează și markets_approved (țările aprobate ale utilizatorului), markets_allowed (alocarea sa; null = nelimitat), markets_available (țările dvs. pe care încă nu le are) și upgrade_url (unde adaugă „Țări suplimentare”).

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

Folosește config_entry_oauth2_flow cu LocalOAuth2ImplementationWithPkce (client_secret gol) și URI-ul de redirecționare https://my.home-assistant.io/redirect/oauth, preînregistrat pentru clienții Home Assistant. Citește cheia din entry.data["token"]["access_token"] și continuă să apelezi API-ul cu Authorization: Bearer. La un 401 de la API, ridică ConfigEntryAuthFailed pentru ca Home Assistant să ofere reautentificarea.

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ări: afișați limitele rămase

GET /api/v2/account/usage — Cât a rămas din limitele dvs. chiar acum, pentru cheia cu care apelați: plan, limită pe secundă și pentru fiecare clasă de cotă zilnică (cheap, heavy, route) limita, consumul, restul și ora resetării (miezul nopții UTC); plus țările dvs. așa cum le vede această cheie și unde faceți upgrade. Necontorizat, 30 de apeluri pe minut per cheie.

Cheile de integrare (OAuth) pot apela oricând GET /api/v2/account/usage, indiferent de produsele permise integrării. Cifrele corespund antetelor X-Devapi-Limit și X-Devapi-Remaining; X-Devapi-Reset dă ora resetării ca timestamp Unix.

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

Când o limită este atinsă, eroarea spune unde să mergi: 429 quota_exceeded returnează și error.reset_at (miezul nopții UTC) și error.upgrade_url; 403 market_not_allowed și 403 integration_product_not_allowed returnează error.upgrade_url. Cheile de integrare primesc și error.pass_url (Trip Pass, mai jos).

Home Assistant: interogați /account/usage cel mult o dată la 15 minute și expuneți un senzor „apeluri rămase” din quotas.cheap.remaining. Între interogări citiți X-Devapi-Remaining din apelurile obișnuite. La 429 quota_exceeded sau 403 market_not_allowed creați un repair issue cu link către error.upgrade_url și opriți apelurile până la reset_at.

Trip Pass

Utilizatorii integrărilor pot cumpăra un Trip Pass (1, 3, 7 sau 14 zile, plată unică) pe pagina de facturare. Cât timp este activ, cheia de integrare primește toate țările integrării, mai multe apeluri de rută camion și de date pe zi și o rată mai mare; produsele integrării, limitele de prognoză și întârzierea datelor nu se schimbă. Cheile de dezvoltator ale aceluiași cont nu sunt ridicate niciodată.

Pentru cheile de integrare, account/usage returnează pass: {active, expires_at, days_left} și pass_url (secțiunea Trip Pass a paginii de facturare); 429 quota_exceeded și 403 market_not_allowed / integration_product_not_allowed conțin același error.pass_url. Pentru alte chei ambele sunt 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.

Produse

Alege un endpoint pentru referința completă, parametri, versiuni și un sandbox live.

Standard folosește cota standard de date  ·  Greu folosește cota de prognoză și statistică — vezi Cote  ·  Rută pentru camioane consumă din propria cotă de rute pentru camioane — vezi Cote

Cozi la frontieră

Prognoze și statistici

Combustibil și locații

Case de schimb valutar

Planificarea călătoriei

Logistică

Șoferi și drumuri

Your Fleet (NakBus Live)

Asistent AI

Altele

Export de date istorice

Dezvoltatorii aprobați pot descărca istoricul publicat al cozilor la frontieră, mediat pe oră, pentru până la 5 puncte de trecere (fereastră glisantă de până la 90 de zile), în format CSV comprimat gzip, NDJSON sau JSON. Este o funcție disponibilă doar în portal — NU un endpoint API; construiești și descarci exporturile din fila „Export de date” din contul tău.

Accesul se acordă la cerere: deschide un tichet Date în care ne spui ce puncte de trecere te interesează, intervalul de timp și scopul utilizării. După aprobare, fila Export de date apare în contul tău. Limită implicită: 1 export/zi, până la 5 puncte de trecere fiecare — cere-ne să o mărim.

Câmpuri — un rând per punct de trecere pentru fiecare oră UTC

Sunt exportate doar date publicate, care trec verificările noastre de anomalii și de calitate (fără date brute per raportare). Toate marcajele de timp sunt UTC. Fișierele se păstrează 10 zile.

Proveniență: fiecare fișier include în antet o amprentă semnată (sha256 + HMAC), astfel încât orice copie poate fi confirmată ulterior ca date autentice nakordoni.eu și verificată pentru modificări — chiar și după descărcare.

# 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

Ce poți construi

Aceleași produse de date redau elementele vizuale de pe nakordoni.eu — grafice de prognoză săptămânală, profiluri orare ale cozilor, carduri de stare în timp real. O mostră a ceea ce conțin API-urile de prognoză și statistici:

Atribuire

Integrările din planul Explorer trebuie să afișeze un link vizibil „Data by nakordoni.eu” oriunde sunt afișate datele. Astfel planul gratuit rămâne gratuit.

Codul exact

Copiați acest fragment așa cum este. Linkul trebuie să rămână indexabil: un <a href> HTML vizibil și simplu lângă date, pe care Google îl poate indexa și urma — NU adăugați rel="nofollow", rel="sponsored" sau rel="ugc" și nu-l ascundeți prin CSS. Un link adăugat prin JavaScript este în regulă dacă apare pe pagina randată de Google (Termenii Developer API v1.0, secțiunea 8.1).

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

Variantă compactă cu litere mici (de ex. sub un grafic sau widget):

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

Puteți face link către versiunea în limba dumneavoastră, de ex. https://nakordoni.eu/ro/ — contează orice link HTML simplu și vizibil către nakordoni.eu. Textul ancorei "Data by nakordoni.eu" trebuie să rămână în engleză.

Unde se plasează

• Direct lângă sau sub blocul de date (tabel, grafic, widget, răspuns) — pe același ecran, vizibil fără clicuri suplimentare.
• Pe fiecare pagină sau ecran de aplicație unde apar datele noastre — nu doar pe pagina "despre".
• Dimensiune și contrast lizibile: cel puțin ~11px, neascuns, nepliat, nu în culoarea fundalului.
• Aplicații mobile native fără linkuri HTML: afișați textul "Data by nakordoni.eu" pe ecranul cu date și puneți linkul accesibil pe ecranul de informații.

Verificăm periodic atribuirea pe "pagina unde sunt folosite datele" indicată la înregistrare. Atribuirea lipsă sau ascunsă în planul gratuit Explorer duce mai întâi la o notificare, apoi la suspendarea cheii. Clienții cu plan plătit pot omite atribuirea.

Verificările au loc aproximativ o dată pe săptămână, prin verificatorul nostru, al cărui user agent conține NakordoniComplianceBot/1.0. Acesta deschide doar paginile listate în panoul de dezvoltator, nu urmează alte linkuri și ignoră robots.txt pentru acele pagini, deoarece pe ele ne-ați cerut să le verificăm. Dacă protecția anti-bot sau un firewall blochează crawlerele necunoscute, permiteți acest user agent — dacă nu putem deschide o pagină, vă scriem printr-un tichet.

Licența datelor și piețe

Cheia dvs. API acordă o licență de utilizare a datelor noastre doar în țările declarate la înregistrare. Analizăm fiecare declarație înainte de a acorda acces complet, deoarece datele noastre sunt propriul nostru produs și nu le licențiem pe piețe fără să știm unde vor fi publicate.

• Declarați fiecare țară pe care o deservește site-ul, aplicația sau produsul dvs. Puteți modifica lista oricând din panoul de control; o modificare readuce contul dvs. în analiză.
• Până la aprobarea piețelor dvs., cheia funcționează cu limite reduse - jumătate din alocația planului Starter. Acest lucru se aplică indiferent de planul dvs.
• Este posibil să aprobăm doar unele dintre țările pe care le-ați solicitat. Lista aprobată, nu cea solicitată, este cea care acoperă țările incluse în licența dvs.
• Publicarea sau redistribuirea datelor noastre pe o piață nedeclarată, sau revânzarea lor ca flux de date concurent, încalcă acești termeni și poate suspenda cheia dvs. fără notificare prealabilă.
• Unele planuri sunt oferite doar în anumite regiuni. Disponibilitatea depinde de piețele pe care le declarați.
• Acordul complet îl reprezintă Termenii Developer API. Aceștia au prioritate față de acest rezumat; versiunea obligatorie este cea în limba engleză.

Prospețimea datelor

Cât de recente sunt datele depinde de planul dumneavoastră. Nu există niciun marcaj în răspuns — toate planurile returnează aceleași câmpuri, aceleași tipuri și aceeași structură a răspunsului.

• Planurile plătite — Student, Starter, Pro și Pro MAX: telemetrie în direct, fără întârziere.
• Planul gratuit Explorer: un instantaneu din ultimele 15–30 de minute. Decalajul exact variază de la o cerere la alta.

Un răspuns întârziat nu este niciodată o eroare și nici o problemă de cotă — este un răspuns complet și valid, cu cifre mai vechi. Reluarea cererii nu aduce date mai noi.

Dacă aplicația dumneavoastră are nevoie de date curente, orice plan plătit returnează telemetrie în timp real.

Obține cheia API gratuită