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

Производи

Изберете крајна точка за нејзината целосна референца, параметри, верзии и песочник во живо.

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

Гранични редици

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

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

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

Возачи и патишта

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> што пребарувачите можат да го следат — НЕ додавајте rel="nofollow" или rel="sponsored", не го рендерирајте само преку JavaScript и не го криjте со 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/mk/ — се брои секој индексирлив линк до 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 клуч