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

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

Code di frontiera

Previsioni e statistiche

Carburante e luoghi

Pianificazione del viaggio

Autisti e strade

Your Fleet (NakBus Live)

Assistente AI

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 essere un <a href> HTML visibile e normale, posto accanto ai dati: non generato solo via JavaScript e non nascosto con i CSS. Dai Termini della Developer API v1.0 (sezione 8.1) puoi aggiungere rel="nofollow" o rel="sponsored" se la policy del tuo sito lo richiede.

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

Licenza dati e mercati

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.
• Possiamo approvare solo alcuni dei paesi che hai richiesto. La lista approvata, non quella richiesta, è ciò che la tua licenza copre.
• 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.
• 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