Документация 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/ru/ — засчитывается любая видимая обычная 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