API belgeleri

Tüm istekler https://ulakbot.tr adresine yapılır ve yanıtlar UTF-8 kodlu JSON döner. API yanıtlarındaki tarihler ISO 8601 biçiminde, Türkiye saatiyle (+03:00) verilir. API anahtarınızı ve RSS adreslerinizi panelinizde API ve RSS sayfasında bulabilirsiniz.

Kimlik doğrulama

Her istekte API anahtarınızı X-Api-Key başlığında gönderin. Başlık eklenemeyen ortamlarda ?api_key= sorgu parametresi de kabul edilir; ancak adres günlüklere düşebileceği için başlık kullanmanızı öneririz. Anahtarınızı panelden yenilediğinizde eski anahtar hemen geçersiz olur.

# Örnek istek
curl -H "X-Api-Key: hb_xxxxxxxxxxxxxxxxxxxx" \
     "https://ulakbot.tr/api/v1/haberler?durum=ready&adet=20"

Haberler

Hesabınızda hazırlanan haberleri en yeniden eskiye listeler.

Parametre	Açıklama
durum	ready (yayına hazır) ya da published (en az bir kanalda yayınlanmış). Verilmezse ikisi birden.
kategori	Kategori adı, ör. Yerel
since	Bu tarihten sonra oluşturulanlar (ISO 8601), ör. 2026-11-10T08:00:00+03:00
sayfa	Sayfa numarası, varsayılan 1
adet	Sayfa başına kayıt, en fazla 50, varsayılan 20

{
  "ok": true,
  "data": [
    {
      "id": 1842,
      "title": "Üreticilere zirai don uyarısı",
      "spot": "İl Tarım ve Orman Müdürlüğü, üreticileri önlem almaya çağırdı.",
      "body_html": "<p>...</p>",
      "tags": ["zirai don", "tarım"],
      "category": "Yerel",
      "image_url": "https://.../gorsel.jpg",
      "source_url": "https://kaynak-kurum.gov.tr/haber/...",
      "seo_title": "Üreticilere zirai don uyarısı",
      "meta_description": "İl genelinde gece sıcaklıklarının eksi 4 dereceye düşmesi bekleniyor.",
      "status": "ready",
      "created_at": "2026-11-10T09:42:11+03:00",
      "published_at": null
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 134 }
}

Tek haber

Tek bir haberin tüm alanlarını döndürür; data bir nesnedir. Haber başka bir hesaba aitse ya da silinmişse 404 döner.

Haber akışı

Takip ettiğiniz kaynaklardan gelen, henüz habere dönüştürülmemiş ya da dönüştürülmüş içerikler.

Parametre	Açıklama
durum	new (bekleyen), converted (habere dönüştürülmüş) ya da ignored (yok sayılmış)
kaynak	Kaynak kimliği; yalnızca o kaynağın içerikleri
sayfa	Sayfa numarası, varsayılan 1 (sayfa başına 20 kayıt)

{
  "ok": true,
  "data": [
    {
      "id": 99120,
      "status": "new",
      "title": "Vali, ilçe ziyaretinde yatırımları inceledi",
      "summary": "…",
      "url": "https://www.ornek.gov.tr/vali-ilce-ziyaretinde-yatirimlari-inceledi",
      "image_url": "https://www.ornek.gov.tr/.../foto.jpg",
      "published_at": "2026-11-10T08:15:00+03:00",
      "source": { "id": 87, "name": "Örnek Valiliği", "platform": "web" }
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 58 }
}

Kaynaklar

Takip listenizdeki kaynaklar; çalışma biçimi (mode: pool, rewrite, publish) ve tarama durumuyla (health: new, ok, warning, error).

{
  "ok": true,
  "data": [
    {
      "id": 87,
      "name": "Örnek Valiliği",
      "platform": "web",
      "url": "https://www.ornek.gov.tr",
      "city": "Örnek",
      "district": null,
      "mode": "pool",
      "is_active": true,
      "health": "ok",
      "last_fetched_at": "2026-11-10T09:40:02+03:00"
    }
  ]
}

RSS çıkışı

RSS okuyabilen her haber yazılımı için size özel iki akış adresi vardır. Adresteki belirteç gizlidir; panelden yenilendiğinde eski adresler çalışmaz.

Hazırlanan haberler: başlık, spot, tam metin (content:encoded), kategori ve görsel (enclosure).

Takip ettiğiniz kaynaklardan gelen ham içerik akışı.

Webhook

Webhook entegrasyonu Kurumsal pakette yer alır. Panelde bir webhook entegrasyonu tanımladığınızda, haber bu entegrasyona gönderildiğinde adresinize POST isteğiyle aşağıdaki JSON iletilir. Bağlantı testinde event değeri test olur. Gizli anahtar belirlediyseniz istek gövdesi HMAC-SHA256 ile imzalanır ve imza X-Ulakbot-Signature: sha256=<onaltılık imza> başlığında gönderilir.

{
  "event": "article.published",
  "sent_at": "2026-11-10T09:45:30+03:00",
  "article": {
    "id": 1842,
    "title": "Üreticilere zirai don uyarısı",
    "spot": "İl Tarım ve Orman Müdürlüğü, üreticileri önlem almaya çağırdı.",
    "body_html": "<p>...</p>",
    "tags": ["zirai don", "tarım"],
    "category": "Yerel",
    "image_url": "https://.../gorsel.jpg",
    "source_url": "https://kaynak-kurum.gov.tr/haber/...",
    "seo_title": "Üreticilere zirai don uyarısı",
    "meta_description": "İl genelinde gece sıcaklıklarının eksi 4 dereceye düşmesi bekleniyor.",
    "created_at": "2026-11-10 09:42:11"
  }
}

Adresiniz 15 saniye içinde 2xx yanıtı vermelidir. Yanıt gövdesinde id ve url alanlarını döndürürseniz, bu bilgiler yayın geçmişinde haberin bağlantısı olarak gösterilir.

<?php
// Webhook adresinizde imza doğrulama
$secret = 'PANELDE_BELIRLEDIGINIZ_GIZLI_ANAHTAR';
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_ULAKBOT_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit('Geçersiz imza');
}
$payload = json_decode($body, true);
if ($payload['event'] === 'article.published') {
    // $payload['article'] ile haberi kendi sisteminize kaydedin
}
http_response_code(200);
echo json_encode(['id' => 'sizdeki-kayit-no', 'url' => 'https://siteniz.com/haber/...']);

Hatalar ve sınırlar

Hatalı isteklerde yanıt {"ok": false, "error": "açıklama"} biçimindedir.

Kod	Anlamı
401	API anahtarı eksik ya da geçersiz
402	Aboneliğiniz etkin değil (deneme süresi doldu ya da hesap askıda)
404	Kayıt bulunamadı
429	İstek sınırı aşıldı; bir dakika bekleyip tekrar deneyin

Her API anahtarı için sınır dakikada 120 istektir. Yeni haberleri almak için birkaç dakikada bir since parametresiyle sorgulamanız ya da anında bildirim için webhook kullanmanız önerilir.