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% квоте.

Plaćeni planovi podižu svaki od ovih limita. Aktuelni planovi i njihovi limiti: Планови

Примери кода

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)

Preuzmite podatke o redovima čekanja, prognozama ili zabranama za kamione direktno u radnu svesku pomoću ugrađenog JSON konektora u Power Query-ju — bez koda, sa osvežavanjem po rasporedu. Isti obrazac Headers-a radi za svaki proizvod ovog API-ja — samo promenite 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

Čuvajte API ključ unutar M upita (Home → Advanced Editor), a ne u ćeliji lista — Power Query blokira veb zahtev sastavljen iz drugog upita ili ćelije ("Formula.Firewall"), osim ako nivo privatnosti nije podešen na Organizational.

Više graničnih prelaza u jednoj tabeli (kontrolne table za vozni park) — 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 u Excel-u ili planirano osvežavanje u Power BI / Excel Online-u održava podatke ažurnim — bez koda za periodično proveravanje (polling).

Integracija sa ERP (BAS / BAF i platforme porodice 1C)

BAS / BAF i druge platforme porodice 1C mogu da pozovu ovaj API direktno iz zakazanog zadatka — HTTPConnection plus ReadJSON, bez međusloja i bez dodatnog servisa. Najčešća postavka održava ažurnim registar informacija sa cenama goriva u EU.

Osvežavanje registra informacija (cene goriva, sve zemlje u jednom pozivu)

// 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;

Tri stvari treba pogoditi: prosledite New OpenSSLSecureConnection na portu 443, inače zahtev pada na TLS; pozovite /api/v1/data/fuel bez parametra country da jedan zahtev vrati sve zemlje umesto poziva po zemlji; i proverite ok pre nego što dirnete data — greške se vraćaju kao ok:false sa error.code, a ne kao izuzetak. Primer koristi engleski skup ključnih reči platforme; lokalizovani ekvivalenti (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) ponašaju se isto.

Cene goriva se u izvorima menjaju jednom dnevno, pa je zakazani zadatak jednom ili dvaput dnevno sasvim dovoljan i ostaje duboko unutar besplatne Explorer kvote. Podaci o redovima uživo (queue, multi, border) menjaju se na svakih nekoliko minuta — njih povlačite po sopstvenom rasporedu i koristite multi da pročitate do 5 graničnih prelaza jednim zahtevom umesto u petlji.

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 уживо.

Стандардни koristi standardnu kvotu podataka  ·  Тежак koristi kvotu prognoze i statistike — vidi Квоте  ·  Рута за камионе троши се из сопствене квоте за руту за камионе — погледајте Квоте

Редови на граници

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

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

Мењачнице

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

Логистика

Возачи и путеви

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“ свуда где се подаци приказују. То одржава бесплатан план бесплатним.

Тачан код

Kopirajte ovaj isečak bez izmena. Link mora ostati indeksibilan: vidljiv, običan HTML <a href> pored podataka, koji Google može da indeksira i prati — NE dodajte rel="nofollow", rel="sponsored" ili rel="ugc" i ne skrivajte ga pomoću CSS-a. Link dodat preko JavaScript-a je u redu ako se pojavljuje na stranici koju Google renderuje (Uslovi Developer API v1.0, odeljak 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/sr/ — рачуна се свака видљива обична 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. Ово важи без обзира на то који план имате.
• Možemo odobriti samo neke od zemalja koje ste zatražili. Odobreni spisak, a ne onaj koji ste zatražili, određuje zemlje koje pokriva vaša licenca.
• Објављивање или редистрибуција наших података на непријављеном тржишту, или њихова препродаја као конкурентски податковни ток, крши ове услове и може суспендовати ваш кључ без упозорења.
• Неки планови се нуде само у одабраним регионима. Доступност зависи од тржишта која пријавите.
• Потпуни споразум чине Услови за Developer API. Они имају предност у односу на овај сажетак; обавезујућа је енглеска верзија.

Ažurnost podataka

Koliko su podaci sveži zavisi od vašeg plana. U samom odgovoru nema nikakve oznake — svi planovi vraćaju ista polja, iste tipove i istu strukturu odgovora.

• Plaćeni planovi — Student, Starter, Pro i Pro MAX: telemetrija uživo, bez kašnjenja.
• Besplatan Explorer plan: snimak poslednjih 15 do 30 minuta. Tačan pomak se razlikuje od zahteva do zahteva.

Odloženi odgovor nikada nije greška niti problem sa kvotom — to je potpun, ispravan odgovor sa starijim brojevima. Ponavljanje zahteva neće vratiti novije podatke.

Ako vašoj aplikaciji trebaju aktuelni podaci, svaki plaćeni plan vraća telemetriju u realnom vremenu.

Преузмите свој бесплатан API кључ