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",
  "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, bad_request, internal_error) dhe statusin HTTP 401/403/404/429/500. Header-at e kufizimit X-Devapi-Limit dhe X-Devapi-Remaining dërgohen në çdo përgjigje të matur.

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

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

Radhë kufitare

Parashikime dhe Statistika

Karburanti dhe Vendndodhjet

Planifikimi i Udhëtimit

Shoferë dhe Rrugë

Your Fleet (NakBus Live)

Asistenti AI

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 siç është. Lidhja duhet të mbetet e indeksueshme: një HTML <a href> i thjeshtë që motorët e kërkimit mund ta ndjekin — MOS shtoni rel="nofollow" ose rel="sponsored", mos e shfaqni vetëm me JavaScript dhe mos e fshihni me CSS.

<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 me versionin tuaj gjuhësor, p.sh. https://nakordoni.eu/sq/ — llogaritet çdo lidhje e indeksueshme drejt nakordoni.eu. Teksti i spirancë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 e përdorimit të të dhënave" të dhënë në regjistrim. Mungesa ose deindeksimi i atribuimit në planin falas Explorer çon fillimisht në një kujtesë, pastaj në pezullim të çelësit. Klientët me plan me pagesë mund ta lënë jashtë atribuimin.

Licenca e të dhënave dhe tregjet

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.
• 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.
• 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.

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