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, за да прочетете до 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" }
    }
  }
}

Продукти

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

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

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

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

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

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

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

ИИ асистент

Други

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

Одобрените разработчици могат да изтеглят публикуваната история на граничните опашки, осреднена по часове, за до 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 води първо до напомняне, после до спиране на ключа. Клиентите на Pay As You Grow могат да пропуснат атрибуцията.

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