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",
  "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, bad_request, internal_error) e stato HTTP 401/403/404/429/500. Gli header di rate-limit X-Devapi-Limit e X-Devapi-Remaining vengono inviati a ogni risposta conteggiata.

Quote

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

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

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

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 frammento così com'è. Il link deve restare indicizzabile: un semplice <a href> HTML che i motori di ricerca possono seguire — NON aggiungere rel="nofollow" o rel="sponsored", non renderizzarlo solo via JavaScript e non nasconderlo con CSS.

<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 linkare la tua versione linguistica, es. https://nakordoni.eu/it/ — conta qualsiasi link indicizzabile a nakordoni.eu. Il testo àncora "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 di utilizzo dei dati" indicata alla registrazione. Attribuzione mancante o deindicizzata nel piano Explorer porta prima a un promemoria, poi alla sospensione della chiave. I clienti Pay As You Grow possono ometterla.

Ottieni la tua chiave API gratuita