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, market_not_allowed, 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)

Кезек, болжам немесе жүк көліктеріне тыйым салу деректерін 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→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

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

Интеграцияларға арналған OAuth (Home Assistant және басқалары)

Әр пайдаланушыға жеке кілт қажет интеграциялар (Home Assistant реттелетін интеграциялары, десктоп және мобильді қолданбалар) кілтті қою орнына пайдаланушыға кіруге мүмкіндік бере алады. Ағын — PKCE (S256) бар жалпыға ортақ клиенттерге арналған OAuth 2.0 authorization code; client secret жоқ. Біз қайтаратын қолжетімділік токені — пайдаланушының өз NKD-DEV кілті, оны қазіргідей Bearer тақырыбымен жібересіз.

Клиенттер өздігінен жасалмайды: Интеграциялар бетінде өтінім беріңіз, біз әр интеграцияны қолмен қарастырып, рұқсат етілген қайта бағыттау URI-лерімен client ID береміз. Мақұлданған клиент арқылы берілген кілттер сол интеграцияға мақұлданған нарықтар үшін бірден белсендіріледі. Интеграция клиентіне өтінім беру →

• Авторизация коды 60 секунд жарамды, бір рет қолданылады және клиентке, пайдаланушыға, қайта бағыттау URI-іне және PKCE challenge-ке байланған.
• Кілт тек токен жауабының денесінде (access_token) қайтарылады — ешқашан URL-де емес. Оны құпиясөздей сақтаңыз.
• expires_in — 30 күн; жаңарту кілт белсенді болғанша сол кілтті қайтарады. Пайдаланушы кілтті қайтарып алса немесе қайта жасаса, жаңарту invalid_grant қатесімен аяқталады, ал API шақырулары 401 қайтарады — қайта аутентификацияны бастаңыз.
• Сұраулар әр IP бойынша жиілігімен шектелген және әр клиентке тәулігіне шектелген; қателер RFC 6749 бойынша беріледі (error, error_description).
• Әр пайдаланушы өз елдер лимитінен аспайтын көлемді алады: интеграцияда пайдаланушының бос орнынан көп ел болса, ол оларды келісім бетінде таңдайды (алдын ала таңдау үшін /oauth/authorize-ге markets=DE,AT беріңіз). Екі token жауабы да markets_approved (пайдаланушының бекітілген елдері), markets_allowed (оның лимиті; null = шектеусіз), markets_available (оның әлі жоқ сіздің елдеріңіз) және upgrade_url («Қосымша елдер» қосатын жер) өрістерін қайтарады.

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

config_entry_oauth2_flow құралын LocalOAuth2ImplementationWithPkce (client_secret бос) және Home Assistant клиенттері үшін алдын ала тіркелген https://my.home-assistant.io/redirect/oauth қайта бағыттау URI-імен пайдаланыңыз. Кілтті entry.data["token"]["access_token"] ішінен оқыңыз және API-ді Authorization: Bearer арқылы шақыруды жалғастырыңыз. API-ден 401 келсе, Home Assistant қайта аутентификацияны ұсынуы үшін ConfigEntryAuthFailed шақырыңыз.

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)

Интеграциялар: қалған лимиттерді көрсетіңіз

GET /api/v2/account/usage — Шақыратын кілтіңіз үшін лимиттеріңізден қазір қанша қалғаны: жоспар, секундтық лимит және әр күндік квота класы (cheap, heavy, route) үшін лимит, жұмсалғаны, қалғаны және нөлдену уақыты (UTC түн ортасы); сондай-ақ осы кілт көретін елдеріңіз және жоспарды қайдан көтеруге болатыны. Есептелмейді, бір кілтке минутына 30 шақыру.

Интеграция (OAuth) кілттері интеграцияға қандай өнімдер рұқсат етілсе де, GET /api/v2/account/usage-ті әрқашан шақыра алады. Сандары X-Devapi-Limit және X-Devapi-Remaining тақырыптарымен сәйкес келеді; X-Devapi-Reset нөлдену уақытын Unix timestamp түрінде береді.

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

Лимитке жеткенде қате қайда бару керегін айтады: 429 quota_exceeded сонымен қатар error.reset_at (UTC түн ортасы) және error.upgrade_url қайтарады; 403 market_not_allowed және 403 integration_product_not_allowed error.upgrade_url қайтарады. Интеграция кілттері error.pass_url-ді де алады (Trip Pass, төменде).

Home Assistant: /account/usage-ті 15 минутта бір реттен жиі сұрамаңыз және quotas.cheap.remaining негізінде «қалған шақырулар» сенсорын шығарыңыз. Сұраулар арасында X-Devapi-Remaining мәнін әдеттегі шақырулардан оқыңыз. 429 quota_exceeded немесе 403 market_not_allowed кезінде error.upgrade_url сілтемесі бар repair issue жасап, шақыруларды reset_at дейін тоқтатыңыз.

Trip Pass

Интеграция пайдаланушылары төлем бетінде Trip Pass сатып ала алады (1, 3, 7 немесе 14 күн, бір реттік төлем). Ол әрекет етіп тұрғанда интеграция кілті интеграцияның барлық елдерін, тәулігіне көбірек жүк көлігі маршруты мен деректер сұрауын және жоғары жиілікті алады; интеграция өнімдері, болжам лимиттері және деректер кешігуі өзгермейді. Сол аккаунттың әзірлеуші кілттері ешқашан арттырылмайды.

Интеграция кілттері үшін account/usage pass: {active, expires_at, days_left} және pass_url (төлем бетінің Trip Pass бөлімі) қайтарады; 429 quota_exceeded және 403 market_not_allowed / integration_product_not_allowed сол error.pass_url-ді қамтиды. Басқа кілттер үшін екеуі де 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.

Өнімдер

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

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

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

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

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

Валюта айырбастау пункттері

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

Логистика

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

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>, оны Google индекстей және өтіп кете алады — rel="nofollow", rel="sponsored" немесе rel="ugc" ҚОСПАҢЫЗ және оны CSS арқылы жасырмаңыз. JavaScript арқылы қосылған сілтеме Google рендерлейтін бетте көрінсе, жарамды (Developer API шарттары v1.0, 8.1-бөлім).

<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-ға апаратын кез келген көрінетін кәдімгі HTML сілтеме есептеледі. Анкер мәтіні "Data by nakordoni.eu" ағылшын тілінде қалуы тиіс.

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

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

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

Тексеру шамамен аптасына бір рет біздің тексеруші ботымызбен жүргізіледі, оның user agent-інде NakordoniComplianceBot/1.0 бар. Ол тек әзірлеуші панеліңізде көрсетілген беттерді ашады, басқа сілтемелерге өтпейді және бұл беттер үшін robots.txt-ті ескермейді, себебі дәл соларды тексеруді сұрадыңыз. Боттардан қорғау немесе файрвол белгісіз краулерлерді бұғаттаса, осы user agent-ке рұқсат беріңіз — бетті аша алмасақ, сізге тикет арқылы жазамыз.

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

API кілтіңіз тек тіркелу кезінде декларацияланған елдерде ғана деректерімізді пайдалануға лицензия береді. Толық қолжетімділік беру алдында біз әр декларацияны қараймыз, себебі деректеріміз — біздің меншікті өнім, және оны қай жерде жарияланатынын білмей нарықтарға лицензиялай алмаймыз.

• Сайтыңыз, қолданбаңыз немесе өніміңіз қызмет ететін әрбір елді декларациялаңыз. Тізімді кез келген уақытта басқару панеліңізден өзгерте аласыз; өзгеріс аккаунтыңызды қайта тексеруге қайтарады.
• Нарықтарыңыз мақұлданғанша кілтіңіз азайтылған лимиттермен жұмыс істейді — Starter жоспарының лимитінің жартысы. Бұл сіз қандай жоспарда болсаңыз да қолданылады.
• Сіз сұраған елдердің тек кейбіреулерін ғана бекіте аламыз. Сұраған тізімі емес, бекітілген тізім сіздің лицензияңыз жауап беретін елдерді анықтайды.
• Деректерімізді декларацияламаған нарықта жариялау немесе тарату, не оны бәсекелес деректер ағыны ретінде қайта сату осы шарттарды бұзу болып табылады және кілтіңізді ескертусіз тоқтата алады.
• Кейбір жоспарлар тек таңдаулы аймақтарда ғана ұсынылады. Қолжетімділік сіз декларациялаған нарықтарға байланысты.
• Толық келісім — Developer API шарттары. Ол осы қысқаша сипаттамадан басым; заңды күші бар нұсқа — ағылшын тіліндегісі.

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

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

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

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

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

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