Site API teknik referansı (seoasist-site-api/1)

Bu sayfa, sitenin uygulaması gereken SEOAsist Site API sözleşmesini (spec seoasist-site-api/1) anlatır. Paneldeki Geliştirici kılavuzu → Spesifikasyon sekmesi ve Kurulum promptu aynı sözleşmeyi içerir. Bağlantı adımları için SEOAsist Site API ile özel yazılım siteni bağlama makalesine bak.

#Genel kurallar

• Tüm uç noktalar tek bir taban yol altındadır, ör. https://example.com/api/seoasist.
• Her yanıt JSON olmalıdır. JSON olmayan yanıt hata sayılır.
• Yönlendirme (30x) yapma. SEOAsist yönlendirmeleri izlemez; panelde son API adresini kaydet.
• Hata durumunda 4xx/5xx ile {"error":"<kısa mesaj>"} dön. Bu mesaj panelde gösterilir.
• Girdiyi doğrula, gövde boyutunu sınırla (~2 MB) ve çağrıları logla.
• SEOAsist her isteği 25 saniye sonra zaman aşımına uğratır. İstekler SEOAsist-SiteAPI/1.0 (+https://seoasist.com) user-agent'ıyla gelir.
• Adres internetten erişilebilir olmalıdır; localhost ve özel ağ adreslerine istek atılmaz.

#Kimlik doğrulama

Her istekte üç başlık gelir:

• Token'ı SEOASIST_SITE_TOKEN ortam değişkeninde sakla, koda yazma. Panelde Bağla ile üretilir ve sa_ ile başlar.
• Token'ı ve imzayı sabit zamanlı (constant-time) karşılaştır.
• GET isteklerinde ham gövde boş dizedir; imzalanan mesaj <timestamp>. olur.
• İmza yanlışsa veya zaman damgası 300 saniyeden eskiyse 401 {"error":"unauthorized"} dön.

const expected = "sha256=" + createHmac("sha256", token).update(`${ts}.${body}`).digest("hex");

#GET /manifest

Bağlantı testi bu uç noktayı çağırır. Yalnızca uyguladığın yetenekleri listele.

{"spec":"seoasist-site-api/1","platform":"nextjs","name":"Sitem","capabilities":["rules","content","files"]}

spec değeri seoasist-site-api/ ile başlamalıdır. Tanınan yetenekler rules, content ve files; diğerleri yok sayılır. Panelde sırasıyla SEO kuralları, İçerik yayını ve llms.txt / robots olarak görünürler.

#PUT /rules (yetenek: rules)

Gövde: {"rules": Rule[]}. Bu, güncel kural setinin tamamıdır; daha önce saklananların hepsini değiştir. Boş dizi tüm kuralları temizler. Kuralları kalıcı sakla (DB tablosu veya JSON dosyası) ve sayfa render edilirken sunucu tarafında uygula. Tarayıcılar sonucu istemci JavaScript'inde değil, HTML'de görmelidir.

type Rule = { id: string; kind: string; matchType: "exact" | "prefix" | "regex" | "all"; matchPath: string; payload: object };

Eşleme, sondaki eğik çizgi atılmış istek yoluyla yapılır (ana sayfa için /):

• exact: yol birebir eşit
• prefix: yol matchPath ile başlıyor
• regex: JavaScript RegExp testi
• all: her sayfa

Aynı türden birden çok kural eşleşirse en özel olan kazanır: exact > prefix > regex > all.

Bilinmeyen türleri sakla ve yok say. Yanıt: {"ok":true,"count":<saklanan sayı>}.

SEOAsist sitenin etkin kurallarının tamamını gönderir: Pixel sekmesinde eklenenler, uygulanan meta önerileri, çalışma alanı görevlerinin oluşturdukları ve Teknik Denetim'deki Otomatik düzelt ile üretilenler.

#POST /content (yetenek: content)

Gövde:

{"externalId":null,"type":"post","title":"…","slug":"…","html":"<h2>…</h2>","excerpt":"…","metaTitle":"…","metaDescription":"…","status":"draft","featuredImageUrl":"https://…","tags":["…"],"updateUrl":null}

• externalId doluysa o öğeyi güncelle.
• updateUrl doluysa (type: "page") o adresteki mevcut sayfanın ana içeriğini, başlığını ve meta bilgisini güncelle.
• Aksi halde sitenin mevcut içerik sistemiyle (DB/CMS/MDX) ve normal URL kalıbıyla yeni bir yazı oluştur.
• status: "draft" herkese açık görünmemelidir.
• html güvenilir, biçimlendirilmiş makale HTML'idir (başlıklar, listeler, tablolar, SSS). Sitenin tasarımını koru.
• tags en fazla 5 etiket içerir.

Yanıt: {"id":"<kalıcı id>","url":"<mutlak genel URL>","status":"draft"|"publish"}. SEOAsist id değerini saklar ve aynı öğeyi tekrar gönderirken externalId olarak kullanır.

#PUT /files (yetenek: files)

Gövde: {"path":"llms.txt"|"robots-ai.txt","content":string}

• llms.txt: /llms.txt adresinden text/plain olarak sun (öncekinin yerine).
• robots-ai.txt: AI tarayıcı kuralları bloğudur. /robots.txt dosyasını sitenin kendi kuralları + sonuna eklenmiş bu blokla sun (önceki bloğun yerine).

Yanıt: {"ok":true,"url":"<genel url>"}.

#Hazır örnekler

Geliştirici kılavuzu penceresinde kopyalanabilir kodlar var:

Örneklerdeki /content uç noktası bir şablondur (TODO); yazıyı kendi blog/CMS yapına kaydedip gerçek URL'yi döndürmen gerekir.

Test komutu:

TOKEN="<SEOASIST_SITE_TOKEN>"
TS=$(date +%s)
SIG=$(printf "%s." "$TS" | openssl dgst -sha256 -hmac "$TOKEN" | sed 's/^.* //')
curl -s "https://example.com/api/seoasist/manifest" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SEOAsist-Timestamp: $TS" \
  -H "X-SEOAsist-Signature: sha256=$SIG"

#Panelde görünen hata mesajları

Site gövdede {"error":"…"} döndürürse panelde doğrudan o mesaj görünür. Çözüm adımları: Site API bağlantı sorunları.