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",
  "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, bad_request, internal_error) și status HTTP 401/403/404/429/500. Anteturile de limitare a ratei X-Devapi-Limit și X-Devapi-Remaining sunt trimise la fiecare răspuns contorizat.

Cote

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

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→EU (crossing_type=9):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/border/1/all/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 20 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" }
    }
  }
}

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

Cozi la frontieră

Prognoze și statistici

Combustibil și locații

Planificarea călătoriei

Șoferi și drumuri

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 ca atare. Linkul trebuie să rămână indexabil: un HTML <a href> simplu pe care motoarele de căutare îl pot urmări — NU adăugați rel="nofollow" sau rel="sponsored", nu îl redați doar prin JavaScript și nu îl ascundeți prin CSS.

<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 dvs. lingvistică, de ex. https://nakordoni.eu/ro/ — contează orice link indexabil 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 de utilizare a datelor" indicată la înregistrare. Lipsa sau deindexarea atribuirii în planul Explorer duce mai întâi la o reamintire, apoi la suspendarea cheii. Clienții Pay As You Grow pot omite atribuirea.

Obține cheia API gratuită