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

Продукти

Изберете крайна точка за пълния ѝ справочник, параметри, версии и жив 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>, който търсачките могат да следват — НЕ добавяйте 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/bg/ — брои се всеки индексируем линк към nakordoni.eu. Текстът на котвата "Data by nakordoni.eu" трябва да остане на английски.

Къде да се постави

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

Периодично проверяваме атрибуцията на "страницата за използване на данните", посочена при регистрация. Липсваща или деиндексирана атрибуция в безплатния план Explorer води първо до напомняне, после до спиране на ключа. Клиентите с платен план могат да пропуснат атрибуцията.

Лиценз за данни и пазари

Your API key grants a licence to use our data in the countries you declared when you signed up, and only in those countries. We review every declaration before granting full access, because our data is our own product and we do not license it into markets without knowing where it will be published.

• Declare every country your site, app or product serves. You can change the list from your dashboard at any time; a change puts your account back into review.
• Until your markets are approved your key runs on reduced limits - half of the Starter plan allowance. This applies whatever plan you are on.
• Можем да одобрим само някои от държавите, които сте поискали. Оторизираният списък, а не поисканият, определя държавите, които покрива вашата лицензия.
• Publishing or redistributing our data in a market you did not declare, or reselling it as a competing data feed, is a breach of these terms and can suspend your key without notice.
• Some plans are offered only in selected regions. Availability depends on the markets you declare.

Актуалност на данните

Колко актуални са данните зависи от вашия план. В самия отговор няма маркер — всички планове връщат едни и същи полета, едни и същи типове и една и съща структура на отговора.

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

Забавеният отговор никога не е грешка и никога не е проблем с лимита — това е пълноценен, валиден отговор с по-стари числа. Повторната заявка не връща по-нови данни.

Ако приложението ви се нуждае от актуални данни, всеки платен план връща телеметрия в реално време.

Вземете безплатния си API ключ