n8n ve jekcms Yayın API'siyle İçerik Otomasyonu

Yayın API uç noktası POST /api/v1/posts/publish-task. İstek gövdesinde JSON formatında title, content, author_id, category, featured_image (bir URL) ve isteğe bağlı ISO 8601 zaman damgalı scheduled_at parametreleri kabul ediliyor. API anahtarı X-API-Key başlığıyla iletiliyor. Başarılı oluşturma durumunda yeni gönderinin ID'si ve genel URL'si dönüyor.

n8n'de Minimal Çalışan Akış

n8n'de çalışan minimal bir akış dört düğümden oluşuyor: kaynak içeriği çeken bir HTTP Request düğümü (OpenAI, RSS beslemesi veya kendi kaynağınız olabilir), yükü biçimlendiren bir Code düğümü, jekcms API'sini çağıran bir HTTP Request düğümü ve hataları Slack bildirimine ya da yeniden deneme kuyruğuna yönlendiren bir IF düğümü.

Yüksek Hacimli İşlemlerde Medya Yönetimi

Medya yönetimi dikkat gerektiriyor. featured_image olarak bir URL ilettiğinizde jekcms bunu API isteği sırasında eş zamanlı olarak çekiyor, AVIF'e dönüştürüyor ve yerel olarak depoluyor. Kaynak URL yavaş yanıt verirse tüm API isteğiniz bloke olur. Yüksek hacimli akışlar için görselleri önceden POST /api/v1/media/upload-from-url uç noktasıyla jekcms'e yükleyin ve URL yerine dönen medya ID'sini kullanın.

Neler Ters Gidebilir

Otomatik bir yayın hattında en sık görülen hata türü, kaynak içerik çekmede yaşanan ağ zaman aşımıdır — jekcms API'sinin kendi hatası değil. Akışınızı, kaynak çekmelerin zaman zaman zaman aşımına uğrayacağını varsayarak tasarlayın: her başarısızlığı ölümcül saymak yerine yeniden deneme kuyruğuna ya da Slack uyarısına yönlendirin. force_duplicate: false varsayılanı (aşağıda) sayesinde yeniden denenen bir istek aynı gönderinin ikinci bir kopyasını oluşturamaz; bu yüzden n8n'in yeniden deneme mekanizmasını gözünüzü kırpmadan çalışır bırakabilirsiniz.

n8n Düğüm Yapılandırmasının Detayları

Yayın çağrısı için HTTP Request düğümünün tam yapılandırması aşağıdadır. Content-Type başlığı application/json olmalı ve API anahtarı X-API-Key başlığında iletilmeli — sorgu parametresi olarak değil. Sorgu parametresi yöntemi v1.5.0'da güvenlik gerekçesiyle kullanımdan kaldırıldı.

// n8n HTTP Request Düğüm Ayarları
Method: POST
URL: https://siteniz.com/api/v1/posts/publish-task
Authentication: None (başlık ile yönetiliyor)
Headers:
  X-API-Key: {{ $credentials.jekcmsApiKey }}
  Content-Type: application/json
Body (JSON):
{
  "title": "{{ $json.title }}",
  "content": "{{ $json.content }}",
  "author_id": 2,
  "category": "{{ $json.category }}",
  "featured_image": "{{ $json.image_url }}",
  "image_alt_text": "{{ $json.image_alt }}",
  "scheduled_at": "{{ $json.publish_date }}"
}

IF Düğümü ile Hata Yönetimi

API çağrısından sonraki IF düğümü {{ $json.success }} değerini kontrol ediyor. Başarısızlık durumunda hata dalı, gönderi başlığını ve hata mesajını içeren bir Slack bildirimi gönderiyor. 409 duplicate hataları için özellikle ayrı bir dala yönlendirme yapıyoruz — bu dal duplicate'ı kaydediyor ancak uyarı tetiklemiyor; çünkü bir içerik grubunu yeniden işlerken duplicate'lar beklenen bir durum.

Zamanlama ve Yayın Sıklığı

jekcms, API üzerinden üç yayın modunu destekliyor:

• Taslak modu (daha güvenli varsayılan): /draft uç noktasını kullanın — gönderi kaydedilir ama biri admin panelden inceleyip yayınlayana kadar görünmez kalır. Yeni bir akış ya da henüz güvenilirliği kanıtlanmamış bir içerik kaynağı için doğru başlangıç noktası budur; hiçbir şey bir insan gözden geçirmeden yayına çıkmaz.
• Zamanlanmış yayın: ISO 8601 zaman damgası iletin (örn. 2026-03-01T09:00:00+03:00) — jekcms cron'u belirtilen saatte yayınlar. Kaynak içeriğe güvendiğinizde ve her gönderiyi tek tek incelemeden öngörülebilir bir zamanlama istediğinizde makul bir seçenektir.
• Anında yayın: scheduled_at alanını atlarsanız gönderi API çağrısı başarılı olduğu anda yayına girer — araya hiçbir inceleme adımı girmez. Kaynak içerik yanlışsa, marka diline uymuyorsa ya da düşük kaliteliyse, kimse görmeden yayında olur. Bu modu bir akış taslak veya zamanlanmış yayınla kendini kanıtladıktan sonra geçilecek bir aşama olarak görün, başlangıç varsayılanı olarak değil.

Hangi modu seçerseniz seçin, karar size ait: jekcms bir inceleme kuyruğunu zorunlu kılmıyor, ama onu atlamanın riskini de gizlemiyor. Çoğu ekip için her şeyi taslak veya zamanlanmış yayından geçirip yayına çıkmadan önce gözden geçirmek — akış oturduktan sonra bile — daha güvenli bir alışkanlıktır.

SEO açısından, her şeyi aynı anda yayınlamak yerine zamanlanmış gönderileri gün içine yayıyoruz — örneğin Code düğümüyle sıralı zaman damgaları atayarak sabit aralıklarla dağıtabilirsiniz.

Kategori ve Etiket Otomasyonu

API, kategori adlarını metin dizesi olarak kabul ediyor. Kategori mevcut değilse jekcms onu otomatik olarak oluşturulmuş bir slug ile yaratıyor. Etiketler de aynı şekilde çalışıyor — tags alanında bir dizi metin gönderin. Bu, n8n akışınızın sitenin mevcut kategori ID'lerini bilmesine gerek olmadığı anlamına geliyor; içerik kaynağından gelen kategori adını doğrudan geçirebilir, arama veya oluşturma işlemini jekcms'e bırakabilirsiniz.

İzleme ve Hata Ayıklama

Her API isteği; istek yöntemi, uç nokta, kimlik doğrulama sonucu, yanıt kodu ve yürütme süresiyle birlikte logs/api-{tarih}.log dosyasına kaydediliyor. n8n hata ayıklaması için HTTP Request düğümünde "Include Response Headers" seçeneğini etkinleştirin — jekcms, sunucu günlük girişiyle eşleşen bir X-Request-ID başlığı döndürüyor. Destek talebi açarken hızlı günlük araması için bu ID'yi ekleyin.

• Yalnızca metin içeren bir gönderi genellikle bir saniyenin çok altında yayınlanır.
• featured_image URL'si iletmek, jekcms'in dosyayı çekmesi, AVIF'e dönüştürmesi ve depolaması için ek süre gerektirir — kaynak sunucu yavaşsa ya da görsel büyükse bu birkaç saniyeyi bulabilir.
• Kurulum başına maksimum eş zamanlı API isteği config/api.php üzerinden yapılandırılabilir (varsayılan 10).
• Hız sınırı: API anahtarı başına dakikada 120 istek (aşıldığında 429 durum kodu).

Yeniden Deneme Stratejisi ve Idempotency

Ağ hataları herhangi bir otomatik hatta kaçınılmazdır; bu yüzden bilinçli bir yeniden deneme stratejisi kurmaya değer.

jekcms yayın API'si, force_duplicate: false varsayılanı devredeyken idempotent'tir: n8n başarısız bir isteği yeniden denerse ve gönderi ilk denemede zaten oluşturulmuşsa, API ikinci bir kopya oluşturmak yerine 409 duplicate yanıtı döndürür. Bu sayede n8n'in yerleşik yeniden deneme mekanizmasını (Settings > Retry on Fail) az sayıda deneme ve aralarında bir bekleme süresiyle, duplicate içerik riski olmadan güvenle etkinleştirebilirsiniz.

Kaynak sunucunun yavaş olduğu, görsel ağırlıklı akışlarda yanıt sürelerinin on saniyeyi bulabildiği durumlarda, HTTP Request düğümünün zaman aşımı süresini buna göre artırın ve birkaç yeniden deneme hakkı tanıyın.

API seviyesindeki duplicate engelleme ile akış seviyesindeki otomatik yeniden denemelerin birleşimi, içerik hattınızın manuel müdahale olmadan geçici hatalardan toparlanabilmesini sağlar. Yeniden denemenin çözemediği tek durum, kalıcı olarak erişilemez bir kaynak URL'sidir — bunları sonsuza dek yeniden denemek yerine manuel incelemeye yönlendirin.