Документація API

Автентифікація

Кожен запит потребує вашого ключа API в заголовку Authorization (рекомендовано) або як параметр ?key=.

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

Формат відповіді

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

Помилки повертають ok:false з 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) та HTTP-статусом 400/401/403/404/429/500/503/504. Заголовки обмеження частоти X-Devapi-Limit і X-Devapi-Remaining надсилаються в кожній тарифікованій відповіді. ok:false є визначальним — ніколи не читайте data у невдалому виклику. Об'єкт usage присутній у кожному тарифікованому продукті; /status публічний і нетарифікований, тому usage не повертає.

Квоти

Денні лічильники скидаються опівночі за UTC. Ви отримуєте email при досягненні 80% і 100% квоти.

Платні тарифи піднімають кожен із цих лімітів. Актуальні тарифи та їхні ліміти: Плани

Приклади коду

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)

Отримуйте дані про черги, прогнози чи заборони для вантажівок прямо в таблицю за допомогою вбудованого JSON-конектора Power Query — без коду, з оновленням за розкладом. Та сама схема заголовків (Headers) працює для будь-якого продукту цього API — достатньо змінити 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

Тримайте ключ API всередині M-запиту (Home → Advanced Editor), а не в клітинці аркуша — Power Query блокує вебзапит, побудований на основі іншого запиту чи клітинки ("Formula.Firewall"), якщо рівень конфіденційності не встановлено як Organizational.

Кілька пунктів пропуску в одній таблиці (дашборди для автопарку) — 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 в Excel або заплановане оновлення в Power BI / Excel Online тримає дані актуальними — без коду опитування (polling).

Інтеграція з ERP (BAS / BAF та платформи родини 1С)

BAS / BAF та інші платформи родини 1С можуть звертатися до цього API просто з регламентного завдання — HTTPConnection плюс ReadJSON, без проміжного сервісу. Найпоширеніший сценарій: тримати в актуальному стані регістр відомостей із цінами на пальне в ЄС.

Оновлення регістру відомостей (ціни на пальне, усі країни одним запитом)

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

Три речі, які треба зробити правильно: передайте New OpenSSLSecureConnection на порт 443, інакше запит впаде на TLS; викликайте /api/v1/data/fuel без параметра country — один запит поверне всі країни замість окремого виклику на кожну; і перевіряйте ok перед тим, як читати data — помилки приходять як ok:false з error.code, а не як виняток. У прикладі використано англомовний набір ключових слів платформи; локалізовані відповідники (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) працюють ідентично.

Ціни на пальне у джерелах змінюються раз на добу, тож регламентного завдання раз або двічі на день достатньо — і це залишається глибоко в межах безкоштовної квоти Explorer. Дані живих черг (queue, multi, border) оновлюються кожні кілька хвилин: опитуйте їх за власним графіком і беріть multi, щоб зчитати до 5 пунктів пропуску одним запитом замість циклу.

MCP-сервер

Надаєте перевагу виклику інструментів замість REST? Ми запускаємо справжній MCP-сервер (транспорт Streamable HTTP), що надає безпечну підмножину цього API лише для читання у вигляді MCP-інструментів — той самий API-ключ, та сама квота, просто інший транспорт.

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

Налаштування клієнта (Claude Desktop / Claude Code):

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

OAuth для інтеграцій (Home Assistant та інші)

Інтеграції, у користувачів яких має бути власний ключ (користувацькі інтеграції Home Assistant, настільні та мобільні застосунки), можуть дозволити користувачеві увійти замість вставлення ключа. Використовується потік OAuth 2.0 authorization code для публічних клієнтів із PKCE (S256) — client secret немає. Токен доступу, який ми повертаємо, — це власний ключ NKD-DEV користувача, і ви надсилаєте його в заголовку Bearer точно так само, як і зараз.

Клієнти створюються не самостійно: подайте заявку на сторінці інтеграцій, ми вручну розглядаємо кожну інтеграцію та видаємо client ID з дозволеними URI перенаправлення. Ключі, видані через схваленого клієнта, миттєво активуються для ринків, схвалених для цієї інтеграції. Подати заявку на клієнт інтеграції →

• Код авторизації дійсний 60 секунд, одноразовий і прив’язаний до клієнта, користувача, URI перенаправлення та PKCE challenge.
• Ключ повертається лише в тілі відповіді з токеном (access_token) — ніколи в URL. Зберігайте його як пароль.
• expires_in дорівнює 30 дням; оновлення повертає той самий ключ, поки він активний. Якщо користувач відкликає або перегенеровує ключ, оновлення завершується помилкою invalid_grant, а виклики API повертають 401 — почніть повторну автентифікацію.
• Запити обмежуються за частотою для кожної IP-адреси та за добовою квотою для кожного клієнта; помилки відповідають RFC 6749 (error, error_description).
• Кожен користувач отримує не більше власного ліміту країн: якщо ваша інтеграція має більше країн, ніж у користувача вільних місць, він обирає їх на сторінці згоди (передайте markets=DE,AT в /oauth/authorize для попереднього вибору). Обидві відповіді token також повертають markets_approved (схвалені країни користувача), markets_allowed (його ліміт; null = без обмежень), markets_available (ваші країни, яких у нього ще немає) і upgrade_url (де додати «Додаткові країни»).

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

Використовуйте config_entry_oauth2_flow з LocalOAuth2ImplementationWithPkce (client_secret порожній) та URI перенаправлення https://my.home-assistant.io/redirect/oauth, який попередньо зареєстровано для клієнтів Home Assistant. Читайте ключ із entry.data["token"]["access_token"] і надалі викликайте API із заголовком Authorization: Bearer. Отримавши від API відповідь 401, викличте ConfigEntryAuthFailed, щоб Home Assistant запропонував повторну автентифікацію.

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)

Інтеграції: показуйте залишок лімітів

GET /api/v2/account/usage — Скільки лишилося від ваших лімітів просто зараз для ключа, яким ви викликаєте: план, ліміт на секунду і для кожного класу денної квоти (cheap, heavy, route) ліміт, використано, залишок і час скидання (опівночі UTC); а також ваші країни так, як їх бачить цей ключ, і де підвищити план. Не тарифікується, 30 викликів на хвилину на ключ.

Ключі інтеграцій (OAuth) завжди можуть викликати GET /api/v2/account/usage, незалежно від того, які продукти дозволено інтеграції. Його числа збігаються із заголовками X-Devapi-Limit і X-Devapi-Remaining; X-Devapi-Reset дає час скидання як Unix timestamp.

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

Коли ліміт вичерпано, помилка підказує, куди перейти: 429 quota_exceeded також повертає error.reset_at (північ UTC) і error.upgrade_url; 403 market_not_allowed і 403 integration_product_not_allowed повертають error.upgrade_url. Ключі інтеграцій також отримують error.pass_url (Trip Pass, нижче).

Home Assistant: опитуйте /account/usage не частіше ніж раз на 15 хвилин і виведіть сенсор «залишилось викликів» з quotas.cheap.remaining. Між опитуваннями читайте X-Devapi-Remaining зі звичайних викликів. На 429 quota_exceeded або 403 market_not_allowed створіть repair issue з посиланням на error.upgrade_url і призупиніть виклики до reset_at.

Trip Pass

Користувачі інтеграцій можуть купити Trip Pass (1, 3, 7 або 14 днів, разовий платіж) на сторінці оплати. Поки він діє, ключ інтеграції отримує всі країни інтеграції, більше викликів маршруту для вантажівок і даних на день та вищу частоту запитів; продукти інтеграції, ліміти прогнозів і затримка даних не змінюються. Ключі розробника того самого акаунта не підвищуються.

Для ключів інтеграції account/usage повертає pass: {active, expires_at, days_left} і pass_url (розділ Trip Pass на сторінці оплати); 429 quota_exceeded і 403 market_not_allowed / integration_product_not_allowed містять той самий error.pass_url. Для інших ключів обидва поля 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.

Продукти

Оберіть ендпоінт, щоб побачити повний довідник, параметри, версії та живу пісочницю.

Стандартний використовує стандартну квоту даних  ·  Важкий використовує прогноз та статистику ліміту — див. Квоти  ·  Маршрут для вантажівок використовує власну квоту маршрутів для вантажівок — див. Квоти

Черги на кордоні

Прогнози та статистика

Пальне та локації

Пункти обміну валют

Планування маршруту

Логістика

Водії та дороги

Your Fleet (NakBus Live)

ШІ-асистент

Інше

Експорт історичних даних

Схвалені розробники можуть завантажити опубліковану історію черг на кордоні, усереднену погодинно, для до 5 пунктів пропуску (рухоме вікно до 90 днів) у форматі gzip-CSV, NDJSON або JSON. Це можливість лише в порталі — НЕ ендпоінт API; експорти ви формуєте й завантажуєте на вкладці «Експорт даних» у своєму акаунті.

Доступ надається за запитом: відкрийте тікет категорії Data й вкажіть, які пункти пропуску, за який період і для чого вам потрібні. Після схвалення в акаунті з’явиться вкладка «Експорт даних». Ліміт за замовчуванням: 1 експорт на день, до 5 пунктів пропуску в кожному — попросіть нас підняти його.

Поля — один рядок на пункт пропуску за кожну годину UTC

Дані — лише опубліковані, і перед експортом вони проходять наші перевірки аномалій та якості (жодних сирих даних окремих повідомлень). Усі позначки часу — UTC. Файли зберігаються 10 днів.

Походження: кожен файл містить у заголовку підписаний відбиток (sha256 + HMAC), тож будь-яку копію можна пізніше підтвердити як справжні дані nakordoni.eu і перевірити на зміни — навіть після завантаження.

# 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

Що ви можете створити

Ті самі продукти даних формують візуалізації на nakordoni.eu — тижневі графіки прогнозів, погодинні профілі черг, картки статусу в реальному часі. Невеликий приклад того, що містять API прогнозів і статистики:

Атрибуція

Інтеграції плану Explorer мають показувати видиме посилання "Data by nakordoni.eu" скрізь, де відображаються дані. Це зберігає безкоштовний план безкоштовним.

Точний код

Скопіюйте цей фрагмент як є. Посилання має залишатися індексованим: видиме звичайне HTML-посилання <a href> поруч із даними, яке Google може проіндексувати і перейти за ним, — НЕ додавайте rel="nofollow", rel="sponsored" чи rel="ugc" і не приховуйте його через CSS. Посилання, додане через JavaScript, підходить, якщо воно є на сторінці, яку рендерить Google (Умови Developer API v1.0, розділ 8.1).

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

Компактний дрібний варіант (наприклад, під графіком чи віджетом):

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

Можна посилатися на свою мовну версію, наприклад https://nakordoni.eu/uk/ — рахується будь-яке видиме звичайне HTML-посилання на nakordoni.eu. Текст якоря "Data by nakordoni.eu" має залишатися англійською.

Де розміщувати

• Безпосередньо поруч або під блоком даних (таблиця, графік, віджет, відповідь) — на тому ж екрані, видимо без додаткових кліків.
• На кожній сторінці чи екрані застосунку, де відображаються наші дані — не лише на сторінці "про нас".
• Читабельний розмір і контраст: щонайменше ~11px, не приховано, не згорнуто, не кольором фону.
• Нативні мобільні застосунки без HTML-посилань: показуйте текст "Data by nakordoni.eu" на екрані з даними та розмістіть клікабельне посилання на екрані "про застосунок".

Ми періодично перевіряємо атрибуцію на "сторінці використання даних", яку ви вказали під час реєстрації. Відсутня або прихована атрибуція на безкоштовному плані Explorer спершу веде до нагадування, потім до призупинення ключа. Клієнти платного плану можуть не вказувати атрибуцію.

Перевірки проводяться приблизно раз на тиждень нашим перевірником, user agent якого містить NakordoniComplianceBot/1.0. Він відкриває лише сторінки, вказані у вашій панелі розробника, не переходить за іншими посиланнями та не зважає на robots.txt для цих сторінок, бо саме їх ви просили перевіряти. Якщо захист від ботів або файрвол блокує невідомих краулерів, дозвольте цей user agent — якщо ми не зможемо відкрити сторінку, ми напишемо вам у тікеті.

Ліцензія на дані та ринки

Ваш API-ключ надає ліцензію на використання наших даних у країнах, які ви задекларували під час реєстрації, і лише в них. Ми перевіряємо кожну декларацію перед наданням повного доступу, оскільки наші дані — це наш власний продукт, і ми не ліцензуємо його на ринки, не знаючи, де він буде опублікований.

• Задекларуйте всі країни, які обслуговує ваш сайт, застосунок чи продукт. Ви можете змінити список у будь-який час у вашій панелі керування; зміна повертає ваш акаунт на розгляд.
• Поки ваші ринки не затверджені, ваш ключ працює з обмеженими лімітами — половина ліміту тарифу Starter. Це стосується будь-якого вашого тарифного плану.
• Ми можемо схвалити лише деякі країни з тих, які ви запросили. Затверджений список, а не запрошений, визначає країни, які покриває ваша ліцензія.
• Публікація або поширення наших даних на ринку, який ви не задекларували, чи перепродаж їх як конкуруючого потоку даних є порушенням цих умов і може призвести до призупинення вашого ключа без попередження.
• Деякі тарифи доступні лише в окремих регіонах. Доступність залежить від задекларованих вами ринків.
• Повна угода — це Умови Developer API. Вони мають перевагу над цим коротким викладом; юридично зобов’язальною є англомовна версія.

Свіжість даних

Наскільки свіжі дані — залежить від вашого тарифу. Позначки в самій відповіді немає: усі тарифи повертають ті самі поля, ті самі типи і ту саму структуру відповіді.

• Платні тарифи — Student, Starter, Pro і Pro MAX: жива телеметрія, без затримки.
• Безкоштовний тариф Explorer: знімок за останні 15–30 хвилин. Точне зміщення змінюється від запиту до запиту.

Затримана відповідь — це не помилка і не проблема з лімітом: це повноцінна валідна відповідь зі старішими числами. Повторний запит новіших даних не поверне.

Якщо вашому застосунку потрібні актуальні дані, будь-який платний тариф повертає телеметрію в реальному часі.

Отримати безкоштовний ключ API