Kaynak API'si

Kaynak API'si; serbest muhabirlerin ve kurumların (belediye, kamu kurumu, dernek basın birimleri) kendi yazılımlarından ajansa haber, basın açıklaması, fotoğraf, video ve belge göndermesi ve gönderinin durumunu sorgulaması içindir. Abone API'sinden (Başlarken) ayrıdır: ayrı adres, ayrı anahtar türü, ayrı OpenAPI belgesi.

• Canlı: https://kaynak.<alan>/v1
• Deneme: https://deneme.<alan>/kaynak/v1

Her gönderi ajans editörünün onayından geçer; API'den gelen içerik YHA Gönderim'den gelenle aynı kuyruğa düşer. Anahtar yalnızca gönderir ve kendi gönderilerinizin durumunu okur; ajansın içeriğini okuyamaz.

Başlarken

1. YHA Gönderim'de API anahtarım ekranından anahtar üretin. Serbest muhabirde anahtar kişinindir; kurumda kurumundur ve yalnızca kurum yöneticisi üretir.
2. Önce deneme anahtarı (yha_deneme_…) ile deneyin: deneme gönderisi kayda geçmez, kuyruğa düşmez; durumu yapay ilerler.
3. Canlı anahtar (yha_canli_…) için Kaynak API kullanım şartlarını programda onaylarsınız (şartlar yayında değilken yalnızca deneme anahtarı üretilir).

Anahtar bir kez gösterilir; ajans yalnızca özetini saklar. Kaybederseniz iptal edip yenisini üretin. Her istekte:

Authorization: Bearer yha_canli_…

Kapsamlar: icerik.gonder (gönderi açma, ek yükleme, geri çekme) ve gonderi.durum (durum sorgusu, liste). Anahtara IP kısıtı eklenebilir. Anahtar üretilince ve iptal edilince serbest muhabire ya da kurum yöneticilerine bildirim gider.

curl https://deneme.<alan>/kaynak/v1/ben -H "Authorization: Bearer $YHA_ANAHTAR"

/ben anahtarın kaynağını, sınırlarını, bugün kalan isteği ve gonderebilir bilgisini döner (gonderemezlik_nedeni: kaynak_askida, sozlesme_yururlukte_degil, gonderim_aboneligi_yok …).

İlk gönderi

curl -X POST https://deneme.<alan>/kaynak/v1/gonderiler \
  -H "Authorization: Bearer $YHA_ANAHTAR" -H "Content-Type: application/json" \
  -d '{"dis_kimlik":"aciklama-2026-0001","icerik_turu":"basin_aciklamasi","baslik":"Örnek basın açıklaması","metin":"Açıklamanın metni.","il_id":61}'

Yanıt 201 ve KaynakGonderi nesnesidir: id, gonderi_no (KG-000123), durum, ekler, red, haber_durumu… Editörün adı, iç notlar ve haberin kimliği hiçbir zaman dönmez.

Büyük dosya: parçalı yükleme

Ekli gönderide durum yukleniyor'dur ve her ekte yukleme bilgisi vardır (parca_boyutu 8 MB, parca_sayisi, adres_kalibi). Her parçayı sırayla gönderin, sonra tamamlayın:

PARCA_OZETI=$(sha256sum parca-1 | cut -d' ' -f1)
curl -X PUT "$KOK/gonderiler/$ID/ekler/1/parcalar/1" -H "Authorization: Bearer $YHA_ANAHTAR" \
  -H "Content-Type: application/octet-stream" -H "X-YHA-Parca-Ozeti: $PARCA_OZETI" --data-binary @parca-1
curl -X POST "$KOK/gonderiler/$ID/ekler/1/tamamla" -H "Authorization: Bearer $YHA_ANAHTAR" \
  -H "Content-Type: application/json" -d "{\"ozet\":\"$DOSYA_OZETI\"}"

• Parça en çok 8 MB; Content-Length tam olmalı; aynı parça aynı özetle yinelenebilir (kaldığınız yerden sürdürün).
• Tamamlama 202 döner; ek denetimde'dir: tür doğrulama, zararlı içerik taraması, görüntüde konum ve cihaz bilgisinin silinmesi, PDF'te etkin içerik reddi. Sonuç durum sorgusunda (hazir ya da karantina).
• Bütün ekler sonuçlanınca gönderi alindi olur. Dosyası denetimden geçemeyen ek habere bağlanmaz.

Durum yoklama

curl "$KOK/gonderiler/KG-000123" -H "Authorization: Bearer $YHA_ANAHTAR"
curl "$KOK/gonderiler/dis:aciklama-2026-0001" -H "Authorization: Bearer $YHA_ANAHTAR"
curl "$KOK/gonderiler?degisti_sonra=2026-10-10T08:00:00Z&boyut=50" -H "Authorization: Bearer $YHA_ANAHTAR"

Durumlar: yukleniyor → alindi → incelemede → onaylandi | reddedildi; ayrıca geri_cekildi. Reddedilen gönderide red.baslik ve red.gerekce vardır. Liste imleçlidir (sonraki_imlec, devami_var); kurum anahtarı kurumun bütün kanallardan gelen gönderilerini görür. Yoklama aralığı en az bir dakika olsun; ajans gönderinin durumunu size itmez (webhook yok).

POST /gonderiler/:id/geri-cek yalnızca incelemeye alınmamış gönderide çalışır (değilse 409 geri_cekilemez).

Yineleme önleme

Oturum olmadığından Idempotency-Key kullanılmaz; yineleme önleme dis_kimlik iledir:

• Aynı dis_kimlik ve aynı gövdeyle yinelenen istek var olan gönderiyi 200 ve X-YHA-Tekrar: evet başlığıyla döner (yeni kayıt açmaz). Ağ hatasında isteği güvenle yineleyin.
• Aynı dis_kimlik başka gövdeyle 409 dis_kimlik_cakisiyor döner (gonderi_id var olanı söyler).
• Gövde karşılaştırması alan sırasından bağımsızdır (kanonik JSON'un SHA-256'sı).

Sınırlar

Her yanıtta X-YHA-Gunluk-Sinir ve X-YHA-Gunluk-Kalan başlıkları vardır. Geçersiz anahtarla çok sayıda deneme adresinizi geçici olarak yasaklar.

Deneme ortamı

https://deneme.<alan>/kaynak/v1 ve yha_deneme_… anahtarı: uçlar ve doğrulama canlıdakinin aynısıdır, ancak gönderi ajansa ulaşmaz (24 saat tutulur). Ekler alınır, taranır ve atılır (deneme eki en çok 5 MB). Durum yapay ilerler: hemen alindi, 60 saniye sonra incelemede, 120 saniye sonra başlıkta "red" geçiyorsa reddedildi, geçmiyorsa onaylandi. Hata yollarınızı sınamak için X-YHA-Deneme-Hata başlığı: yavasla, gunluk_sinir_doldu, gonderim_siniri_doldu, kaynak_askida, sunucu_hatasi. Canlı anahtar deneme adresinde, deneme anahtarı canlı adreste 401 anahtar_ortami_uyusmuyor döner.

Sözlük

GET /sozluk/kategoriler ve GET /sozluk/iller (ilçeleriyle). Kimlikler değişmez; günde bir kez önbelleğe almanız yeterlidir.

Hatalar

Bütün hatalar { "hata": { "kod", "mesaj", "belge", … } } biçimindedir; yazılımınız kod'a bakmalıdır. Kodların tamamı: Kaynak API'si hataları. Sık görülenler:

Destek isterken yanıttaki X-YHA-Istek değerini verin.

Örnekler ve araçlar

• OpenAPI belgesi (JSON), YAML; anahtarsız: GET /v1/openapi.json
• Postman derlemesi
• Örnek kod: ornekler/curl/kaynak-gonder.sh, ornekler/python/kaynak_gonder.py, ornekler/javascript/kaynak-gonder.mjs, ornekler/csharp/KaynakGonder.cs

Başka gönderme yolları

YHA Gönderim (izlenen klasör dahil), kuruma tanımlanan e-posta adresi ve FTP (yalnızca SFTP ve TLS zorunlu FTPS) da aynı kuyruğa düşer. Kanal bilgileri YHA Gönderim'in Kurum ekranındadır.