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)

Кезек, болжам немесе жүк көліктеріне тыйым салу деректерін Power Query-дің кіріктірілген JSON коннекторы арқылы тікелей жұмыс кітабына алыңыз — коды жоқ, кесте бойынша жаңартылады. Дәл сол 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

Excel-дегі Data → Refresh All немесе 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;

Үш нәрсені дұрыс істеу керек: 443 портына New OpenSSLSecureConnection беріңіз, әйтпесе сұрау TLS-те құлайды; /api/v1/data/fuel-ді country параметрсіз шақырыңыз — бір сұрау әр елге бөлек шақырудың орнына бәрін қайтарады; және data-ға тиер алдында ok мәнін тексеріңіз — қателер ерекше жағдай емес, ok:false және error.code түрінде келеді. Мысалда платформаның ағылшын тіліндегі кілт сөздері қолданылған; локализацияланған баламалары (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) дәл солай жұмыс істейді.

Дереккөздердегі жанармай бағалары тәулігіне бір рет өзгереді, сондықтан күніне бір-екі рет орындалатын жоспарланған тапсырма жеткілікті және тегін Explorer квотасының шегінде қалады. Кезектің тікелей деректері (queue, multi, border) бірнеше минут сайын өзгереді — оларды өз кестеңізбен сұраңыз және цикл орнына multi арқылы 20 өткізу пунктіне дейін бір сұраумен оқыңыз.

MCP сервері

REST орнына құралдарды шақыруды қалайсыз ба? Біз осы API-дің қауіпсіз, тек оқуға арналған ішкі жиынтығын MCP құралдары ретінде ұсынатын нақты MCP серверін (Streamable HTTP тасымалы) іске қосамыз — сол 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 соңғы нүктесі ЕМЕС; экспорттарды аккаунтыңыздағы "Деректі экспорттау" қойындысында құрып, жүктейсіз.

Қолжетімділік сұраныс бойынша беріледі: қай бекеттер, қандай уақыт аралығы және деректі не үшін қолданатыныңызды көрсетіп Дерек тикетін ашыңыз. Мақұлданғаннан кейін аккаунтыңызда «Деректі экспорттау» қойындысы пайда болады. Әдепкі шек: тәулігіне 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 арқылы көрсетпеңіз және 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/kk/ — nakordoni.eu-ге кез келген индекстелетін сілтеме есептеледі. "Data by nakordoni.eu" анкор мәтіні ағылшынша қалуы керек.

Қайда орналастыру

• Деректер блогының (кесте, график, виджет, жауап) тікелей жанында немесе астында — сол экранда, қосымша басусыз көрінетін.
• Біздің деректер көрсетілетін әрбір бетте немесе қолданба экранында — тек "біз туралы" бетінде ғана емес.
• Оқылатын өлшем мен контраст: кемінде ~11px, жасырылмаған, жиналмаған, фон түсінде емес.
• HTML сілтемелері жоқ нативті мобильді қолданбалар: деректер экранында "Data by nakordoni.eu" мәтінін көрсетіңіз, басылатын сілтемені ақпарат экранына қойыңыз.

Тіркелу кезінде көрсетілген "деректер қолданылатын бетте" атрибуцияны мерзімді тексереміз. Explorer жоспарында атрибуцияның болмауы немесе деиндекстелуі алдымен еске салуға, кейін кілтті тоқтатуға әкеледі. Pay As You Grow клиенттері атрибуцияны қалдыра алады.

Тегін API кілтіңізді алыңыз