Documentazione dell'API

Autenticazione

Ogni richiesta necessita della tua chiave API nell'header Authorization (consigliato) o come parametro ?key=.

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

Envelope di risposta

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

Gli errori restituiscono ok:false con 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) e stato HTTP 400/401/403/404/429/500/503/504. Gli header di rate-limit X-Devapi-Limit e X-Devapi-Remaining vengono inviati a ogni risposta conteggiata. ok:false fa fede — non leggere mai data in una chiamata fallita. L'oggetto usage è presente in ogni prodotto tariffato; /status è pubblico e non tariffato, quindi non restituisce usage.

Quote

I contatori giornalieri si azzerano a mezzanotte UTC. Ricevi un'e-mail all'80% e al 100% della quota.

I piani a pagamento alzano ognuno di questi limiti. Piani attuali e relative soglie: Piani

Esempi di codice

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)

Importa dati live su code, previsioni o divieti per i camion direttamente in una cartella di lavoro con il connettore JSON integrato di Power Query — senza codice, con aggiornamento pianificato. Lo stesso schema di Headers funziona per ogni prodotto di questa API — basta cambiare l'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

Conserva la chiave API all'interno della query M (Home → Advanced Editor), non in una cella del foglio — Power Query blocca una richiesta web costruita da un'altra query o cella ("Formula.Firewall"), a meno che il livello di privacy non sia impostato su Organizational.

Più valichi di frontiera in un'unica tabella (dashboard per flotte) — 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 in Excel, o un aggiornamento pianificato in Power BI / Excel Online, mantiene i dati aggiornati — senza codice di polling.

Integrazione ERP (BAS / BAF e piattaforme della famiglia 1C)

BAS / BAF e le altre piattaforme della famiglia 1C possono chiamare questa API direttamente da un’attività pianificata — HTTPConnection più ReadJSON, senza middleware né servizi aggiuntivi da ospitare. Lo scenario più diffuso mantiene aggiornato un registro informazioni con i prezzi dei carburanti nell’UE.

Aggiornare un registro informazioni (prezzi carburanti, tutti i paesi in una chiamata)

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

Tre cose da azzeccare: passate New OpenSSLSecureConnection sulla porta 443, altrimenti la richiesta muore sul TLS; chiamate /api/v1/data/fuel senza il parametro country, così una sola richiesta restituisce tutti i paesi invece di una chiamata per paese; e verificate ok prima di toccare data — gli errori tornano come ok:false con un error.code, non come eccezione. L’esempio usa il set di parole chiave inglese della piattaforma; gli equivalenti localizzati (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) si comportano allo stesso modo.

I prezzi dei carburanti alla fonte cambiano una volta al giorno, quindi un’attività pianificata una o due volte al giorno basta e resta ampiamente dentro la quota gratuita Explorer. I dati di coda in tempo reale (queue, multi, border) cambiano ogni pochi minuti: interrogateli con il vostro ritmo e usate multi per leggere fino a 5 valichi in una sola richiesta invece che in un ciclo.

Server MCP

Preferisci le chiamate agli strumenti invece di REST? Gestiamo un vero server MCP (trasporto Streamable HTTP) che espone un sottoinsieme sicuro, di sola lettura, di questa API come strumenti MCP — stessa chiave API, stessa quota, solo un trasporto diverso.

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

Configurazione client (Claude Desktop / Claude Code):

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

OAuth per le integrazioni (Home Assistant e altre)

Le integrazioni i cui utenti hanno bisogno ciascuno della propria chiave (integrazioni personalizzate di Home Assistant, app desktop e mobili) possono far accedere l’utente invece di fargli incollare una chiave. Il flusso è OAuth 2.0 authorization code per client pubblici con PKCE (S256) — non c’è alcun client secret. Il token di accesso che restituiamo è la chiave NKD-DEV dell’utente, che invii poi in un header Bearer esattamente come oggi.

I client non sono self-service: fai richiesta nella pagina Integrazioni, esaminiamo ogni integrazione manualmente ed emettiamo un client ID con gli URI di reindirizzamento consentiti. Le chiavi emesse tramite un client approvato sono attivate istantaneamente per i mercati approvati per quell’integrazione. Richiedi un client di integrazione →

• Il codice di autorizzazione è valido per 60 secondi, monouso e legato al client, all’utente, all’URI di reindirizzamento e al PKCE challenge.
• La chiave viene restituita solo nel corpo della risposta del token (access_token) — mai in un URL. Conservala come una password.
• expires_in è di 30 giorni; un refresh restituisce la stessa chiave finché è attiva. Se l’utente revoca o rigenera la chiave, il refresh fallisce con invalid_grant e le chiamate API restituiscono 401 — avvia una nuova autenticazione.
• Le richieste hanno un limite di frequenza per IP e un tetto giornaliero per client; gli errori seguono la RFC 6749 (error, error_description).
• Ogni utente ottiene al massimo la propria quota di paesi: se la tua integrazione elenca più paesi dei posti liberi dell’utente, li sceglie nella pagina di consenso (passa markets=DE,AT a /oauth/authorize per preselezionarli). Entrambe le risposte token restituiscono anche markets_approved (paesi approvati dell’utente), markets_allowed (la sua quota; null = illimitata), markets_available (i tuoi paesi che non ha ancora) e upgrade_url (dove aggiunge «Paesi extra»).

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

Usa config_entry_oauth2_flow con LocalOAuth2ImplementationWithPkce (client_secret vuoto) e l’URI di reindirizzamento https://my.home-assistant.io/redirect/oauth, preregistrato per i client Home Assistant. Leggi la chiave da entry.data["token"]["access_token"] e continua a chiamare l’API con Authorization: Bearer. In caso di 401 dall’API, solleva ConfigEntryAuthFailed così che Home Assistant proponga una nuova autenticazione.

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)

Integrazioni: mostrare i limiti residui

GET /api/v2/account/usage — Quanto resta dei tuoi limiti in questo momento, per la chiave con cui chiami: piano, limite al secondo e, per ogni classe di quota giornaliera (cheap, heavy, route), limite, usato, residuo e ora di azzeramento (mezzanotte UTC); inoltre i tuoi paesi come li vede questa chiave e dove passare a un piano superiore. Non conteggiato, 30 chiamate al minuto per chiave.

Le chiavi di integrazione (OAuth) possono sempre chiamare GET /api/v2/account/usage, qualunque siano i prodotti consentiti all'integrazione. I numeri coincidono con le intestazioni X-Devapi-Limit e X-Devapi-Remaining; X-Devapi-Reset indica l'ora di azzeramento come 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"}}

Quando si raggiunge un limite, l'errore dice dove andare: 429 quota_exceeded restituisce anche error.reset_at (mezzanotte UTC) ed error.upgrade_url; 403 market_not_allowed e 403 integration_product_not_allowed restituiscono error.upgrade_url. Le chiavi d'integrazione ricevono anche error.pass_url (Trip Pass, sotto).

Home Assistant: interroga /account/usage al massimo ogni 15 minuti ed esponi un sensore «chiamate rimaste» da quotas.cheap.remaining. Tra un'interrogazione e l'altra leggi X-Devapi-Remaining dalle chiamate normali. Su 429 quota_exceeded o 403 market_not_allowed crea un repair issue con link a error.upgrade_url e sospendi le chiamate fino a reset_at.

Trip Pass

Gli utenti delle integrazioni possono acquistare un Trip Pass (1, 3, 7 o 14 giorni, pagamento una tantum) nella pagina Fatturazione. Finché è attivo, la chiave dell'integrazione ottiene tutti i paesi dell'integrazione, più chiamate di percorso camion e dati al giorno e una frequenza più alta; prodotti dell'integrazione, limiti delle previsioni e ritardo dei dati non cambiano. Le chiavi sviluppatore dello stesso account non vengono mai alzate.

Per le chiavi d'integrazione, account/usage restituisce pass: {active, expires_at, days_left} e pass_url (sezione Trip Pass della pagina Fatturazione); 429 quota_exceeded e 403 market_not_allowed / integration_product_not_allowed riportano lo stesso error.pass_url. Per le altre chiavi entrambi sono 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.

Prodotti

Scegli un endpoint per il riferimento completo, i parametri, le versioni e una sandbox dal vivo.

Standard utilizza la quota dati standard  ·  Pesante utilizza la quota di previsioni e statistiche — vedi Quote  ·  Percorso camion usa una propria quota di percorsi per camion — vedi Quote

Code di frontiera

Previsioni e statistiche

Carburante e luoghi

Uffici di cambio

Pianificazione del viaggio

Calendario dei giorni festivi

Logistica

Autisti e strade

Your Fleet (NakBus Live)

Assistente AI

Altro

Esportazione dei dati storici

Gli sviluppatori approvati possono scaricare lo storico pubblicato delle code di frontiera, mediato per ora, per un massimo di 5 valichi (finestra mobile fino a 90 giorni) in CSV, NDJSON o JSON compressi con gzip. È una funzione solo del portale — NON un endpoint API; le esportazioni si creano e si scaricano dalla scheda «Esportazione dati» del tuo account.

L'accesso viene concesso su richiesta: apri un ticket Data indicandoci quali valichi, l'intervallo temporale e l'uso previsto. Una volta approvato, nel tuo account compare la scheda Esportazione dati. Limite predefinito: 1 esportazione al giorno, fino a 5 valichi ciascuna — chiedici di aumentarlo.

Campi — una riga per valico per ogni ora UTC

Vengono esportati solo dati pubblicati, che superano i nostri controlli di anomalia e qualità (nessun dato grezzo delle singole segnalazioni). Tutti i timestamp sono in UTC. I file restano disponibili 10 giorni.

Provenienza: ogni file incorpora nell'intestazione un'impronta firmata (sha256 + HMAC), così qualsiasi copia può essere in seguito confermata come dato autentico di nakordoni.eu e verificata contro manomissioni — anche dopo il download.

# 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

Cosa puoi creare

Gli stessi prodotti di dati generano gli elementi visivi di nakordoni.eu — grafici di previsione settimanali, profili orari delle code, schede di stato in tempo reale. Un assaggio di ciò che contengono le API di previsioni e statistiche:

Attribuzione

Le integrazioni del piano Explorer devono mostrare un link visibile "Data by nakordoni.eu" ovunque vengano visualizzati i dati. È ciò che mantiene gratuito il piano gratuito.

Il codice esatto

Copia questo snippet così com'è. Il link deve rimanere indicizzabile: un <a href> HTML visibile e semplice accanto ai dati, che Google può indicizzare e seguire — NON aggiungere rel="nofollow", rel="sponsored" o rel="ugc" e non nasconderlo con CSS. Un link aggiunto tramite JavaScript va bene se compare nella pagina renderizzata da Google (Termini Developer API v1.0, sezione 8.1).

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

Variante compatta in piccolo (es. sotto un grafico o widget):

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

Puoi anche collegarti alla tua versione linguistica, ad esempio https://nakordoni.eu/it/ — vale qualsiasi link HTML visibile e normale verso nakordoni.eu. Il testo dell'ancora "Data by nakordoni.eu" deve restare in inglese.

Dove posizionarlo

• Direttamente accanto o sotto il blocco dati (tabella, grafico, widget, risposta) — sulla stessa schermata, visibile senza clic aggiuntivi.
• Su ogni pagina o schermata dell'app dove compaiono i nostri dati — non solo su una pagina "chi siamo".
• Dimensione e contrasto leggibili: almeno ~11px, non nascosto, non compresso, non del colore dello sfondo.
• App mobili native senza link HTML: mostra il testo "Data by nakordoni.eu" nella schermata dei dati e metti il link cliccabile nella schermata informazioni.

Verifichiamo periodicamente l'attribuzione sulla "pagina in cui vengono usati i dati" indicata in fase di registrazione. Un'attribuzione mancante o nascosta sul piano gratuito Explorer comporta prima un sollecito e poi la sospensione della chiave. I clienti su un piano a pagamento possono omettere l'attribuzione.

I controlli avvengono circa una volta a settimana tramite il nostro verificatore, il cui user agent contiene NakordoniComplianceBot/1.0. Apre solo le pagine elencate nella tua dashboard sviluppatore, non segue altri link e ignora robots.txt per quelle pagine, perché sono proprio quelle che ci hai chiesto di controllare. Se una protezione anti-bot o un firewall blocca i crawler sconosciuti, consenti questo user agent — se non riusciamo ad aprire una pagina, ti scriviamo in un ticket.

Licenza dati e mercati

La tua chiave API concede una licenza d'uso dei nostri dati solo nei paesi dichiarati al momento della registrazione. Esaminiamo ogni dichiarazione prima di concedere l'accesso completo, poiché i nostri dati sono un nostro prodotto e non li concediamo in licenza a mercati senza sapere dove verranno pubblicati.

• Dichiara ogni paese servito dal tuo sito, app o prodotto. Puoi modificare l'elenco in qualsiasi momento dalla tua dashboard; una modifica riporta il tuo account in revisione.
• Finché i tuoi mercati non sono approvati, la chiave funziona con limiti ridotti — la metà dell'assegnazione del piano Starter. Questo vale indipendentemente dal piano che hai.
• Possiamo approvare solo alcuni dei paesi che hai richiesto. La lista approvata, non quella richiesta, è ciò che la tua licenza copre.
• Pubblicare o ridistribuire i nostri dati in un mercato non dichiarato, o rivenderli come feed di dati concorrente, viola questi termini e può sospendere la tua chiave senza preavviso.
• Alcuni piani sono offerti solo in regioni selezionate. La disponibilità dipende dai mercati che dichiari.
• L'accordo completo sono i Termini della Developer API. Prevalgono su questa sintesi; la versione vincolante è quella inglese.

Attualità dei dati

L'aggiornamento dei dati dipende dal tuo piano. Nella risposta non c'è alcun indicatore — tutti i piani restituiscono gli stessi campi, gli stessi tipi e la stessa struttura di risposta.

• Piani a pagamento — Student, Starter, Pro e Pro MAX: telemetria in tempo reale, senza ritardo.
• Piano gratuito Explorer: un'istantanea degli ultimi 15–30 minuti. Lo scarto esatto varia da richiesta a richiesta.

Una risposta ritardata non è mai un errore né un problema di quota: è una risposta completa e valida, con numeri meno recenti. Ripetere la richiesta non restituisce dati più recenti.

Se la tua applicazione ha bisogno di dati attuali, qualsiasi piano a pagamento restituisce telemetria in tempo reale.

Ottieni la tua chiave API gratuita