Dokumentacioni i API

Autentikimi

Çdo kërkesë ka nevojë për çelësin tuaj API në header-in Authorization (rekomandohet) ose si parametër ?key=.

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Struktura e përgjigjes

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

Gabimet kthejnë ok:false me 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) dhe statusin HTTP 400/401/403/404/429/500/503/504. Header-at e kufizimit X-Devapi-Limit dhe X-Devapi-Remaining dërgohen në çdo përgjigje të matur. ok:false është përcaktues — mos e lexoni kurrë data në një thirrje të dështuar. Objekti usage është i pranishëm në çdo produkt të faturuar; /status është publik dhe i pafaturuar, prandaj nuk kthen usage.

Kuotat

Numëruesit ditorë rivendosen në mesnatë UTC. Merrni një email në 80% dhe 100% të kuotës.

Planet me pagesë e ngrenë secilin nga këta kufij. Planet aktuale dhe kufijtë e tyre: Planet

Shembuj kodi

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)

Merrni të dhëna live për radhët, parashikimet ose ndalimet për kamionë direkt në një libër pune me lidhësin e integruar JSON të Power Query — pa kod, me rifreskim sipas orarit. E njëjta skemë Headers funksionon për çdo produkt të këtij API — thjesht ndryshoni URL-në.

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

Mbajeni çelësin API brenda pyetjes M (Home → Advanced Editor), jo në një qelizë të fletës — Power Query bllokon një kërkesë web të ndërtuar nga një pyetje ose qelizë tjetër ("Formula.Firewall"), përveçse nëse niveli i privatësisë është vendosur në Organizational.

Disa pika kalimi kufitar në një tabelë të vetme (paneli i flotës) — 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 në Excel, ose një rifreskim i planifikuar në Power BI / Excel Online, i mban të dhënat aktuale — pa kod polling.

Integrimi me ERP (BAS / BAF dhe platformat e familjes 1C)

BAS / BAF dhe platformat e tjera të familjes 1C mund ta thërrasin këtë API drejtpërdrejt nga një detyrë e planifikuar — HTTPConnection plus ReadJSON, pa shtresë ndërmjetëse dhe pa shërbim shtesë. Skenari më i zakonshëm mban të përditësuar një regjistër informacioni me çmimet e karburanteve në BE.

Përditësimi i një regjistri informacioni (çmimet e karburanteve, të gjitha vendet me një thirrje)

// 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 gjëra duhen bërë saktë: kaloni New OpenSSLSecureConnection në portën 443, përndryshe kërkesa dështon në TLS; thirrni /api/v1/data/fuel pa parametrin country, që një kërkesë e vetme t’i kthejë të gjitha vendet në vend të një thirrjeje për secilin; dhe kontrolloni ok para se të prekni data — gabimet kthehen si ok:false me error.code, jo si përjashtim. Shembulli përdor grupin anglisht të fjalëve kyçe të platformës; ekuivalentët e lokalizuar (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) sillen njësoj.

Çmimet e karburanteve në burim ndryshojnë një herë në ditë, prandaj një detyrë e planifikuar një ose dy herë në ditë mjafton dhe mbetet thellë brenda kuotës falas Explorer. Të dhënat e radhëve në kohë reale (queue, multi, border) ndryshojnë çdo pak minuta — ato kërkojini me ritmin tuaj dhe përdorni multi për të lexuar deri në 5 pika kalimi me një kërkesë të vetme në vend të një cikli.

Server MCP

Preferoni thirrjen e mjeteve në vend të REST? Ne operojmë një server të vërtetë MCP (transport Streamable HTTP) që ekspozon një nënbashkësi të sigurt, vetëm-lexim, të këtij API si mjete MCP — e njëjta çelës API, e njëjta kuotë, thjesht një transport tjetër.

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

Konfigurimi i klientit (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "nakordoni": {
      "url": "https://nakordoni.eu/mcp",
      "headers": { "Authorization": "Bearer NKD-DEV-XXXX-XXXX-XXXX" }
    }
  }
}

OAuth për integrime (Home Assistant e të tjera)

Integrimet përdoruesit e të cilave kanë nevojë secili për çelësin e vet (integrime të personalizuara të Home Assistant, aplikacione desktop dhe mobile) mund ta lënë përdoruesin të hyjë në vend që të ngjitë një çelës. Rrjedha është OAuth 2.0 authorization code për klientë publikë me PKCE (S256) — nuk ka client secret. Tokeni i qasjes që kthejmë është çelësi NKD-DEV i vetë përdoruesit, të cilin e dërgon më pas si header Bearer saktësisht si deri tani.

Klientët nuk krijohen vetë: apliko në faqen e Integrimeve, çdo integrim e shqyrtojmë manualisht dhe lëshojmë një client ID me URI-t e lejuara të ridrejtimit. Çelësat e lëshuar përmes një klienti të miratuar aktivizohen menjëherë për tregjet e miratuara për atë integrim. Apliko për një klient integrimi →

• Kodi i autorizimit vlen 60 sekonda, përdoret vetëm një herë dhe është i lidhur me klientin, përdoruesin, URI-n e ridrejtimit dhe PKCE challenge.
• Çelësi kthehet vetëm në trupin e përgjigjes së tokenit (access_token) — kurrë në një URL. Ruaje si fjalëkalim.
• expires_in është 30 ditë; një rifreskim kthen të njëjtin çelës për sa kohë është aktiv. Nëse përdoruesi e anulon ose e rigjeneron çelësin, rifreskimi dështon me invalid_grant dhe thirrjet API kthejnë 401 — nise ri-autentikimin.
• Kërkesat kanë kufi shpejtësie për IP dhe kufi ditor për klient; gabimet ndjekin RFC 6749 (error, error_description).
• Çdo përdorues merr më së shumti kuotën e vet të vendeve: nëse integrimi juaj ka më shumë vende se vendet e lira të përdoruesit, ai i zgjedh në faqen e pëlqimit (dërgoni markets=DE,AT te /oauth/authorize për parazgjedhje). Të dyja përgjigjet token kthejnë gjithashtu markets_approved (vendet e miratuara të përdoruesit), markets_allowed (kuotën e tij; null = pa kufi), markets_available (vendet tuaja që ai ende nuk i ka) dhe upgrade_url (ku shton «Vende shtesë»).

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

Përdor config_entry_oauth2_flow me LocalOAuth2ImplementationWithPkce (client_secret bosh) dhe URI-n e ridrejtimit https://my.home-assistant.io/redirect/oauth, që është paraprakisht e regjistruar për klientët e Home Assistant. Lexo çelësin nga entry.data["token"]["access_token"] dhe vazhdo të thërrasësh API-n me Authorization: Bearer. Në rast 401 nga API, ngre ConfigEntryAuthFailed që Home Assistant të ofrojë ri-autentikim.

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)

Integrimet: shfaqni limitet e mbetura

GET /api/v2/account/usage — Sa ka mbetur nga limitet tuaja tani, për çelësin me të cilin thërrisni: plani, kufiri për sekondë dhe për çdo klasë kuote ditore (cheap, heavy, route) limiti, përdorur, mbetur dhe ora e rivendosjes (mesnatë UTC); gjithashtu vendet tuaja siç i sheh ky çelës dhe ku të përmirësoni planin. Nuk matet, 30 thirrje në minutë për çelës.

Çelësat e integrimit (OAuth) mund ta thërrasin gjithmonë GET /api/v2/account/usage, pavarësisht produkteve që lejon integrimi. Numrat përputhen me kokat X-Devapi-Limit dhe X-Devapi-Remaining; X-Devapi-Reset jep orën e rivendosjes si vulë kohore Unix.

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

Kur arrihet një kufi, gabimi tregon ku të shkoni: 429 quota_exceeded kthen gjithashtu error.reset_at (mesnata UTC) dhe error.upgrade_url; 403 market_not_allowed dhe 403 integration_product_not_allowed kthejnë error.upgrade_url. Çelësat e integrimit marrin edhe error.pass_url (Trip Pass, më poshtë).

Home Assistant: pyetni /account/usage më së shumti një herë në 15 minuta dhe shfaqni një sensor «thirrje të mbetura» nga quotas.cheap.remaining. Ndërmjet pyetjeve lexoni X-Devapi-Remaining nga thirrjet e zakonshme. Në 429 quota_exceeded ose 403 market_not_allowed krijoni një repair issue me lidhje te error.upgrade_url dhe ndalni thirrjet deri në reset_at.

Trip Pass

Përdoruesit e integrimeve mund të blejnë një Trip Pass (1, 3, 7 ose 14 ditë, pagesë e njëhershme) në faqen e Faturimit. Sa kohë që është aktiv, çelësi i integrimit merr të gjitha vendet e integrimit, më shumë thirrje itinerari kamioni dhe të dhënash në ditë dhe një ritëm më të lartë; produktet e integrimit, kufijtë e parashikimeve dhe vonesa e të dhënave nuk ndryshojnë. Çelësat e zhvilluesit të së njëjtës llogari nuk rriten kurrë.

Për çelësat e integrimit, account/usage kthen pass: {active, expires_at, days_left} dhe pass_url (seksioni Trip Pass i faqes së Faturimit); 429 quota_exceeded dhe 403 market_not_allowed / integration_product_not_allowed mbajnë të njëjtin error.pass_url. Për çelësat e tjerë të dyja janë 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.

Produktet

Zgjidhni një endpoint për referencën e tij të plotë, parametrat, versionet dhe një Sandbox të drejtpërdrejtë.

Standard përdor kuotën standarde të të dhënave  ·  I rëndë përdor kuotën e parashikimit dhe statistikave — shiko Kuotat  ·  Itinerar kamionësh zbritet nga kuota e vet e itinerarit të kamionëve — shih Kuotat

Radhë kufitare

Parashikime dhe Statistika

Karburanti dhe Vendndodhjet

Zyra këmbimi valutor

Planifikimi i Udhëtimit

Logjistikë

Shoferë dhe Rrugë

Your Fleet (NakBus Live)

Asistenti AI

Të tjera

Eksporti i të dhënave historike

Zhvilluesit e miratuar mund të shkarkojnë historikun e publikuar të radhëve kufitare, të mesatarizuar për orë, për deri në 5 pika kufitare (dritare rrëshqitëse deri në 90 ditë) si CSV, NDJSON ose JSON të kompresuar me gzip. Kjo është një veçori vetëm e portalit — JO një endpoint i API-t; eksportet i ndërtoni dhe i shkarkoni nga skeda „Eksporti i të dhënave“ në llogarinë tuaj.

Qasja jepet me kërkesë: hapni një biletë Data duke na treguar cilat pika kufitare, intervalin kohor dhe qëllimin e përdorimit. Pas miratimit, skeda „Eksporti i të dhënave“ shfaqet në llogarinë tuaj. Kufiri i parazgjedhur: 1 eksport në ditë, deri në 5 pika kufitare secili — na kërkoni ta rrisim.

Fushat — një rresht për çdo pikë kufitare për çdo orë UTC

Eksportohen vetëm të dhëna të publikuara, të cilat kalojnë kontrollet tona për anomali dhe cilësi (pa të dhëna të papërpunuara raportimi). Të gjitha vulat kohore janë në UTC. Skedarët ruhen 10 ditë.

Prejardhja: çdo skedar mbart në kokën e tij një gjurmë të nënshkruar (sha256 + HMAC), kështu që çdo kopje mund të konfirmohet më vonë si e dhënë autentike e nakordoni.eu dhe të kontrollohet për ndryshime — edhe pas shkarkimit.

# 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

Çfarë mund të ndërtoni

Të njëjtat produkte të dhënash krijojnë vizualizimet në nakordoni.eu — grafikë parashikimi javor, profile orare të radhëve, karta statusi në kohë reale. Një shije e asaj që përmbajnë API-të e parashikimit dhe statistikave:

Atribuimi

Integrimet e planit Explorer duhet të shfaqin një lidhje të dukshme "Data by nakordoni.eu" kudo që shfaqen të dhënat. Kjo e mban planin falas, falas.

Kodi i saktë

Kopjojeni këtë fragment ashtu siç është. Lidhja duhet të mbetet e indeksueshme: një <a href> HTML i dukshëm dhe i thjeshtë pranë të dhënave, që Google mund ta indeksojë dhe ta ndjekë — MOS shtoni rel="nofollow", rel="sponsored" ose rel="ugc" dhe mos e fshihni me CSS. Një lidhje e shtuar me JavaScript është në rregull nëse shfaqet në faqen që Google e renderon (Kushtet e Developer API v1.0, seksioni 8.1).

<a href="https://nakordoni.eu/" title="Border queues, forecasts &amp; statistics">Data by nakordoni.eu</a>

Variant kompakt me shkronja të vogla (p.sh. nën një grafik ose widget):

<p style="font-size:12px;margin:4px 0">
  Data by <a href="https://nakordoni.eu/">nakordoni.eu</a>
</p>

Mund të lidheni edhe me versionin tuaj gjuhësor, p.sh. https://nakordoni.eu/sq/ — vlen çdo lidhje HTML e dukshme dhe e zakonshme drejt nakordoni.eu. Teksti i ankorës "Data by nakordoni.eu" duhet të mbetet në anglisht.

Ku ta vendosni

• Direkt pranë ose nën bllokun e të dhënave (tabelë, grafik, widget, përgjigje) — në të njëjtin ekran, i dukshëm pa klikime shtesë.
• Në çdo faqe ose ekran aplikacioni ku shfaqen të dhënat tona — jo vetëm në faqen "rreth nesh".
• Madhësi dhe kontrast i lexueshëm: të paktën ~11px, jo i fshehur, jo i palosur, jo në ngjyrën e sfondit.
• Aplikacione mobile native pa lidhje HTML: shfaqni tekstin "Data by nakordoni.eu" në ekranin e të dhënave dhe vendoseni lidhjen e klikueshme në ekranin e informacionit.

Verifikojmë periodikisht atribuimin në "faqen ku përdoren të dhënat" që deklaruat gjatë regjistrimit. Atribuimi që mungon ose është i fshehur në planin falas Explorer sjell fillimisht një kujtesë, pastaj pezullimin e çelësit. Klientët me plan me pagesë mund ta lënë pa atribuim.

Kontrollet bëhen afërsisht një herë në javë nga verifikuesi ynë, user agent-i i të cilit përmban NakordoniComplianceBot/1.0. Ai hap vetëm faqet e listuara në panelin tuaj të zhvilluesit, nuk ndjek lidhje të tjera dhe e shpërfill robots.txt për ato faqe, sepse pikërisht ato na keni kërkuar t'i kontrollojmë. Nëse mbrojtja nga botët ose një firewall bllokon crawler-at e panjohur, lejoni këtë user agent — nëse nuk arrijmë ta hapim një faqe, do t'ju shkruajmë me një tiketë.

Licenca e të dhënave dhe tregjet

Çelësi juaj API jep licencë për përdorimin e të dhënave tona vetëm në vendet që keni deklaruar gjatë regjistrimit. Shqyrtojmë çdo deklaratë përpara se të japim qasje të plotë, sepse të dhënat tona janë produkti ynë dhe nuk i licencojmë në tregje pa ditur ku do të publikohen.

• Deklaroni çdo vend që i shërben faqja, aplikacioni ose produkti juaj. Listën mund ta ndryshoni në çdo kohë nga paneli juaj; një ndryshim e kthen llogarinë tuaj sërish në shqyrtim.
• Derisa tregjet tuaja të miratohen, çelësi juaj funksionon me limite të reduktuara - gjysma e kuotës së planit Starter. Kjo vlen pavarësisht cilit plan i përkisni.
• Ne mund të aprovojmë vetëm disa nga vendet që keni kërkuar. Lista e aprovuar, jo ajo e kërkuar, përcakton vendet që mbulon licenca juaj.
• Publikimi ose rishpërndarja e të dhënave tona në një treg të padeklaruar, ose rishitja e tyre si burim të dhënash konkurrues, shkel këto kushte dhe mund të pezullojë çelësin tuaj pa paralajmërim.
• Disa plane ofrohen vetëm në rajone të zgjedhura. Disponueshmëria varet nga tregjet që deklaroni.
• Marrëveshja e plotë janë Kushtet e Developer API. Ato kanë përparësi ndaj kësaj përmbledhjeje; versioni detyrues është ai anglisht.

Freshness e të dhënave

Sa të freskëta janë të dhënat varet nga plani juaj. Në vetë përgjigjen nuk ka asnjë shënues — të gjitha planet kthejnë të njëjtat fusha, të njëjtat tipe dhe të njëjtën strukturë përgjigjeje.

• Planet me pagesë — Student, Starter, Pro dhe Pro MAX: telemetri e drejtpërdrejtë, pa vonesë.
• Plani falas Explorer: një fotografi e 15 deri 30 minutave të fundit. Zhvendosja e saktë ndryshon nga kërkesa në kërkesë.

Një përgjigje e vonuar nuk është kurrë gabim dhe as problem kuote — është një përgjigje e plotë dhe e vlefshme me numra më të vjetër. Përsëritja e kërkesës nuk kthen të dhëna më të reja.

Nëse aplikacioni juaj ka nevojë për të dhëna aktuale, çdo plan me pagesë kthen telemetri në kohë reale.

Merrni çelësin tuaj API falas