Yazar Haber Ajansı Geliştirici Belgeleri

Yazar Haber Ajansı Geliştirici Belgeleri: Haber Ajansı Entegrasyonu Rehberi

Yazar Haber Ajansı geliştirici dökümanları, YHA haberlerini, fotoğraflarını ve videolarını kendi sitenize, uygulamanıza veya haber yazılımınıza otomatik olarak aktarmanız için gereken her şeyi tek yerde toplar. Kısaca: kendi yazılımınız akışı çekecekse Abone API'sini, saniyeler içinde haber almak için anlık akışı (SSE) ya da webhook'u, klasör izleyen haber yazılımları için FTP/SFTP'yi, en basit kurulum için RSS ve Atom beslemesini, yapay zekâ istemcileri için MCP sunucusunu, WordPress sitesi için de ajansın WordPress eklentisini kullanırsınız.

Bu sayfa, YHA belgelerinin ana giriş noktasıdır. Hangi yolun size uygun olduğunu seçmenize, ilk isteği göndermenize ve ajans içeriğini sitenizde hem teknik hem de yayıncılık açısından doğru kullanmanıza yardım eder. Her yolun ayrıntılı belgesine aşağıdaki bağlantılardan ulaşabilirsiniz.

Haber ajansı entegrasyonu nedir?

Haber ajansı entegrasyonu, bir ajansın ürettiği haberlerin (metin, fotoğraf, video) abone yayın kuruluşunun sistemine elle kopyalanmadan, makine tarafından okunabilir biçimde ve düzenli olarak aktarılmasıdır. Geleneksel olarak bu iş teleks, ardından e-posta ve FTP ile yapılıyordu. Bugün ise çoğu yayın kuruluşu HTTP tabanlı API'ler, besleme dosyaları ve olay tabanlı bildirimler kullanıyor.

Doğru kurulmuş bir entegrasyon üç sorunu çözer:

• Hız: Haber ajansta servis edildiği anda sizin editör panelinize de düşer.
• Tutarlılık: Başlık, spot, kategori, il, medya ve zaman gibi alanlar her seferinde aynı yapıda gelir; kopyala-yapıştır hataları ortadan kalkar.
• Ölçeklenebilirlik: Günde onlarca ya da yüzlerce haberi küçük bir ekip yönetebilir.

Entegrasyon yöntemleri: ne zaman hangisi?

YHA aynı servisi farklı yollardan verir ve birden fazlasını aynı anda kullanabilirsiniz. Hangi yolların açık olduğu paketinize bağlıdır: otomatik çıkışlar pakete sözleşmeyle eklenir, paketinizde açık olmayan bir yol 403 kanal_paketinde_yok döner. İçerik her yolda paketinizin hakkıyla sınırlıdır.

Kısa bir karar rehberi:

1. Siteniz WordPress ise eklentiyle başlayın. Haberleri, fotoğrafları, düzeltmeleri ve iptalleri sitenize yazı olarak işler; varsayılan olarak taslak oluşturur.
2. Kendi yazılımınız varsa API'deki akışı (/v1/akis) temel alın; anlık tepki için anlık akış ya da webhook ekleyin.
3. Haber yazılımınız klasördeki dosyaları okuyorsa FTP/SFTP gönderimini seçin; NewsML-G2 (varsayılan), NITF, IPTC 7901, ajans XML'i ve JSON biçimleri vardır.
4. Yalnızca bir besleme okuyabiliyorsanız RSS ya da Atom yeterlidir.
5. Editörleriniz bir yapay zekâ istemcisiyle haber aramak ve okumak istiyorsa MCP sunucusunu bağlayın.

Haber yazılımınız için önceden doldurulmuş ayarları hazır bağlantılar sayfasında bulabilirsiniz.

Başlangıç adımları

YHA entegrasyonu dört adımda canlıya alınır. Adımların teknik ayrıntısı Başlarken sayfasındadır.

1. Abonelik

Tüm teknik erişimler imzalı bir abonelik sözleşmesine bağlıdır. Başlangıç paketleri metin, metin + fotoğraf ve tam (metin, fotoğraf, video) olarak kurulur; API, anlık akış, RSS, webhook, FTP/SFTP, e-posta, MCP ve WordPress eklentisi gibi otomatik çıkışlar pakete sözleşmeyle eklenir. Paketleri incelemek için Yazar Haber Ajansı abonelik ve paketler sayfasını, başvuru için abonelik başvurusu formunu kullanın. 14 günlük deneme hesabı yalnızca görüntüleme içindir; otomatik çıkış içermez.

2. Anahtar

Anahtarları YHA Abone · Çıkışlar · Anahtarlar ekranında kendiniz üretirsiniz. Önce deneme ortamı için yha_deneme_… anahtarı üretmenizi öneririz. Canlı anahtar (yha_canli_…) için kurumunuz adına API kullanım şartları bir kez onaylanır. Anahtar yalnızca bir kez gösterilir; sunucunuzdaki ortam değişkeninde ya da parola yöneticisinde saklayın, kaynak koduna, Git deposuna veya tarayıcıda çalışan JavaScript'e koymayın. Tarayıcıdan (CORS) gelen istek zaten kabul edilmez. Ayrıntılar: Kimlik ve anahtarlar.

3. Deneme ortamında sınama

Canlıya geçmeden önce entegrasyonu https://deneme.yha.com.tr/v1 adresindeki deneme ortamında çalıştırın. Burada yapay örnek içerik vardır (başlıklar "[ÖRNEK]" ile başlar); örnek akış 10 dakikada bir yeni olay üretir, günde bir flaş, saatte bir düzeltme ve günde bir iptal içerir. Uçlar, hata kodları ve başlıklar canlıyla aynıdır. Ayrıntılar: Deneme ortamı.

• Alanların doğru eşleştiğini kontrol edin (başlık, spot, gövde, kategori, il, medya).
• Türkçe karakterlerin bozulmadan geldiğinden emin olun; tüm katmanlarda UTF-8 kullanın.
• Aynı olay iki kez geldiğinde sitenizde iki kopya oluşmadığını doğrulayın.
• Düzeltme ve iptal senaryolarını deneyin.

4. Canlıya geçiş ve izleme

Canlıda istekler ve yanıtlar deneme ortamıyla aynıdır; yalnızca kök adres https://api.yha.com.tr/v1 olur. Hata kayıtlarını izleyin ve olası kesintileri takip etmek için YHA servis durumu sayfasını yer imlerinize ekleyin. Planlı bakımlar ve olaylar aynı sayfada duyurulur.

Haber veri modeli

Hangi yolu kullanırsanız kullanın, bir YHA haberi aynı alanlardan oluşur. API, anlık akış, webhook ve JSON dosyası bu alanları aynı adlarla taşır; NewsML-G2, NITF ve RSS'te aynı bilgi o biçimin öğelerine yazılır.

Tam şema API başvurusunda ve OpenAPI belgesindedir (https://api.yha.com.tr/v1/openapi.json). Zaman alanları UTC olarak gelir (ör. 2026-10-07T11:19:00Z); ekranda Türkiye saatine çevirirken saat dilimi bilgisini kaybetmeyin.

En iyi uygulamalar

Tekrar eden olayları kimlikle ayıklayın

Aynı olay iki kez gelebilir. Olayları olay_id ile, haberleri id ile eşleştirin; başlığa göre eşleştirmeyin, çünkü başlık düzeltilebilir. Haber kimliğini veritabanınızda benzersiz bir sütunda saklarsanız aynı haberin iki kez yayımlanması teknik olarak imkânsız hale gelir.

Düzeltme ve iptalleri işleyin

Düzeltmede haberin yeni sürümü gelir; surum_no sizdekinden büyükse uygulayın, küçükse yok sayın (sıra garantisi yoktur, flaş öne geçebilir). İptal edilen haberde govde boş gelir: haberi yayınınızdan kaldırın. Editörünüzün yaptığı değişikliklerin ezilmemesi için kendi tarafınızda bir "editör düzenledi" bayrağı tutmak iyi bir yöntemdir.

Embargo ve tanıtım

Önceden verilen embargolu içerik embargo bilgisiyle gelir; yazılımınız embargo.zaman'ı beklemeli, haberi saatinden önce yayımlamamalıdır. Tanıtım içeriği tanitim: true taşır; tercihiniz kapalıysa hiç gelmez.

Medya ve kullanım hakkı

Medya dosyaları kalıcı bir ajans adresinden değil, süreli ve imzalı adreslerden verilir. Bu yüzden fotoğrafı kendi sunucunuza ya da CDN'inize indirip oradan sunmanız gerekir. API'den indirilen fotoğraf ve video aylık indirme kotasına girer (aynı dosya 24 saat içinde yeniden indirilirse düşmez); FTP, SFTP, webhook ve e-posta ile giden dosyalar kotaya girmez. Ajans içeriği yalnızca abonelik sözleşmenizdeki kullanım hakkı içinde kullanılır ve yapay zekâ modellerinin eğitiminde kullanılamaz.

Kaynak gösterme

Haberde kaynak olarak "Yazar Haber Ajansı" ya da "YHA" görünür biçimde yazılmalıdır. Her haberle gelen kullanim.kaynak_gosterme_notu bu iş içindir. Bu hem sözleşmenin hem de okuyucu güveninin gereğidir.

Ajans içeriği ve SEO: değer katın

Aynı ajans haberi pek çok sitede neredeyse aynı metinle yayımlandığında Google bu kopyalardan genellikle birini öne çıkarır, diğerlerini benzer sonuçlar arasında gösterir. Google'ın kanonik URL belgesi yinelenen içeriğin nasıl ele alındığını açıklar. Bu bir ceza değildir, ancak aynen yayımlanan ajans metni sitenize ayrıca arama trafiği getirmeyebilir.

Ajans haberini sitenizin değerine dönüştürmek için:

• Kendi başlığınızı ve spotunuzu yazın.
• Yerel bağlam, arka plan bilgisi, uzman görüşü veya kendi fotoğrafınızı ekleyin.
• Konuyla ilgili önceki haberlerinize bağlantı verin.
• Hızın önemli olduğu son dakika haberlerini ajans metniyle hemen yayımlayıp sonradan zenginleştirin.

Google, içeriğin nasıl üretildiğinden çok kullanıcıya ne kadar fayda sağladığına bakar; ajans akışını otomatik olarak çok sayıda sayfaya çoğaltıp hiçbir değer katmamak ise spam politikalarındaki "ölçekli içerik kötüye kullanımı" kapsamına girebilir. Bu konuda Google'ın spam politikaları sayfasını okumanızı öneririz.

Güvenlik

• API anahtarlarını yalnızca sunucu tarafında kullanın; anahtarı IP listesiyle (en çok 20 blok) daraltabilirsiniz.
• Anahtar sızarsa hemen iptal edin ve yenisini üretin; iptal hemen geçerlidir.
• Webhook isteklerinin gerçekten YHA'dan geldiğini imza doğrulamasıyla (Standard Webhooks, HMAC-SHA256) kontrol edin.
• Dosya çıkışlarında FTPS ya da SFTP kullanın; şifresiz FTP yalnızca ajansın izniyle açılır.
• Gelen haber gövdesindeki HTML'i yayımlamadan önce izin verilen etiketlere göre temizleyin.

Örnek entegrasyon mimarisi

Orta ölçekli bir haber sitesi için sağlam ve bakımı kolay bir düzen şöyle kurulabilir:

1. Bildirim katmanı: YHA webhook'u yeni haber, düzeltme ya da iptalde sunucunuzdaki adrese imzalı bir POST gönderir. Varsayılan yük tam içeriktir; profilde "ince" seçerseniz yalnızca kimlik ve adres gelir.
2. Hızlı yanıt: Alıcı imzayı doğrular, olayı bir iş kuyruğuna yazar ve 10 saniyelik süre dolmadan 2xx döner.
3. Çekme katmanı: Kuyruktaki işçi gerekirse içeriği API'deki akıştan çeker ("dürt ve çek"), medyayı indirir.
4. Eşleştirme: Haber kimliği ve surum_no ile yeni kayıt mı, düzeltme mi, iptal mi olduğu belirlenir; kategori eşlemesi yapılır.
5. Editör onayı: Haber sitenizde taslak olarak oluşur; editör başlığı ve spotu düzenleyip yayımlar. Flaş haberler için doğrudan yayına alma kuralı tanımlanabilir.
6. Yedek kanal: Bir bildirim kaçarsa diye akışı saklanan imleçten düzenli aralıklarla okuyan zamanlanmış bir görev çalışır.

Bu düzen, tek bir kanaldaki sorunun haber akışını durdurmasını engeller. Haber yazılımı firmasıysanız ve ürününüze ajans bağlantısı eklemek istiyorsanız entegrasyon kitine bakın.

Sık yapılan entegrasyon hataları

• Her istekte arşivi baştan çekmek: Akışta son imleci saklayın ve oradan devam edin; devami_var yanlışsa en erken 10 saniye bekleyin.
• Karakter kodlamasını gözden kaçırmak: Veritabanı tablosunun UTF-8 (MySQL'de utf8mb4) olmaması Türkçe karakterleri bozar.
• Hataları sessizce yutmak: Hata gövdesindeki kod alanını ve X-YHA-Istek başlığını kaydedin; destek isterken bu değeri verin. Bkz. Hatalar.
• Sınırları hesaba katmamak: Dakikalık istek sınırı anahtar başına varsayılan 120'dir; aşımda 429 ve Retry-After gelir. Bkz. Sınırlar.

Haber sitesi kuracaklar için

Henüz bir haber siteniz yoksa ya da altyapı seçiyorsanız, WordPress ile haber sitesi kurma rehberimiz tema, performans ve haber sitesine özgü SEO ayarlarını anlatır. Haber ajansının ne olduğu ve yayıncılıktaki yeri haber ajansı nedir yazısında.

Temel kavramlar: entegrasyondan önce okuyun

Belgelerde geçen teknik terimler, haber verisi örnekleriyle şu rehberlerde anlatılıyor:

• API nedir?: Uygulamaların birbiriyle nasıl konuştuğu ve haber API'lerinin mantığı.
• JSON nedir?: API yanıtlarında kullanılan veri biçimi ve bir haber nesnesinin JSON yapısı.
• XML nedir?: Beslemelerde ve ajans dosyalarında kullanılan işaretleme dili.
• RSS nedir?: Haber beslemelerinin nasıl çalıştığı ve nasıl okunduğu.
• FTP ve SFTP nedir?: Dosya aktarım protokolleri ve aralarındaki güvenlik farkı.
• Webhook nedir?: Sorgulamak yerine bildirim almak: push modelinin temelleri.
• MCP nedir?: Yapay zekâ asistanlarını veri kaynaklarına bağlayan Model Context Protocol.

Sıkça Sorulan Sorular

YHA entegrasyonu için yazılımcı gerekir mi?

WordPress kullanıyorsanız gerekmez; eklenti kurulum koduyla bağlanır. RSS beslemesi ve hazır bağlantısı olan haber yazılımları da kod yazmadan kullanılabilir. Kendi yazılımınıza API, anlık akış veya webhook entegrasyonu için geliştirici desteği gerekir.

Birden fazla entegrasyon yöntemini aynı anda kullanabilir miyim?

Evet; paketinizde açık olan yolların hepsini birlikte kullanabilirsiniz. Yaygın düzen, webhook ya da anlık akışla haberi hemen almak ve akışı imleçle yedek olarak okumaktır. Birden fazla yol kullanıyorsanız tekrarları önlemek için hepsinde aynı haber kimliğini ana anahtar yapın.

Haberler hangi formatlarda sunuluyor?

API, anlık akış ve webhook JSON verir. Dosya çıkışlarında NewsML-G2 (varsayılan), NITF, IPTC 7901, ajans XML'i ve JSON vardır. Beslemeler RSS 2.0 ya da Atom'dur. Ayrıntılar ilgili belge sayfalarındadır.

Teknik destek nereden alınır?

Teknik destek ve entegrasyon soruları için destek@yha.com.tr adresine yazabilirsiniz; destek hafta içi 09.00–18.00 (Türkiye saati) arasında e-posta ve telefonla verilir. Diğer kanallar iletişim sayfasındadır. Kesinti olduğunu düşünüyorsanız önce servis durumu sayfasını kontrol edin; destek isterken hata yanıtındaki X-YHA-Istek değerini iletin.

Entegrasyon ücretli mi?

Otomatik çıkışlar abonelik paketinize sözleşmeyle eklenir; fiyatlar sitede yayımlanmaz, teklifle verilir. Teklif için abonelik başvurusu formunu kullanabilir ya da satis@yha.com.tr adresine yazabilirsiniz.