Документація 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",
  "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, bad_request, internal_error) та HTTP-статусом 401/403/404/429/500. Заголовки обмеження частоти X-Devapi-Limit і X-Devapi-Remaining надсилаються в кожній тарифікованій відповіді.

Квоти

Денні лічильники скидаються опівночі за 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→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 в 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, щоб зчитати до 20 пунктів пропуску одним запитом замість циклу.

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

Продукти

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

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

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

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

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

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

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

ШІ-асистент

Інше

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

Схвалені розробники можуть завантажити опубліковану історію черг на кордоні, усереднену погодинно, для до 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>, який пошукові системи можуть переходити — НЕ додавайте rel="nofollow" чи rel="sponsored", не рендеріть його лише через JavaScript і не ховайте через CSS.

<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/ — рахується будь-яке індексоване посилання на nakordoni.eu. Текст якоря "Data by nakordoni.eu" має залишатися англійською.

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

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

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

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