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ă.

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

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

Your Fleet (NakBus Live)

Asistent AI

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 gratuit Explorer duce mai întâi la o reamintire, apoi la suspendarea cheii. Clienții cu un plan cu plată pot omite atribuirea.

Licența datelor și piețe

Your API key grants a licence to use our data in the countries you declared when you signed up, and only in those countries. We review every declaration before granting full access, because our data is our own product and we do not license it into markets without knowing where it will be published.

• Declare every country your site, app or product serves. You can change the list from your dashboard at any time; a change puts your account back into review.
• Until your markets are approved your key runs on reduced limits - half of the Starter plan allowance. This applies whatever plan you are on.
• 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.
• Publishing or redistributing our data in a market you did not declare, or reselling it as a competing data feed, is a breach of these terms and can suspend your key without notice.
• Some plans are offered only in selected regions. Availability depends on the markets you declare.

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ă