API Dokümantasyonu

Kimlik doğrulama

Her istek, API anahtarınızı Authorization üst bilgisinde (önerilen) veya ?key= parametresi olarak gerektirir.

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

Yanıt zarfı

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

Hatalar, 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) ve HTTP durumu 400/401/403/404/429/500/503/504 ile ok:false döndürür. X-Devapi-Limit ve X-Devapi-Remaining hız sınırı üst bilgileri, ölçülen her yanıtta gönderilir. ok:false belirleyicidir — başarısız bir çağrıda data alanını asla okumayın. usage nesnesi ücretlendirilen her üründe bulunur; /status herkese açıktır ve ücretlendirilmez, bu nedenle usage döndürmez.

Kotalar

Günlük sayaçlar gece yarısı UTC'de sıfırlanır. Kotanın %80 ve %100'ünde bir e-posta alırsınız.

Ücretli planlar bu limitlerin her birini yükseltir. Güncel planlar ve kotaları: Planlar

Kod örnekleri

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'nin yerleşik JSON bağlayıcısıyla canlı kuyruk, tahmin veya kamyon yasağı verilerini doğrudan bir çalışma kitabına alın — kod yok, zamanlanmış yenileme. Aynı Headers şeması bu API'deki her ürün için çalışır — sadece URL'yi değiştirin.

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 anahtarını bir sayfa hücresinde değil, M sorgusunun içinde saklayın (Home → Advanced Editor) — gizlilik düzeyi Organizational olarak ayarlanmadıkça Power Query, başka bir sorgu veya hücreden oluşturulan web isteğini engeller ("Formula.Firewall").

Tek tabloda birden fazla sınır kapısı (filo panoları) — 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'de Data → Refresh All veya Power BI / Excel Online'da zamanlanmış yenileme, sayıları güncel tutar — polling kodu gerekmez.

ERP entegrasyonu (BAS / BAF ve 1C ailesi platformlar)

BAS / BAF ve diğer 1C ailesi platformlar bu API’yi doğrudan zamanlanmış bir görevden çağırabilir — HTTPConnection ve ReadJSON, ara katman ya da barındırılacak ek servis olmadan. En yaygın kurulum, AB akaryakıt fiyatlarını tutan bir bilgi kaydını güncel tutar.

Bilgi kaydını yenileme (akaryakıt fiyatları, tüm ülkeler tek çağrıda)

// 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;

Üç noktayı doğru yapın: 443 numaralı bağlantı noktasında New OpenSSLSecureConnection geçin, yoksa istek TLS’te düşer; /api/v1/data/fuel adresini country parametresi olmadan çağırın ki tek istek her ülke için ayrı çağrı yerine hepsini döndürsün; ve data’ya dokunmadan önce ok değerini kontrol edin — hatalar istisna olarak değil, error.code taşıyan ok:false olarak döner. Örnek, platformun İngilizce anahtar sözcük kümesini kullanır; yerelleştirilmiş karşılıkları (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) aynı şekilde çalışır.

Akaryakıt fiyatları kaynağında günde bir kez değişir; bu yüzden günde bir ya da iki kez çalışan zamanlanmış bir görev yeterlidir ve ücretsiz Explorer kotasının çok altında kalır. Canlı kuyruk verileri (queue, multi, border) birkaç dakikada bir değişir — bunları kendi programınızla sorgulayın ve döngü yerine multi ile tek istekte 5 sınır kapısına kadar okuyun.

MCP Sunucusu

REST yerine araç çağırmayı mı tercih ediyorsunuz? Bu API'nin güvenli, salt okunur bir alt kümesini MCP araçları olarak sunan gerçek bir MCP sunucusu (Streamable HTTP taşıması) çalıştırıyoruz — aynı API anahtarı, aynı kota, sadece farklı bir taşıma.

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

İstemci yapılandırması (Claude Desktop / Claude Code):

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

Entegrasyonlar için OAuth (Home Assistant ve diğerleri)

Her kullanıcısının kendi anahtarına ihtiyaç duyduğu entegrasyonlar (Home Assistant özel entegrasyonları, masaüstü ve mobil uygulamalar), kullanıcıdan anahtar yapıştırmasını istemek yerine oturum açmasına izin verebilir. Akış, PKCE (S256) ile genel istemciler için OAuth 2.0 authorization code akışıdır — client secret yoktur. Döndürdüğümüz erişim belirteci, kullanıcının kendi NKD-DEV anahtarıdır; bunu şimdiye kadar olduğu gibi Bearer başlığı olarak gönderirsiniz.

İstemciler self-servis değildir: Entegrasyonlar sayfasından başvurun, her entegrasyonu elle inceleriz ve izin verilen yönlendirme URI’leriyle bir client ID veririz. Onaylı bir istemci aracılığıyla verilen anahtarlar, o entegrasyon için onaylanan pazarlarda anında etkinleşir. Entegrasyon istemcisi için başvurun →

• Yetkilendirme kodu 60 saniye geçerlidir, tek kullanımlıktır ve istemciye, kullanıcıya, yönlendirme URI’sine ve PKCE challenge’a bağlıdır.
• Anahtar yalnızca belirteç yanıtının gövdesinde (access_token) döndürülür — asla bir URL’de değil. Onu bir parola gibi saklayın.
• expires_in 30 gündür; yenileme, anahtar etkin olduğu sürece aynı anahtarı döndürür. Kullanıcı anahtarı iptal eder veya yeniden oluşturursa yenileme invalid_grant ile başarısız olur ve API çağrıları 401 döndürür — yeniden kimlik doğrulamayı başlatın.
• İstekler IP başına hız sınırlıdır ve istemci başına günlük olarak sınırlandırılır; hatalar RFC 6749’u (error, error_description) izler.
• Her kullanıcı en fazla kendi ülke hakkını alır: entegrasyonunuz kullanıcının boş yerinden fazla ülke içeriyorsa kullanıcı bunları onay sayfasında seçer (ön seçim için /oauth/authorize'a markets=DE,AT gönderin). Her iki token yanıtı da markets_approved (kullanıcının onaylı ülkeleri), markets_allowed (hakkı; null = sınırsız), markets_available (henüz sahip olmadığı ülkeleriniz) ve upgrade_url («Ek ülkeler» ekleyeceği yer) döndürür.

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’u LocalOAuth2ImplementationWithPkce (client_secret boş) ve Home Assistant istemcileri için önceden kaydedilmiş https://my.home-assistant.io/redirect/oauth yönlendirme URI’si ile kullanın. Anahtarı entry.data["token"]["access_token"] içinden okuyun ve API’yi Authorization: Bearer ile çağırmaya devam edin. API’den 401 alırsanız, Home Assistant’ın yeniden kimlik doğrulama sunması için ConfigEntryAuthFailed oluşturun.

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)

Entegrasyonlar: kalan limitleri gösterin

GET /api/v2/account/usage — Çağırdığınız anahtar için limitlerinizden şu an ne kaldığı: plan, saniye başına sınır ve her günlük kota sınıfı (cheap, heavy, route) için limit, kullanılan, kalan ve sıfırlanma zamanı (UTC gece yarısı); ayrıca bu anahtarın gördüğü ülkeleriniz ve nereden yükseltme yapılacağı. Sayılmaz, anahtar başına dakikada 30 çağrı.

Entegrasyon (OAuth) anahtarları, entegrasyonun izin verdiği ürünlerden bağımsız olarak GET /api/v2/account/usage uç noktasını her zaman çağırabilir. Sayılar X-Devapi-Limit ve X-Devapi-Remaining başlıklarıyla aynıdır; X-Devapi-Reset sıfırlanma zamanını Unix zaman damgası olarak verir.

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

Bir limite ulaşıldığında hata nereye gidileceğini söyler: 429 quota_exceeded ayrıca error.reset_at (UTC gece yarısı) ve error.upgrade_url döndürür; 403 market_not_allowed ve 403 integration_product_not_allowed error.upgrade_url döndürür. Entegrasyon anahtarları ayrıca error.pass_url alır (Trip Pass, aşağıda).

Home Assistant: /account/usage uç noktasını en fazla 15 dakikada bir sorgulayın ve quotas.cheap.remaining değerinden "kalan çağrı" sensörü oluşturun. Sorgular arasında X-Devapi-Remaining değerini normal çağrılardan okuyun. 429 quota_exceeded veya 403 market_not_allowed alındığında error.upgrade_url bağlantılı bir repair issue oluşturun ve reset_at zamanına kadar çağrıları durdurun.

Trip Pass

Entegrasyon kullanıcıları Faturalandırma sayfasından Trip Pass satın alabilir (1, 3, 7 veya 14 gün, tek seferlik ödeme). Etkin olduğu sürece entegrasyon anahtarı entegrasyonun tüm ülkelerini, günde daha fazla tır rotası ve veri çağrısını ve daha yüksek bir hızı alır; entegrasyonun ürünleri, tahmin limitleri ve veri gecikmesi değişmez. Aynı hesabın geliştirici anahtarları hiçbir zaman yükseltilmez.

Entegrasyon anahtarları için account/usage, pass: {active, expires_at, days_left} ve pass_url (Faturalandırma sayfasının Trip Pass bölümü) döndürür; 429 quota_exceeded ve 403 market_not_allowed / integration_product_not_allowed aynı error.pass_url'yi taşır. Diğer anahtarlar için ikisi de null'dır.

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.

Ürünler

Tam referansı, parametreleri, sürümleri ve canlı sanal alanı için bir uç nokta seçin.

Standart standart veri kotasını kullanır  ·  Ağır tahmin ve istatistik kotasından çeker — bkz. Kotalar  ·  Tır rotası kendi tır rotası kotasını kullanır — bkz. Kotalar

Sınır Kuyrukları

Tahminler ve İstatistikler

Yakıt ve Konumlar

Döviz büroları

Seyahat Planlaması

Lojistik

Sürücüler ve Yollar

Your Fleet (NakBus Live)

Yapay Zeka Asistanı

Diğer

Geçmiş veri dışa aktarımı

Onaylanmış geliştiriciler, en fazla 5 sınır kapısı için saatlik ortalaması alınmış, yayımlanmış sınır kuyruğu geçmişini (90 güne kadar kayan pencere) gzip'lenmiş CSV, NDJSON veya JSON olarak indirebilir. Bu yalnızca portala özgü bir özelliktir — bir API uç noktası DEĞİLDİR; dışa aktarımları hesabınızdaki "Veri dışa aktarma" sekmesinde oluşturur ve indirirsiniz.

Erişim talep üzerine verilir: hangi sınır kapılarını, hangi zaman aralığını ve verileri ne amaçla kullanacağınızı belirten bir Veri talebi açın. Onaylandıktan sonra hesabınızda Veri dışa aktarma sekmesi görünür. Varsayılan sınır: günde 1 dışa aktarma, her biri en fazla 5 sınır kapısı — artırmamızı isteyin.

Alanlar — sınır kapısı ve UTC saati başına bir satır

Veriler yalnızca yayımlanmış olanlardır ve dışa aktarımdan önce anomali / veri kalitesi kontrollerimizden geçer (ham rapor verisi yok). Tüm zaman damgaları UTC'dir. Dosyalar 10 gün saklanır.

Kaynak doğrulama: her dosya, başlığına imzalı bir parmak izi (sha256 + HMAC) gömer; böylece herhangi bir kopyanın gerçek nakordoni.eu verisi olduğu sonradan doğrulanabilir ve değiştirilip değiştirilmediği kontrol edilebilir — indirildikten sonra bile.

# 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

Neler oluşturabilirsiniz

Aynı veri ürünleri, nakordoni.eu üzerindeki görselleri oluşturur — haftalık tahmin grafikleri, saatlik kuyruk profilleri, canlı durum kartları. Tahmin ve istatistik API'lerinin içeriğinden bir tat:

Atıf

Explorer planı entegrasyonları, verinin görüntülendiği her yerde görünür bir "Data by nakordoni.eu" bağlantısı göstermelidir. Bu, ücretsiz planı ücretsiz tutar.

Tam kod

Bu kod parçasını olduğu gibi kopyalayın. Bağlantı dizine eklenebilir kalmalıdır: verilerin yanında Google'ın dizine ekleyip takip edebileceği görünür, sade bir HTML <a href> — rel="nofollow", rel="sponsored" veya rel="ugc" EKLEMEYİN ve CSS ile gizlemeyin. JavaScript ile eklenen bir bağlantı, Google'ın oluşturduğu sayfada görünüyorsa uygundur (Developer API Koşulları v1.0, bölüm 8.1).

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

Kompakt küçük yazı varyantı (örn. bir grafik veya widget altında):

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

Kendi dil sürümünüze de bağlantı verebilirsiniz, örneğin https://nakordoni.eu/tr/ — nakordoni.eu'ya giden görünür ve sıradan her HTML bağlantısı sayılır. Bağlantı metni "Data by nakordoni.eu" İngilizce kalmalıdır.

Nereye yerleştirilmeli

• Veri bloğunun (tablo, grafik, widget, yanıt) hemen yanına veya altına — aynı ekranda, ek tıklama olmadan görünür.
• Verilerimizin göründüğü her sayfada veya uygulama ekranında — yalnızca "hakkında" sayfasında değil.
• Okunabilir boyut ve kontrast: en az ~11px, gizli değil, daraltılmış değil, arka plan renginde değil.
• HTML bağlantısı olmayan yerel mobil uygulamalar: veri ekranında "Data by nakordoni.eu" metnini gösterin ve tıklanabilir bağlantıyı bilgi ekranına koyun.

Kayıt sırasında bildirdiğiniz "verilerin kullanıldığı sayfa" üzerinde atıfları düzenli olarak denetliyoruz. Ücretsiz Explorer planında eksik veya gizlenmiş atıf önce bir hatırlatmaya, ardından anahtarın askıya alınmasına yol açar. Ücretli plan müşterileri atıfı atlayabilir.

Kontroller yaklaşık haftada bir, user agent'ı NakordoniComplianceBot/1.0 içeren denetleyicimiz tarafından yapılır. Yalnızca geliştirici panelinizde listelenen sayfaları açar, başka bağlantıları izlemez ve bu sayfalar için robots.txt'yi dikkate almaz, çünkü kontrol etmemizi istediğiniz sayfalar tam da bunlardır. Bot koruması veya güvenlik duvarı bilinmeyen tarayıcıları engelliyorsa bu user agent'a izin verin — bir sayfayı açamazsak size destek talebiyle yazarız.

Veri lisansı ve piyasalar

API anahtarınız, kayıt sırasında beyan ettiğiniz ülkelerde ve yalnızca o ülkelerde verilerimizi kullanma lisansı verir. Tam erişim vermeden önce her beyanı inceleriz, çünkü verilerimiz kendi ürünümüzdür ve nerede yayınlanacağını bilmeden pazarlara lisanslamıyoruz.

• Sitenizin, uygulamanızın veya ürününüzün hizmet verdiği her ülkeyi beyan edin. Listeyi istediğiniz zaman panelinizden değiştirebilirsiniz; bir değişiklik hesabınızı tekrar incelemeye alır.
• Pazarlarınız onaylanana kadar anahtarınız düşürülmüş limitlerle çalışır — Starter planı kotasının yarısı. Bu, hangi planda olursanız olun geçerlidir.
• İstediğiniz ülkelerin sadece bazılarını onaylayabiliriz. Onaylanan liste, talep edilen değil, lisansınızın kapsadığı ülkeleri belirler.
• Verilerimizi beyan etmediğiniz bir pazarda yayınlamak veya yeniden dağıtmak ya da rakip bir veri akışı olarak yeniden satmak bu şartların ihlalidir ve anahtarınız bildirim yapılmadan askıya alınabilir.
• Bazı planlar yalnızca seçili bölgelerde sunulur. Kullanılabilirlik beyan ettiğiniz pazarlara bağlıdır.
• Sözleşmenin tamamı Developer API Koşulları belgesidir. Bu özete göre önceliklidir; bağlayıcı olan İngilizce sürümdür.

Veri tazeliği

Verilerin güncelliği tarifenize bağlıdır. Yanıtın kendisinde herhangi bir işaret yoktur — tüm tarifeler aynı alanları, aynı türleri ve aynı yanıt yapısını döndürür.

• Ücretli tarifeler — Student, Starter, Pro ve Pro MAX: gecikmesiz, canlı telemetri.
• Ücretsiz Explorer tarifesi: son 15–30 dakikaya ait bir anlık görüntü. Kesin gecikme miktarı istekten isteğe değişir.

Gecikmeli yanıt asla bir hata ya da kota sorunu değildir — daha eski sayılar içeren eksiksiz ve geçerli bir yanıttır. İsteği yinelemek daha yeni veri getirmez.

Uygulamanız güncel veriye ihtiyaç duyuyorsa, ücretli tarifelerin tümü gerçek zamanlı telemetri döndürür.

Ücretsiz API anahtarınızı alın