Documentación de la API

Autenticación

Cada solicitud necesita tu clave API en la cabecera Authorization (recomendado) o como parámetro ?key=.

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

Envelope de respuesta

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

Los errores devuelven 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) y estado HTTP 400/401/403/404/429/500/503/504. Las cabeceras de límite de tasa X-Devapi-Limit y X-Devapi-Remaining se envían en cada respuesta medida. ok:false es determinante: nunca leas data en una llamada fallida. El objeto usage está presente en cada producto tarificado; /status es público y no tarificado, por lo que no devuelve usage.

Cuotas

Los contadores diarios se reinician a medianoche UTC. Recibes un correo al 80% y al 100% de la cuota.

Los planes de pago suben cada uno de estos límites. Planes actuales y sus cuotas: Planes

Ejemplos de código

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)

Trae datos en vivo de colas, previsiones o prohibiciones para camiones directamente a un libro con el conector JSON integrado de Power Query — sin código, con actualización programada. El mismo patrón de Headers funciona para cualquier producto de esta API — solo cambia la 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

Guarda la clave API dentro de la consulta M (Home → Advanced Editor), no en una celda de la hoja — Power Query bloquea una solicitud web construida a partir de otra consulta o celda ("Formula.Firewall") a menos que el nivel de privacidad esté establecido en Organizational.

Varios pasos fronterizos en una sola tabla (paneles de flota) — 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 en Excel, o una actualización programada en Power BI / Excel Online, mantiene los datos al día — sin código de sondeo (polling).

Integración con ERP (BAS / BAF y plataformas de la familia 1C)

BAS / BAF y las demás plataformas de la familia 1C pueden llamar a esta API directamente desde una tarea programada — HTTPConnection más ReadJSON, sin middleware ni servicios adicionales que alojar. El montaje más habitual mantiene al día un registro de información con los precios de los carburantes en la UE.

Actualizar un registro de información (precios de carburantes, todos los países en una llamada)

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

Tres cosas que hay que acertar: pase New OpenSSLSecureConnection en el puerto 443 o la petición se caerá en TLS; llame a /api/v1/data/fuel sin el parámetro country para que una sola petición devuelva todos los países en lugar de una llamada por país; y compruebe ok antes de tocar data — los fallos vuelven como ok:false con un error.code, no como excepción. El ejemplo usa el juego de palabras clave en inglés de la plataforma; los equivalentes localizados (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) se comportan igual.

Los precios de los carburantes cambian en origen una vez al día, así que una tarea programada una o dos veces al día basta y se queda muy por debajo de la cuota gratuita Explorer. Los datos de cola en directo (queue, multi, border) cambian cada pocos minutos: consúltelos a su propio ritmo y use multi para leer hasta 5 pasos fronterizos en una sola petición en vez de en un bucle.

Servidor MCP

¿Prefieres la llamada a herramientas en lugar de REST? Ejecutamos un servidor MCP real (transporte Streamable HTTP) que expone un subconjunto seguro, de solo lectura, de esta API como herramientas MCP — la misma clave API, la misma cuota, solo un transporte diferente.

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

Configuración del cliente (Claude Desktop / Claude Code):

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

OAuth para integraciones (Home Assistant y otras)

Las integraciones cuyos usuarios necesitan cada uno su propia clave (integraciones personalizadas de Home Assistant, aplicaciones de escritorio y móviles) pueden dejar que el usuario inicie sesión en lugar de pegar una clave. El flujo es OAuth 2.0 authorization code para clientes públicos con PKCE (S256); no hay client secret. El token de acceso que devolvemos es la propia clave NKD-DEV del usuario, que luego envías en una cabecera Bearer exactamente como hasta ahora.

Los clientes no son de autoservicio: solicítalos en la página de Integraciones, revisamos cada integración manualmente y emitimos un client ID con sus URI de redirección permitidas. Las claves emitidas mediante un cliente aprobado se activan al instante para los mercados aprobados para esa integración. Solicitar un cliente de integración →

• El código de autorización es válido durante 60 segundos, de un solo uso y está vinculado al cliente, al usuario, a la URI de redirección y al PKCE challenge.
• La clave solo se devuelve en el cuerpo de la respuesta del token (access_token), nunca en una URL. Guárdala como una contraseña.
• expires_in es de 30 días; una renovación devuelve la misma clave mientras esté activa. Si el usuario revoca o regenera la clave, la renovación falla con invalid_grant y las llamadas a la API devuelven 401: inicia la reautenticación.
• Las solicitudes tienen límite de frecuencia por IP y un tope diario por cliente; los errores siguen la RFC 6749 (error, error_description).
• Cada usuario recibe como máximo su propio cupo de países: si tu integración incluye más países que plazas libres tiene el usuario, los elige en la página de consentimiento (pasa markets=DE,AT a /oauth/authorize para preseleccionarlos). Ambas respuestas token devuelven también markets_approved (países aprobados del usuario), markets_allowed (su cupo; null = ilimitado), markets_available (tus países que aún no tiene) y upgrade_url (donde añade «Países adicionales»).

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 vacío) y la URI de redirección https://my.home-assistant.io/redirect/oauth, que está preregistrada para los clientes de Home Assistant. Lee la clave de entry.data["token"]["access_token"] y sigue llamando a la API con Authorization: Bearer. Ante un 401 de la API, lanza ConfigEntryAuthFailed para que Home Assistant ofrezca la reautenticación.

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)

Integraciones: mostrar los límites restantes

GET /api/v2/account/usage — Lo que queda de tus límites ahora mismo, para la clave con la que llamas: plan, límite por segundo y, para cada clase de cuota diaria (cheap, heavy, route), límite, usado, restante y hora de reinicio (medianoche UTC); además tus países tal como los ve esta clave y dónde mejorar el plan. No se contabiliza, 30 llamadas por minuto por clave.

Las claves de integración (OAuth) siempre pueden llamar a GET /api/v2/account/usage, sean cuales sean los productos permitidos a la integración. Sus cifras coinciden con las cabeceras X-Devapi-Limit y X-Devapi-Remaining; X-Devapi-Reset da la hora de reinicio como marca de tiempo 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"}}

Cuando se alcanza un límite, el error indica a dónde ir: 429 quota_exceeded también devuelve error.reset_at (medianoche UTC) y error.upgrade_url; 403 market_not_allowed y 403 integration_product_not_allowed devuelven error.upgrade_url. Las claves de integración también reciben error.pass_url (Trip Pass, abajo).

Home Assistant: consulta /account/usage como mucho cada 15 minutos y expón un sensor «llamadas restantes» a partir de quotas.cheap.remaining. Entre consultas, lee X-Devapi-Remaining de tus llamadas normales. Ante 429 quota_exceeded o 403 market_not_allowed, crea un repair issue con enlace a error.upgrade_url y pausa las llamadas hasta reset_at.

Trip Pass

Los usuarios de integraciones pueden comprar un Trip Pass (1, 3, 7 o 14 días, pago único) en la página de Facturación. Mientras está activo, la clave de la integración obtiene todos los países de la integración, más llamadas de ruta de camión y de datos al día y una tasa más alta; los productos de la integración, los límites de previsión y el retraso de los datos no cambian. Las claves de desarrollador de la misma cuenta nunca se elevan.

Para claves de integración, account/usage devuelve pass: {active, expires_at, days_left} y pass_url (sección Trip Pass de la página de Facturación); 429 quota_exceeded y 403 market_not_allowed / integration_product_not_allowed llevan el mismo error.pass_url. Para otras claves ambos son 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.

Productos

Elige un endpoint para ver su referencia completa, parámetros, versiones y un sandbox en vivo.

Estándar utiliza la cuota de datos estándar  ·  Pesado utiliza la cuota de pronósticos y estadísticas — ver Cuotas  ·  Ruta para camiones consume su propia cuota de rutas para camiones — consulta Cuotas

Colas en frontera

Pronósticos y estadísticas

Combustible y ubicaciones

Casas de cambio

Planificación de viajes

Logística

Conductores y carreteras

Your Fleet (NakBus Live)

Asistente de IA

Otros

Exportación de datos históricos

Los desarrolladores aprobados pueden descargar el histórico publicado de colas en frontera, promediado por hora, de hasta 5 pasos fronterizos (ventana móvil de hasta 90 días) en CSV, NDJSON o JSON comprimidos con gzip. Es una función solo del portal — NO un endpoint de la API; las exportaciones se crean y se descargan desde la pestaña «Exportación de datos» de tu cuenta.

El acceso se concede a petición: abre un ticket de Data indicándonos qué pasos fronterizos, el intervalo de fechas y el uso previsto. Una vez aprobado, la pestaña Exportación de datos aparece en tu cuenta. Límite por defecto: 1 exportación al día, con hasta 5 pasos cada una — pídenos ampliarlo.

Campos — una fila por paso fronterizo y hora UTC

Solo se exportan datos publicados, que han pasado nuestros controles de anomalías y calidad (nada de datos brutos por reporte). Todas las marcas de tiempo están en UTC. Los archivos se conservan 10 días.

Procedencia: cada archivo incorpora en su cabecera una huella firmada (sha256 + HMAC), de modo que cualquier copia puede confirmarse después como datos auténticos de nakordoni.eu y comprobarse frente a manipulaciones — incluso tras la descarga.

# 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

Lo que puedes crear

Los mismos productos de datos generan los elementos visuales de nakordoni.eu — gráficos de previsión semanal, perfiles horarios de colas, tarjetas de estado en tiempo real. Una muestra de lo que contienen las API de previsiones y estadísticas:

Atribución

Las integraciones del plan Explorer deben mostrar un enlace visible "Data by nakordoni.eu" allí donde se muestren los datos. Es lo que mantiene gratis el plan gratuito.

El código exacto

Copia este fragmento tal cual. El enlace debe seguir siendo indexable: un <a href> HTML visible y sencillo junto a los datos, que Google pueda indexar y seguir — NO añadas rel="nofollow", rel="sponsored" ni rel="ugc", y no lo ocultes con CSS. Un enlace añadido con JavaScript es válido si aparece en la página que Google renderiza (Términos de Developer API v1.0, sección 8.1).

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

Variante compacta en letra pequeña (p. ej., bajo un gráfico o widget):

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

También puedes enlazar a tu versión de idioma, por ejemplo https://nakordoni.eu/es/: vale cualquier enlace HTML visible y normal a nakordoni.eu. El texto del ancla "Data by nakordoni.eu" debe permanecer en inglés.

Dónde colocarlo

• Directamente junto o debajo del bloque de datos (tabla, gráfico, widget, respuesta) — en la misma pantalla, visible sin clics adicionales.
• En cada página o pantalla de la app donde aparezcan nuestros datos — no solo en una página "acerca de".
• Tamaño y contraste legibles: al menos ~11px, no oculto, no plegado, no del color del fondo.
• Apps móviles nativas sin enlaces HTML: muestre el texto "Data by nakordoni.eu" en la pantalla de datos y ponga el enlace pulsable en la pantalla de información.

Verificamos periódicamente la atribución en la "página donde se usan los datos" que indicaste al registrarte. La falta de atribución o su ocultación en el plan gratuito Explorer conlleva primero un aviso y después la suspensión de la clave. Los clientes de un plan de pago pueden omitir la atribución.

Las comprobaciones se hacen aproximadamente una vez por semana con nuestro verificador, cuyo user agent contiene NakordoniComplianceBot/1.0. Solo abre las páginas indicadas en tu panel de desarrollador, no sigue otros enlaces e ignora robots.txt en esas páginas, porque son justo las que nos pediste comprobar. Si una protección antibots o un firewall bloquea rastreadores desconocidos, permite este user agent: si no podemos abrir una página, te escribiremos en un ticket.

Licencia de datos y mercados

Tu clave API concede una licencia para usar nuestros datos únicamente en los países que declaraste al registrarte. Revisamos cada declaración antes de conceder acceso completo, porque nuestros datos son nuestro propio producto y no los licenciamos en mercados sin saber dónde se publicarán.

• Declara cada país que atiende tu sitio, app o producto. Puedes cambiar la lista en cualquier momento desde tu panel; un cambio devuelve tu cuenta a revisión.
• Hasta que tus mercados sean aprobados, tu clave funciona con límites reducidos: la mitad de la asignación del plan Starter. Esto se aplica sea cual sea tu plan.
• Es posible que solo aprobemos algunos de los países que solicitaste. La lista aprobada, no la solicitada, es la que cubre tu licencia.
• Publicar o redistribuir nuestros datos en un mercado no declarado, o revenderlos como un feed de datos competidor, incumple estos términos y puede suspender tu clave sin previo aviso.
• Algunos planes se ofrecen solo en regiones seleccionadas. La disponibilidad depende de los mercados que declares.
• El acuerdo completo son los Términos de la Developer API. Prevalecen sobre este resumen; la versión vinculante es la inglesa.

Actualidad de los datos

La actualidad de tus datos depende de tu plan. La respuesta no incluye ningún indicador — todos los planes devuelven los mismos campos, los mismos tipos y la misma estructura de respuesta.

• Planes de pago — Student, Starter, Pro y Pro MAX: telemetría en directo, sin retraso.
• Plan gratuito Explorer: una instantánea de los últimos 15 a 30 minutos. El desfase exacto varía de una petición a otra.

Una respuesta retrasada nunca es un error ni un problema de cuota: es una respuesta completa y válida con cifras más antiguas. Repetir la petición no devuelve datos más recientes.

Si tu aplicación necesita datos actuales, cualquier plan de pago devuelve telemetría en tiempo real.

Consigue tu clave API gratuita