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. Получавате имейл при 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 и платформи от семейството 1C)

BAS / BAF и другите платформи от семейството 1C могат да извикват този 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. При 401 от API предизвикайте 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.

Продукти

Изберете крайна точка за пълния ѝ справочник, параметри, версии и жив sandbox.

Стандартен използва стандартната квота за данни  ·  Тежък използва квотата за прогнози и статистика — вижте Квоти  ·  Камионен маршрут използва собствена квота за камионни маршрути — вижте Квоти

Гранични опашки

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

Гориво и локации

Обменни бюра

Планиране на пътуване

Логистика

Шофьори и пътища

Your Fleet (NakBus Live)

ИИ асистент

Други

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

Одобрените разработчици могат да изтеглят публикуваната история на граничните опашки, осреднена по часове, за до 5 гранични пункта (плъзгащ прозорец до 90 дни), като CSV с gzip, NDJSON или JSON. Това е функция само в портала — НЕ е API крайна точка; изграждате и изтегляте експортите от раздела „Експорт на данни“ в акаунта си.

Достъпът се дава при заявка: отворете тикет Данни и ни кажете кои гранични пунктове, за какъв период и с каква цел. След одобрение разделът Експорт на данни се появява в акаунта ви. Лимит по подразбиране: 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/bg/ — брои се всяка видима обикновена 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 ключ