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, 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% од квотата.

Платените планови го креваат секој од овие лимити. Актуелните планови и нивните лимити: Планови

Примери на код

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→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 во 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" }
    }
  }
}

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.

Производи

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

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

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

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

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

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

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

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> поставен до податоците — не смее да се прикажува само преку JavaScript ниту да се крие со CSS. Од Условите за Developer API v1.0 (точка 8.1) можете да додадете rel="nofollow" или rel="sponsored", ако тоа го бара политиката на вашата страница.

<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/ — се брои секоја видлива обична HTML врска кон 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.
• Целосната спогодба се Услови за Developer API. Тие имаат предност пред ова резиме; обврзувачка е англиската верзија.

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

Колку се свежи податоците зависи од вашиот план. Во самиот одговор нема ознака — сите планови ги враќаат истите полиња, истите типови и истата структура на одговорот.

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

Задоцнетиот одговор никогаш не е грешка ниту проблем со квотата — тоа е целосен, валиден одговор со постари бројки. Повторното барање не враќа понови податоци.

Ако на вашата апликација ѝ требаат актуелни податоци, секој платен план враќа телеметрија во реално време.

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