Yazar Haber Ajansı Abone API

Yazar Haber Ajansı API ile Haber Çekme: Kimlik Doğrulama, JSON ve Örnek Kodlar

Yazar Haber Ajansı API (Abone API'si), servis edilen haberleri, fotoğrafları ve videoları HTTPS üzerinden JSON olarak çekmenizi sağlayan bir REST arayüzüdür. Kök adres https://api.yha.com.tr/v1'dir; her istek Authorization: Bearer <anahtar> başlığı taşır. API ile haber çekmek için paketinizde API kanalı açık bir YHA aboneliği, YHA Abone'de ürettiğiniz anahtar ve HTTP isteği gönderebilen herhangi bir programlama dili yeterlidir. Bu sayfada kimlik doğrulamadan hata yönetimine kadar tüm akışı ve curl, PHP, Python örneklerini bulacaksınız.

API, YHA entegrasyon seçenekleri içinde en esnek olanıdır: akışı imleçle kaldığınız yerden okur, kategoriye, ile, önceliğe ve içerik türüne göre süzer, arşivde arama yapar ve sonuçları kendi içerik yönetim sisteminize istediğiniz biçimde aktarırsınız. Diğer yöntemlerle karşılaştırma için Yazar Haber Ajansı geliştirici belgeleri ana sayfasına bakabilirsiniz.

Bu sayfa bir özettir. Uçların, parametrelerin ve yanıt şemalarının tam listesi OpenAPI 3.1 belgesindedir: https://api.yha.com.tr/v1/openapi.json (anahtarsız).

API'yi ne zaman kullanmalısınız?

API ile haber çekmek özellikle şu durumlarda doğru tercihtir:

• Kendi yazdığınız ya da özel geliştirilmiş bir haber yazılımınız varsa.
• Haberleri kategori, il, öncelik veya tarih aralığına göre seçici biçimde almak istiyorsanız.
• Mobil uygulama, ekran veya bülten sistemi gibi birden fazla kanala aynı veriyi dağıtıyorsanız.
• Düzeltmeleri ve iptalleri otomatik olarak yansıtmanız gerekiyorsa.

Yalnızca bir besleme okuyabiliyorsanız YHA RSS ve Atom beslemeleri daha hızlı kurulur. WordPress kullanıyorsanız ajansın eklentisi bu API'yi sizin yerinize kullanır.

Kimlik doğrulama

Her istek Authorization: Bearer <anahtar> başlığı taşır. Anahtar sorgu dizgesinde kabul edilmez; böylece sunucu günlüklerine ve vekil sunuculara düşmez.

GET /v1/ben HTTP/1.1
Host: api.yha.com.tr
Authorization: Bearer yha_canli_...

Anahtarları YHA Abone · Çıkışlar · Anahtarlar ekranında siz üretirsiniz; anahtar yalnızca bir kez gösterilir. İki ortam vardır:

Canlı anahtar deneme adresinde, deneme anahtarı canlıda 401 anahtar_ortami_uyusmuyor alır. Canlı anahtar için kurumunuz adına API kullanım şartları bir kez onaylanır. Anahtarın kapsamı hangi uçları açacağını belirler: akis.oku (akış, anlık akış, haberler, varlıklar, sözlükler), icerik.indir (medya dosyası) ve arsiv.ara (arama). İçerik her zaman paket hakkınızla sınırlıdır. Ayrıntılar: Kimlik ve anahtarlar.

API anahtarı için güvenlik kuralları:

• Anahtarı yalnızca sunucu tarafında kullanın. Tarayıcıdan (CORS) istek zaten kabul edilmez; mobil uygulama paketine veya herkese açık bir Git deposuna da koymayın.
• Anahtarı kodun içine yazmak yerine ortam değişkeninde (YHA_ANAHTAR gibi) veya bir gizli bilgi yöneticisinde saklayın.
• Anahtarı daraltın: en çok 20 IP bloğu, anahtara özel günlük sınır, paket kısıtı ve son kullanma tarihi tanımlayabilirsiniz.
• Anahtar sızarsa YHA Abone'den hemen iptal edin ve yenisini üretin. Planlı değişimde "Döndür" yeni anahtar üretir; eskisi seçtiğiniz geçiş süresince (0–168 saat, varsayılan 24) çalışmaya devam eder.

Temel uçlar

Bütün okuma uçları GET'tir; yanıtlar UTF-8 JSON, zamanlar ISO 8601 UTC'dir.

Süzgeçler: akışta icerik (haber, fotograf, video), kategori_id (sözlükteki kategori kimlikleri, virgülle birden fazla), il_id (plaka, 1–81), oncelik (flas, onemli, normal), olay (varsayılan yeni,duzeltme,iptal), paket_id ve boyut (varsayılan 50, en çok 100). /v1/haberler ayrıca baslangic, bitis (ISO 8601 ya da YYYY-AA-GG), durum ve dil alır; /v1/ara zorunlu q (1–300 karakter) ile çalışır.

Tarih parametrelerinde saat dilimli bir ISO 8601 değer gönderecekseniz URL içinde + işaretini %2B olarak kodlayın; aksi halde birçok sunucu + karakterini boşluk olarak yorumlar.

Akış ve imleç (sayfa numarası yoktur)

YHA'da sayfa numarası ve toplam sayı yoktur; bütün listeler imleçlidir. Yanıt { "ogeler", "sonraki_imlec", "devami_var" } biçimindedir. Akışta döngü şöyledir:

1. İlk istekte imleç vermeyin: akış son 24 saatten (ya da baslangic'tan) başlar; en çok 7 gün geri gidilir. Daha eskisi için /v1/haberler ve /v1/ara kullanılır.
2. Yanıttaki sonraki_imlec'i saklayın ve bir sonraki istekte ?imlec= olarak verin.
3. devami_var doğruysa hemen yeniden sorun; yanlışsa en erken 10 saniye bekleyin. Daha sık soran dakikalık sınıra takılır.

Ayrıntılı anlatım: Akış ve imleç.

JSON yanıt örneği

Yanıtlar UTF-8 kodludur ve RFC 8259 JSON standardına uyar. Akıştaki her öğe bir olaydır (DisOlay); olay alanı yeni, duzeltme, iptal ya da guncelleme olabilir. Aşağıda kısaltılmış bir akış yanıtı görüyorsunuz:

{
  "ogeler": [
    {
      "olay_id": "…",
      "imlec": "MjAyNi0xMC0wN1Qx…",
      "olay": "duzeltme",
      "zaman": "2026-10-07T11:19:00Z",
      "icerik": "haber",
      "haber": {
        "id": "…",
        "no": "H-001230",
        "surum_no": 2,
        "durum": "serviste",
        "oncelik": "normal",
        "baslik": "…",
        "spot": "…",
        "govde": "…",
        "kategori": { "id": "…", "kod": "ekonomi", "ad": "Ekonomi" },
        "il": { "id": 61, "ad": "Trabzon" },
        "imza": "…",
        "ilk_servis_zamani": "2026-10-07T10:02:00Z",
        "servis_zamani": "2026-10-07T11:19:00Z",
        "embargo": null,
        "kullanim": { "kaynak_gosterme_notu": "…", "kullanim_kisiti": null },
        "tanitim": false,
        "iptal": null,
        "duzeltmeler": [ { "zaman": "2026-10-07T11:19:00Z", "surum_no": 2, "not": "…" } ],
        "medya": []
      },
      "varlik": null
    }
  ],
  "sonraki_imlec": "MjAyNi0xMC0wN1Qx…",
  "devami_var": false
}

En önemli kurallar: haber kimliğini (id) veritabanınızda benzersiz anahtar olarak saklayın, aynı olay iki kez gelebileceği için olay_id'yi ayıklayın ve düzeltmeyi yalnızca surum_no sizdekinden büyükse uygulayın. İptalde govde, spot ve medya boş gelir; haberi yayından kaldırın. Alanların tamamı geliştirici belgelerindeki haber veri modeli bölümünde özetlenir.

Örnek kodlar

curl

export YHA_ANAHTAR=yha_deneme_...
curl -s "https://deneme.yha.com.tr/v1/ben" -H "Authorization: Bearer $YHA_ANAHTAR"
curl -s "https://deneme.yha.com.tr/v1/akis?boyut=50" -H "Authorization: Bearer $YHA_ANAHTAR"
curl -s "https://deneme.yha.com.tr/v1/akis?imlec=$IMLEC" -H "Authorization: Bearer $YHA_ANAHTAR"

PHP

<?php
$kok     = getenv('YHA_KOK') ?: 'https://deneme.yha.com.tr';
$anahtar = getenv('YHA_ANAHTAR');
$dosya   = __DIR__ . '/imlec.txt';
$imlec   = is_file($dosya) ? trim(file_get_contents($dosya)) : '';

$sorgu = ['boyut' => 100] + ($imlec !== '' ? ['imlec' => $imlec] : []);
$ch = curl_init($kok . '/v1/akis?' . http_build_query($sorgu));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $anahtar, 'Accept: application/json'],
]);
$yanit = curl_exec($ch);
$durum = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$g = json_decode((string) $yanit, true);
if ($durum !== 200) {
    error_log('YHA API: ' . $durum . ' ' . ($g['hata']['kod'] ?? ''));
    exit(1);
}
foreach ($g['ogeler'] as $olay) {
    // olay_id ile ayıkla, haber id'sine göre ekle, düzelt ya da kaldır
    echo $olay['olay'], ' ', $olay['haber']['no'] ?? $olay['varlik']['no'], PHP_EOL;
}
if ($g['sonraki_imlec']) {
    file_put_contents($dosya, $g['sonraki_imlec']);
}

Python

import os, time, requests

KOK = os.environ.get("YHA_KOK", "https://deneme.yha.com.tr")
OTURUM = requests.Session()
OTURUM.headers["Authorization"] = f"Bearer {os.environ['YHA_ANAHTAR']}"
imlec = oku_imlec()  # kendi deponuzdan

while True:
    y = OTURUM.get(f"{KOK}/v1/akis", params={"imlec": imlec, "boyut": 100}, timeout=30)
    if y.status_code == 429:
        time.sleep(int(y.headers.get("Retry-After", "10")))
        continue
    y.raise_for_status()
    g = y.json()
    for olay in g["ogeler"]:
        isle(olay)  # olay_id ile ayıkla, surum_no ile düzelt, iptalde kaldır
    if g["sonraki_imlec"]:
        imlec = g["sonraki_imlec"]
        yaz_imlec(imlec)
    if not g["devami_var"]:
        time.sleep(10)

Daha kapsamlı başvuru bağlayıcıları (Python, JavaScript, PHP, C#) imleç, ayıklama, düzeltme, iptal, embargo, kaynak notu ve medya indirmeyi doğru yapar; entegrasyon kitinde bulunur.

Medya dosyalarını indirme

haber.medya yalnızca paketinizin açtığı medyayı taşır. Dosyayı GET /v1/varliklar/{id}/dosya?secenek=web ile alırsınız: 303 ile süreli, imzalı bir adrese yönlendirilirsiniz (curl -L). İmzalı adrese giderken Authorization başlığını taşımayın. Kopya hazırlanıyorsa 202 ve Retry-After gelir; o kadar bekleyip yeniden deneyin. Seçenekler fotoğrafta kucuk, web, orijinal; videoda 1080p, 720p, 480p'dir. İndirilen fotoğraf ve video aylık indirme kotasına girer; aynı dosya 24 saat içinde yeniden indirilirse düşmez. İptal edilen içeriğin dosyası verilmez (409 icerik_iptal).

HTTP durum kodları ve hata biçimi

API sonucu standart HTTP durum kodlarıyla bildirir; anlamları RFC 9110 HTTP Semantics belgesinde tanımlıdır, MDN HTTP durum kodları sayfası da iyi bir başvuru kaynağıdır. Bütün hatalar aynı gövdeyle gelir:

{ "hata": { "kod": "kapsam_yok", "mesaj": "Bu anahtarın bu uç için kapsamı yok.", "belge": "…", "kapsam": "icerik.indir" } }

mesaj Türkçedir ve değişebilir; yazılımınız kod'a bakmalıdır. Her yanıtta X-YHA-Istek başlığı vardır; destek isterken bu değeri verin. Sık görülen kodlar:

Tam liste: Hatalar.

Sınırlar, 429 ve geri çekilme

Dakikalık istek sınırı anahtar başına varsayılan 120'dir (anahtara özel olabilir). Aşımda sunucu RFC 6585 ile tanımlanan 429 Too Many Requests kodunu yavasla hata koduyla döndürür ve Retry-After başlığında beklemeniz gereken süreyi verir. Kurumun günlük API çağrısı paketinizde yazılıdır; dolduğunda 429 gunluk_sinir_doldu gelir ve sınır Türkiye saatiyle gece yarısı sıfırlanır. Deneme ortamında sınır dakikada 30, günde 2.000 istektir.

Her yanıtta kalan hakkınızı görebilirsiniz:

Her anahtarlı istek bir çağrıdır (304 dahil); reddedilen istek sayılmaz. İyi bir istemci 429'da Retry-After'a uyar, 5xx'te bekleme süresini her denemede artırır, belirli bir deneme sayısından sonra durup uyarı üretir. Sık sorgulama yerine değişiklikleri bildirim olarak almak için anlık akışı ya da YHA webhook bildirimlerini kullanabilirsiniz. Ayrıntılar: Sınırlar.

Adım adım senkronizasyon stratejisi

API ile haber çekmeye yeni başlayan ekiplerin en sık yaptığı hata, her çalıştırmada son haberleri baştan çekip hepsini yeniden kaydetmektir. YHA'da doğru yol akışı imleçle okumaktır:

1. İmleci saklayın. Son işlediğiniz yanıtın sonraki_imlec değerini veritabanında veya küçük bir dosyada tutun.
2. İmleçten devam edin. Bir sonraki çalıştırmada bu değeri ?imlec= olarak gönderin; tarih hesabı ve örtüşme payı gerekmez.
3. Olayları ayıklayın. olay_id'yi saklayın; daha önce gördüğünüz olayı atlayın.
4. Kimliğe göre ekle, düzelt ya da kaldır. Aynı id varsa ve gelen surum_no daha büyükse kaydı güncelleyin; iptal olayında haberi yayından kaldırın; yoksa yeni kayıt oluşturun.
5. Embargoya uyun. embargo.suruyor doğruysa haberi embargo.zaman gelene kadar yayımlamayın.
6. İmleci en son ilerletin. Olaylar başarıyla işlendikten sonra imleci yazın. Arada hata olursa bir sonraki çalıştırma aynı noktadan devam eder; tekrar gelen olaylar olay_id ile elenir.

Akış en çok 7 gün geriye gider; sunucunuz daha uzun kapalı kaldıysa eksiği /v1/haberler ile tarih aralığı vererek tamamlayın.

Gelen içeriği güvenli yayımlama

Haber gövdesini sitenizde yayımlamadan önce izin verilen etiketlere (paragraf, başlık, liste, bağlantı, kalın/italik) göre temizlemek iyi bir güvenlik alışkanlığıdır. PHP'de HTML Purifier, Python'da nh3 gibi kütüphaneler bu iş için yaygın olarak kullanılır. Bağlantıların href değerlerinde yalnızca http ve https şemalarına izin verin.

Test ve hata ayıklama

• İlk denemeleri deneme ortamında yapın; yapay örnek içerik 10 dakikada bir yeni olay üretir. Bkz. Deneme ortamı.
• Hata durumlarını denemek için yalnızca deneme ortamında X-YHA-Deneme-Hata başlığını gönderin (paket_disi, kota_doldu, yavasla, sunucu_hatasi).
• curl'de -v ile başlıkları görebilirsiniz; çıktıyı paylaşırken anahtarı gizleyin. Yanıtları jq ile inceleyin.
• Her isteği adres, durum kodu, hata kodu ve X-YHA-Istek değeriyle kaydedin.
• Beklenmedik hatalarda önce YHA servis durumu sayfasında devam eden bir olay olup olmadığını kontrol edin.

Önbellekleme ve verimlilik

• Kategori ve il sözlükleri gibi seyrek değişen verileri önbelleğe alın.
• Ayrıntı uçları (/v1/haberler/{id}, /v1/varliklar/{id}) ETag verir; If-None-Match ile sorduğunuzda değişiklik yoksa 304 alırsınız. 304 de bir çağrı sayılır.
• Medyayı her seferinde yeniden indirmeyin; aynı varlığın yerel kopyasını kullanın.
• İstekleri zaman aşımı değeriyle gönderin; yanıt vermeyen bir bağlantı tüm iş kuyruğunuzu kilitleyebilir.
• Yanıttaki bilinmeyen alanları ve değerleri yok sayın; bunlar geriye uyumlu eklemelerdir. Kaldırılacak bir uç Deprecation ve Sunset başlıklarıyla önceden duyurulur.

Yapay zekâ asistanlarıyla kullanım

Editörlerinizin Claude Code, Cursor gibi bir yapay zekâ istemcisinden "bugünkü ekonomi haberlerini getir" gibi isteklerle YHA verisine ulaşmasını istiyorsanız, Yazar Haber Ajansı MCP sunucusu aynı içeriği istemcilerin anlayacağı araçlar olarak sunar.

API kavramına yeniyseniz önce API nedir? ve JSON nedir? rehberlerine göz atmanızı öneririz.

Sıkça Sorulan Sorular

Yazar Haber Ajansı API ücretsiz mi?

API, abonelik paketine sözleşmeyle eklenen bir çıkıştır; fiyatlar teklifle verilir. Paketler için YHA abonelik ve paketler sayfasına bakabilir, teklif için başvuru formunu kullanabilirsiniz. Deneme ortamı anahtarı ise kullanım şartları onayı gerektirmez ve aboneliğiniz denemedeyken bile çalışır.

API yanıtları hangi formatta?

Yanıtlar UTF-8 kodlu JSON'dur. XML gerekiyorsa dosya çıkışlarındaki NewsML-G2, NITF ya da ajans XML'i biçimlerini veya RSS/Atom beslemesini kullanabilirsiniz.

Haberleri ne sıklıkla çekmeliyim?

Akışta devami_var yanlış döndüğünde en erken 10 saniye sonra yeniden sorun. Saniyeler içinde almak istiyorsanız anlık akışa (/v1/olaylar) bağlanın ya da webhook kullanın.

API anahtarımı JavaScript ile tarayıcıdan kullanabilir miyim?

Hayır. API tarayıcıdan (CORS) gelen isteği kabul etmez ve tarayıcıya gönderilen her şey ziyaretçiler tarafından görülebilir. İstekleri kendi sunucunuz üzerinden yapın.

Hangi programlama dilini kullanmalıyım?

API dilden bağımsızdır; HTTPS isteği gönderip JSON okuyabilen her dil çalışır. Belgelerde ve entegrasyon kitinde curl, Python, JavaScript, PHP ve C# örnekleri vardır.

Birden fazla anahtar kullanabilir miyim?

Evet. Anahtar kurumunuzundur ve Anahtarlar ekranında birden fazla anahtar üretebilirsiniz; her entegrasyon için ayrı anahtar, sızıntıda yalnızca onu iptal etmenizi ve "son kullanım IP'si" ile kimin kullandığını görmenizi sağlar. İçeriği birden fazla sitede yayımlama hakkı ise abonelik sözleşmenize bağlıdır.

Kaldırılan haberleri nasıl anlarım?

Akışta olay: "iptal" gelir; haberin durum alanı iptal_edildi olur, iptal nesnesi zamanı ve gerekçeyi taşır. iptal.kaldirma doğruysa kaldırma hukuki kaynaklıdır. Her iki durumda da haberi kendi yayınınızdan kaldırın.