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 арқылы 5 өткізу пунктіне дейін бір сұраумен оқыңыз.

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

Өнімдер

Толық анықтамасын, параметрлерін, нұсқаларын және тікелей сынақ алаңын көру үшін соңғы нүктені таңдаңыз.

Стандартты стандартты деректер квотасын қолданады  ·  Ауыр болжам мен статистика квотасын қолданады — қараңыз Квоталар

Шекара кезектері

Болжамдар мен статистика

Жанармай және орындар

Сапар жоспарлау

Жүргізушілер мен жолдар

Your Fleet (NakBus Live)

ЖИ көмекші

Тарихи деректерді экспорттау

Мақұлданған әзірлеушілер 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 жоспарында атрибуцияның болмауы немесе деиндекстелуі алдымен еске салуға, кейін кілтті тоқтатуға әкеледі. Ақылы жоспардағы клиенттер атрибуцияны қалдыра алады.

Деректер лицензиясы және нарықтар

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.

Деректердің жаңалығы

Деректердің жаңалығы сіздің тарифіңізге байланысты. Жауаптың өзінде ешқандай белгі жоқ — барлық тарифтер бірдей өрістерді, бірдей типтерді және жауаптың бірдей құрылымын қайтарады.

• Ақылы тарифтер — Student, Starter, Pro және Pro MAX: кідіріссіз, тікелей телеметрия.
• Тегін Explorer тарифі: соңғы 15–30 минуттағы дерек көшірмесі. Нақты ауытқу әр сұрауда әртүрлі болады.

Кідірген жауап ешқашан қате де, шектеу мәселесі де емес — бұл ескілеу сандары бар толыққанды, жарамды жауап. Сұрауды қайталау жаңарақ дерек қайтармайды.

Егер қосымшаңызға өзекті деректер қажет болса, кез келген ақылы тариф нақты уақыттағы телеметрияны қайтарады.

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