Documentation de l'API

Authentification

Chaque requête nécessite votre clé API dans l'en-tête Authorization (recommandé) ou en tant que paramètre ?key=.

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

Enveloppe de réponse

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

Les erreurs renvoient ok:false avec 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) et un statut HTTP 400/401/403/404/429/500/503/504. Les en-têtes de limitation de débit X-Devapi-Limit et X-Devapi-Remaining sont envoyés à chaque réponse facturée. ok:false fait foi — n'exploitez jamais data lors d'un appel en échec. L'objet usage est présent dans chaque produit facturé ; /status est public et non facturé, il ne renvoie donc pas usage.

Quotas

Les compteurs quotidiens sont réinitialisés à minuit UTC. Vous recevez un e-mail à 80 % et à 100 % du quota.

Les forfaits payants relèvent chacune de ces limites. Forfaits actuels et leurs quotas : Forfaits

Exemples de code

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)

Récupérez les données de files d'attente, de prévisions ou d'interdictions pour poids lourds directement dans un classeur grâce au connecteur JSON intégré de Power Query — sans code, avec actualisation programmée. Le même schéma d'en-têtes (Headers) fonctionne pour tous les produits de cette API — il suffit de changer 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

Conservez la clé API à l'intérieur de la requête M (Home → Advanced Editor), pas dans une cellule de feuille — Power Query bloque une requête web construite à partir d'une autre requête ou cellule ("Formula.Firewall"), sauf si le niveau de confidentialité est défini sur Organizational.

Plusieurs postes-frontières dans un seul tableau (tableaux de bord de 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 dans Excel, ou une actualisation planifiée dans Power BI / Excel Online, garde les chiffres à jour — sans code d'interrogation (polling).

Intégration ERP (BAS / BAF et plateformes de la famille 1C)

BAS / BAF et les autres plateformes de la famille 1C peuvent appeler cette API directement depuis une tâche planifiée — HTTPConnection et ReadJSON, sans intergiciel ni service supplémentaire à héberger. Le montage le plus courant tient à jour un registre d’informations avec les prix des carburants dans l’UE.

Mettre à jour un registre d’informations (prix des carburants, tous les pays en un appel)

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

Trois points à ne pas rater : passez New OpenSSLSecureConnection sur le port 443, sinon la requête échoue sur TLS ; appelez /api/v1/data/fuel sans paramètre country pour qu’une seule requête renvoie tous les pays au lieu d’un appel par pays ; et testez ok avant de toucher à data — les échecs reviennent en ok:false avec un error.code, pas sous forme d’exception. L’exemple utilise le jeu de mots-clés anglais de la plateforme ; les équivalents localisés (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) se comportent à l’identique.

Les prix des carburants ne bougent qu’une fois par jour à la source : une tâche planifiée une ou deux fois par jour suffit et reste très en deçà du quota Explorer gratuit. Les files d’attente en direct (queue, multi, border) changent toutes les quelques minutes — interrogez-les à votre propre rythme et utilisez multi pour lire jusqu’à 5 points de passage en une seule requête plutôt qu’en boucle.

Serveur MCP

Vous préférez l'appel d'outils plutôt que REST ? Nous exploitons un véritable serveur MCP (transport Streamable HTTP) exposant un sous-ensemble sûr, en lecture seule, de cette API sous forme d'outils MCP — même clé API, même quota, juste un transport différent.

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

Configuration client (Claude Desktop / Claude Code):

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

OAuth pour les intégrations (Home Assistant et autres)

Les intégrations dont chaque utilisateur a besoin de sa propre clé (intégrations personnalisées Home Assistant, applications de bureau et mobiles) peuvent laisser l’utilisateur se connecter au lieu de coller une clé. Le flux est OAuth 2.0 authorization code pour clients publics avec PKCE (S256) — il n’y a pas de client secret. Le jeton d’accès que nous renvoyons est la clé NKD-DEV propre à l’utilisateur, que vous envoyez ensuite dans un en-tête Bearer exactement comme aujourd’hui.

Les clients ne sont pas en libre-service : faites une demande sur la page Intégrations, nous examinons chaque intégration manuellement et émettons un client ID avec ses URI de redirection autorisées. Les clés émises via un client approuvé sont activées instantanément pour les marchés approuvés pour cette intégration. Demander un client d’intégration →

• Le code d’autorisation est valable 60 secondes, à usage unique, et lié au client, à l’utilisateur, à l’URI de redirection et au PKCE challenge.
• La clé n’est renvoyée que dans le corps de la réponse du jeton (access_token) — jamais dans une URL. Conservez-la comme un mot de passe.
• expires_in vaut 30 jours ; un rafraîchissement renvoie la même clé tant qu’elle est active. Si l’utilisateur révoque ou régénère la clé, le rafraîchissement échoue avec invalid_grant et les appels API renvoient 401 — lancez une nouvelle authentification.
• Les requêtes sont limitées en débit par IP et plafonnées par client et par jour ; les erreurs suivent la RFC 6749 (error, error_description).
• Chaque utilisateur obtient au plus son propre quota de pays : si votre intégration propose plus de pays que l’utilisateur n’a de places libres, il les choisit sur la page de consentement (passez markets=DE,AT à /oauth/authorize pour les présélectionner). Les deux réponses token renvoient aussi markets_approved (pays approuvés de l’utilisateur), markets_allowed (son quota ; null = illimité), markets_available (vos pays qu’il n’a pas encore) et upgrade_url (où ajouter « Pays supplémentaires »).

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

Utilisez config_entry_oauth2_flow avec LocalOAuth2ImplementationWithPkce (client_secret vide) et l’URI de redirection https://my.home-assistant.io/redirect/oauth, préenregistrée pour les clients Home Assistant. Lisez la clé dans entry.data["token"]["access_token"] et continuez à appeler l’API avec Authorization: Bearer. Sur un 401 de l’API, levez ConfigEntryAuthFailed pour que Home Assistant propose une nouvelle authentification.

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)

Intégrations : afficher les limites restantes

GET /api/v2/account/usage — Ce qu'il reste de vos limites en ce moment, pour la clé utilisée : offre, plafond par seconde et, pour chaque classe de quota journalier (cheap, heavy, route), limite, consommé, restant et heure de remise à zéro (minuit UTC) ; ainsi que vos pays tels que cette clé les voit et où passer à une offre supérieure. Non décompté, 30 appels par minute et par clé.

Les clés d'intégration (OAuth) peuvent toujours appeler GET /api/v2/account/usage, quels que soient les produits autorisés pour l'intégration. Ses chiffres correspondent aux en-têtes X-Devapi-Limit et X-Devapi-Remaining ; X-Devapi-Reset donne l'heure de remise à zéro en horodatage 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"}}

Quand une limite est atteinte, l'erreur indique où aller : 429 quota_exceeded renvoie aussi error.reset_at (minuit UTC) et error.upgrade_url ; 403 market_not_allowed et 403 integration_product_not_allowed renvoient error.upgrade_url. Les clés d'intégration reçoivent aussi error.pass_url (Trip Pass, ci-dessous).

Home Assistant : interrogez /account/usage au plus toutes les 15 minutes et exposez un capteur « appels restants » à partir de quotas.cheap.remaining. Entre deux interrogations, lisez X-Devapi-Remaining dans vos appels normaux. Sur 429 quota_exceeded ou 403 market_not_allowed, créez un repair issue avec un lien vers error.upgrade_url et suspendez les appels jusqu'à reset_at.

Trip Pass

Les utilisateurs d'intégrations peuvent acheter un Trip Pass (1, 3, 7 ou 14 jours, paiement unique) sur la page Facturation. Tant qu'il est actif, la clé d'intégration obtient tous les pays de l'intégration, davantage d'appels d'itinéraire poids lourd et de données par jour et un débit plus élevé ; les produits de l'intégration, les limites de prévision et le délai des données ne changent pas. Les clés développeur du même compte ne sont jamais relevées.

Pour les clés d'intégration, account/usage renvoie pass : {active, expires_at, days_left} et pass_url (section Trip Pass de la page Facturation) ; 429 quota_exceeded et 403 market_not_allowed / integration_product_not_allowed portent le même error.pass_url. Pour les autres clés, les deux valent 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.

Produits

Choisissez un endpoint pour sa référence complète, ses paramètres, ses versions et une sandbox en direct.

Standard utilise la quote-part standard de données  ·  Lourd utilise le quota de prévisions et statistiques — voir Quotas  ·  Itinéraire poids lourd utilise son propre quota d'itinéraires poids lourd — voir Quotas

Files d'attente frontalières

Prévisions et statistiques

Carburant et emplacements

Bureaux de change

Planification de voyage

Calendrier des jours fériés

Logistique

Conducteurs et routes

Your Fleet (NakBus Live)

Assistant IA

Autres

Export des données historiques

Les développeurs approuvés peuvent télécharger l'historique publié des files aux frontières, moyenné à l'heure, pour jusqu'à 5 postes-frontières (fenêtre glissante jusqu'à 90 jours) en CSV, NDJSON ou JSON compressés en gzip. C'est une fonction du portail uniquement — PAS un endpoint d'API ; vous construisez et téléchargez les exports depuis l'onglet « Export de données » de votre compte.

L'accès est accordé sur demande : ouvrez un ticket Data en nous indiquant quels postes-frontières, la période et l'usage prévu. Une fois approuvé, l'onglet Export de données apparaît dans votre compte. Limite par défaut : 1 export/jour, jusqu'à 5 postes chacun — demandez-nous de l'augmenter.

Champs — une ligne par poste-frontière et par heure UTC

Seules des données publiées sont exportées, après nos contrôles d'anomalies et de qualité (aucune donnée brute par signalement). Tous les horodatages sont en UTC. Les fichiers sont conservés 10 jours.

Provenance : chaque fichier intègre dans son en-tête une empreinte signée (sha256 + HMAC), de sorte que toute copie peut être confirmée plus tard comme d'authentiques données nakordoni.eu et vérifiée contre toute altération — même après téléchargement.

# 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 que vous pouvez créer

Les mêmes produits de données génèrent les visuels de nakordoni.eu — graphiques de prévisions hebdomadaires, profils horaires des files, cartes de statut en temps réel. Un aperçu de ce que contiennent les API de prévisions et de statistiques :

Attribution

Les intégrations du forfait Explorer doivent afficher un lien visible « Data by nakordoni.eu » partout où les données sont présentées. C'est ce qui maintient le forfait gratuit gratuit.

Le code exact

Copiez cet extrait tel quel. Le lien doit rester indexable : un <a href> HTML visible et simple à côté des données, que Google peut indexer et suivre — n'ajoutez PAS rel="nofollow", rel="sponsored" ni rel="ugc", et ne le masquez pas par CSS. Un lien ajouté par JavaScript convient s'il apparaît sur la page rendue par Google (Conditions Developer API v1.0, section 8.1).

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

Variante compacte en petits caractères (p. ex. sous un graphique ou un widget) :

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

Vous pouvez aussi pointer vers votre version linguistique, par exemple https://nakordoni.eu/fr/ — tout lien HTML visible et ordinaire vers nakordoni.eu est accepté. Le texte d'ancrage "Data by nakordoni.eu" doit rester en anglais.

Où le placer

• Directement à côté ou sous le bloc de données (tableau, graphique, widget, réponse) — sur le même écran, visible sans clic supplémentaire.
• Sur chaque page ou écran d'application où nos données apparaissent — pas seulement sur une page "à propos".
• Taille et contraste lisibles : au moins ~11px, non masqué, non replié, pas de la couleur du fond.
• Applications mobiles natives sans liens HTML : affichez le texte "Data by nakordoni.eu" sur l'écran des données et placez le lien cliquable sur l'écran d'informations.

Nous vérifions régulièrement l'attribution sur la « page où les données sont utilisées » que vous avez indiquée à l'inscription. Une attribution absente ou masquée sur l'offre gratuite Explorer entraîne d'abord un rappel, puis la suspension de la clé. Les clients d'une offre payante peuvent omettre l'attribution.

Les vérifications ont lieu environ une fois par semaine, par notre robot dont le user agent contient NakordoniComplianceBot/1.0. Il n'ouvre que les pages indiquées dans votre tableau de bord développeur, ne suit aucun autre lien et ignore robots.txt pour ces pages, puisque ce sont celles que vous nous avez demandé de vérifier. Si une protection anti-bots ou un pare-feu bloque les robots inconnus, autorisez ce user agent — si nous ne pouvons pas ouvrir une page, nous vous écrirons dans un ticket.

Licence de données et marchés

Votre clé API accorde une licence d'utilisation de nos données uniquement dans les pays que vous avez déclarés lors de votre inscription. Nous examinons chaque déclaration avant d'accorder un accès complet, car nos données sont notre propre produit et nous ne les concédons pas sous licence à des marchés sans savoir où elles seront publiées.

• Déclarez chaque pays que votre site, application ou produit dessert. Vous pouvez modifier la liste à tout moment depuis votre tableau de bord ; une modification remet votre compte en cours d'examen.
• Tant que vos marchés ne sont pas approuvés, votre clé fonctionne avec des limites réduites — la moitié de l'allocation du plan Starter. Cela s'applique quel que soit votre plan.
• Nous pouvons n'approuver que certains des pays que vous avez demandés. C'est la liste approuvée, et non la liste demandée, qui détermine les pays couverts par votre licence.
• Publier ou redistribuer nos données sur un marché non déclaré, ou les revendre comme flux de données concurrent, constitue une violation de ces conditions et peut suspendre votre clé sans préavis.
• Certains plans ne sont proposés que dans des régions sélectionnées. La disponibilité dépend des marchés que vous déclarez.
• L'accord complet, ce sont les Conditions de la Developer API. Elles priment sur ce résumé ; la version anglaise fait foi.

Actualité des données

La fraîcheur de vos données dépend de votre forfait. Aucun marqueur n'apparaît dans la réponse — tous les forfaits renvoient les mêmes champs, les mêmes types et la même structure de réponse.

• Forfaits payants — Student, Starter, Pro et Pro MAX : télémétrie en direct, sans délai.
• Forfait gratuit Explorer : un instantané des 15 à 30 dernières minutes. Le décalage exact varie d'une requête à l'autre.

Une réponse différée n'est jamais une erreur ni un problème de quota : c'est une réponse complète et valide, avec des chiffres plus anciens. Réessayer ne renvoie pas de données plus récentes.

Si votre application a besoin de données actuelles, tout forfait payant renvoie de la télémétrie en temps réel.

Obtenez votre clé API gratuite