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

Производи

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

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

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

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

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

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

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

ИИ асистент

Друго

Извоз на историски податоци

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

Земете го вашиот бесплатен API клуч