Otopilot API Entegrasyonu
Hazırlayan Ersin DorlakSon güncelleme:
Bu Sayfa Ne Yapar
Otopilot API, kendi yazılımıyla çalışan sitelerin (ASP, PHP, React, Next.js ve benzeri) hazır SEO düzeltmelerini proje anahtarıyla sunucu tarafında çekip kalıcı olarak uygulamasını ve uyguladığını bildirmesini sağlayan geliştirici kanalıdır. Hazır eklentisi olmayan bir altyapıda düzeltmeleri elle taşımak sürdürülebilir değildir; bu kanal düzeltmeleri makinenin okuyacağı bir listeye çevirir ve sayfa gövdesi, robots.txt, site haritası, yönlendirme ve blog yazısı dahil tam kapsam sunar.
Kurulum ekranı SEO Onarım ekranında Kanal & Kurulum görünümündeki Otopilot API kartından açılır ve Geliştirici API'si ve MCP başlığını taşır. Ekranda anahtar kutusu (API anahtarı üret, Göster, Kopyala, Yeniden üret, Bağlantıyı kes), API adresi, MCP adresi ve Başlık satırları, Geliştirici referansını aç bağlantısı, MCP kurulumu düğmesi ve altı bölüm bulunur: Senkron sağlığı, API sürümü, İzinler, IP kısıtı, Olay adresleri (webhook) ve Kullanım.
Akış dört uçtan oluşur: handshake anahtarı doğrular, rules uygulanmaya hazır düzeltmeleri döndürür, applied uygulanan kimlikleri alır, status senkron durumunu verir. İlk rules çağrısında since gönderilmez; sonraki çağrılarda önceki yanıttaki cursor değeri since olarak verilir ve yalnız yeni ya da değişen düzeltmeler gelir, kaldırılanlar removedIds içinde döner. Tek yanıtta en fazla 500 düzeltme istenebilir (varsayılan 100). Anahtar X-SP-Auth başlığıyla ya da Authorization: Bearer ile gönderilir, kodun yazıldığı sürüm X-SP-Api-Version başlığıyla bildirilir. Anahtar başına dakikada 300, IP başına dakikada 600 istek sınırı vardır; aşılırsa 429 döner. Senkron görevinin en az 15 dakikada bir çalışması beklenir; 24 saat çekim olmazsa ekran uyarır. Hazır bağlayıcı isteyenler için Next.js ve PHP paketleri ayrı kılavuzda anlatılır.
Kılavuz, siteyi yöneten geliştiriciler ve bir geliştiriciyle çalışan site sahipleri içindir. Kurulum bitince Senkron sağlığı bölümü Düzeltmeler alınıyor gösterir, düzeltmeler siteye ulaştıkça Düzeltmeler sekmesinde Çekildi ve Uygulandı durumlarına geçer.
İki yanlış anlama sık görülür. Birincisi, bu anahtarın hesap düzeyindeki API jetonlarıyla aynı olduğunu sanmaktır: bu anahtar tek bir projeye bağlı entegrasyon anahtarıdır, hesabınızın genel API jetonları Kullanıcı Ayarları altındaki API Erişimi sayfasında ayrıca yönetilir. İkincisi, anahtarı tarayıcı koduna koymaktır; anahtar düzeltme ve yayın kanalına erişim verdiği için yalnız sunucuda saklanmalıdır.
Anlatılan sayfayı panelde aç(giriş yapınca açılır)
Ön Koşullar
- Sunucu tarafında HTTP isteği atıp JSON işleyebilen bir yazılımınız ve bunu kurabilecek bir geliştiriciniz olmalıdır.
- Projede tamamlanmış bir SEO taraması ve paketinizde otomatik düzeltme hakkı bulunmalıdır; düzeltme kapalıyken anahtar çalışır ama rules ve applied uçları 403 döner.
- Anahtarı üretmek, yenilemek, iptal etmek ve izinleri değiştirmek proje sahibine açıktır.
- Düzeltmeleri en az 15 dakikada bir çeken zamanlanmış bir görev (cron) kurabilmeniz gerekir.
Adım Adım Kullanım
- SEO Onarım ekranında Kanal & Kurulum görünümüne geçin, Site ve geliştirici grubundaki Otopilot API kartında Bağla düğmesine basın. Otomatik düzeltme kapalıysa kurulum penceresinde modu seçip Kaydet ve başlat deyin; "Niyet kaydedildi: Otopilot API." bildirimi çıkar.
- Anahtar oluşturun kutusunda API anahtarı üret düğmesine basın. Anahtar sp_ ile başlar; Göster ile açıp Kopyala ile alın ve yalnız sunucunuzun gizli ayarlarında saklayın. Göster anahtarı değiştirmez; Yeniden üret eskisini anında geçersiz kılar.
- API adresi ve Başlık satırlarını kopyalayın. Her isteğe anahtarı X-SP-Auth başlığıyla (ya da Authorization: Bearer) ve kodunuzun sürümünü X-SP-Api-Version başlığıyla ekleyin; sürüm bildirilmezse API sürümü bölümü uyarı verir.
- Sunucunuzdan POST /api/seo-repair/v1/handshake isteğiyle anahtarı doğrulayın; yanıt bağlı projeyi döner. Uçların gövde ve yanıt biçimleri için Geliştirici referansını aç bağlantısını kullanın.
- GET /api/seo-repair/v1/rules/{projectId} ile hazır düzeltmeleri çekin. İlk çağrıda since vermeyin; yanıttaki cursor değerini saklayıp sonraki çağrıda since olarak gönderin. hasMore true ise aynı çağrıyı cursor ile tekrarlayın, removedIds içindeki kimliklerin değişikliklerini sitenizden kaldırın.
- Düzeltmeleri sitenize uygulayın ve POST /api/seo-repair/v1/rules/{projectId}/applied ile uygulanan kimlikleri ids alanında gönderin. Blog yazısı ve yeni sayfa için urls alanında sitedeki yayın adresini de bildirin; aynı kimliği tekrar bildirmek zarar vermez.
- Bu çekme ve bildirme döngüsünü en az 15 dakikada bir çalışan bir zamanlanmış göreve bağlayın. Senkron sağlığı bölümünde "Son çekim" zamanının güncellendiğini ve durumun Düzeltmeler alınıyor olduğunu kontrol edin.
- Modül uçlarını (sohbet, form, randevu, yorum) kullanacaksanız İzinler bölümünde gerekli izinleri işaretleyip İzinleri kaydet deyin. SEO uçları izin sormaz; sitede açık olmayan bir modülün izni verilemez.
- Güvenliği artırmak için IP kısıtı bölümünde sunucu adreslerinizi Ekle ile girin, ardından Yalnız listedeki adreslere izin ver anahtarını açın. Listede olmayan adreslerden gelen istekler 403 SP_API_IP_DENIED alır.
- Kullanım bölümünde son 90 günün isteklerini IP'ye göre inceleyin; tanımadığınız bir adres görürseniz anahtarı yenileyin, kendi sunucunuzsa satırdaki Listeye ekle ile IP listesine alın.
Entegrasyon akışı
- Anahtarı panelden üretin ve sunucunuzda gizli tutun.
- handshake ile anahtarı ve bağlı projeyi doğrulayın.
- rules ucundan since ve cursor ile yalnız yeni ya da değişen düzeltmeleri çekin; hasMore bitene kadar devam edin.
- Düzeltmeleri sitenizde uygulayın, removedIds içindekileri kaldırın.
- applied ucuyla uygulanan kimlikleri (gerekirse urls ile) bildirin; tekrar bildirim zararsızdır.
- status ucuyla mod, aktif kanal, son çekim ve durum sayılarını izleyin.
Anahtarı yönetirken dikkat
Yeniden üret eski anahtarı anında geçersiz kılar. Aynı anahtar WordPress ve OpenCart eklentileriyle ve MCP bağlantısıyla ortak kullanıldığından bu kanalların hepsi "bağlantı bekliyor" durumuna düşer ve yeni anahtarı her birine girmeniz gerekir. Bağlantıyı kes anahtarı iptal eder; sonraki istekler 401 alır ve aynı anahtarı kullanan eklentiler de bağlantısını kaybeder.
Ekrandaki öğeler
- Anahtar oluşturun / API anahtarı — Anahtar yoksa API anahtarı üret; varsa maskelenmiş anahtar, oluşturulma tarihi, Göster / Gizle, Kopyala, Yeniden üret ve Bağlantıyı kes.
- API adresi, MCP adresi, Başlık — Entegrasyonda kullanılacak temel adres, MCP uç adresi ve anahtar başlığının adı; her biri Kopyala düğmeli.
- Geliştirici referansını aç — Tüm uçların istek ve yanıt biçimlerini anlatan referans.
- MCP kurulumu — Yapay zekâ asistanı bağlantısı için yapılandırma penceresi.
- Senkron sağlığı — Düzeltmeler alınıyor ya da Siten düzeltmeleri almıyor, son çekim zamanı.
- API sürümü — Güncel sürüm, entegrasyonunuzun bildirdiği sürüm ve eksik güncelleme sayısı.
- İzinler — Sohbet, form, randevu, yorum ve Google yorumları için okuma/yazma izinleri ve İzinleri kaydet.
- IP kısıtı — Yalnız listedeki adreslere izin ver anahtarı, adres alanı, Ekle ve Kaldır.
- Olay adresleri (webhook) — Webhook, izin, kullanım ve IP listesinin Entegrasyonlar ekranından da yönetilebildiğini anlatan bağlantı.
- Kullanım — Son 90 günün istekleri; IP, İstek, Son istek, Listede sütunları ve Listeye ekle.
Sonuçları nasıl yorumlarsınız
- Düzeltmeler alınıyor son 24 saatte en az bir çekim yapıldığını söyler; Siten düzeltmeleri almıyor görünüyorsa zamanlanmış görev durmuştur.
- "Bu anahtarla henüz düzeltme çekilmedi." ifadesi entegrasyonun hiç rules çağırmadığını gösterir; handshake başarılı olsa bile kanal ilk çekime kadar aktifleşmez.
- API sürümü bölümünde eksik güncelleme sayısı sıfırdan büyükse entegrasyonunuz yeni alanları tanımıyor olabilir; geliştirici referansındaki sürüm notlarını okuyun.
- Düzeltmeler sekmesinde Çekilmeye hazır durumunda bekleyen kartlar sitenin henüz çekmediği, Çekildi durumundakiler çekilip uygulandığı bildirilmeyen düzeltmelerdir; ikincisi uzun sürüyorsa applied çağrısını kontrol edin.
Örnek senaryo
örnek.com, kurum içi bir ekip tarafından yazılmış Laravel tabanlı bir emlak sitesi; hazır eklenti yok. Geliştirici Otopilot API kartında Bağla deyip API anahtarı üret ile anahtarı alıyor ve sunucunun ortam değişkenlerine koyuyor. Her 10 dakikada bir çalışan bir zamanlanmış görev yazıyor: görev önce handshake, sonra rules ucunu cursor ile çağırıyor, gelen başlık ve meta açıklama değişikliklerini ilan sayfalarının veritabanı alanlarına yazıyor ve applied ile kimlikleri bildiriyor.
İlk çalıştırmadan sonra Senkron sağlığı Düzeltmeler alınıyor gösteriyor. Ekip IP kısıtı bölümüne iki sunucu adresini ekleyip Yalnız listedeki adreslere izin ver anahtarını açıyor. Kullanım tablosunda yalnız bu iki adres görünüyor. Düzeltmeler sekmesindeki kartlar çekim ve bildirim sonrasında Uygulandı oluyor; yeniden taramadan sonra Doğrulandı durumuna geçiyor.
İpuçları
- cursor değerini kalıcı bir yerde (veritabanı ya da dosya) saklayın; görev yeniden başladığında kaldığı yerden devam eder ve aynı düzeltmeleri yeniden işlemez.
- Her isteğe X-SP-Api-Version başlığını ekleyin; yeni bir sürüm çıktığında API sürümü bölümü eksik güncellemeleri size gösterir.
- Sunucu adresleriniz sabitse IP kısıtını açın; anahtar sızsa bile başka adresten kullanılamaz.
- Next.js ya da özel PHP siteleri için Next.js ve PHP bağlayıcı kılavuzundaki hazır paketler bu döngünün tamamını kurar.
- Hesap düzeyinde başka otomasyonlar için proje anahtarı yerine API Erişimi sayfasındaki jetonları kullanın; proje anahtarını yalnız bu projenin entegrasyonuna ayırın.
Sık yapılan hatalar
- Anahtarı ön yüz (tarayıcı) koduna ya da herkese açık bir depoya koymak.
- Her çağrıda since göndermeyip tüm listeyi yeniden çekmek; istek sınırına takılmayı ve gereksiz yükü artırır.
- Düzeltmeleri uygulayıp applied bildirimini atlamak; kartlar Çekildi durumunda kalır ve doğrulama sırası gecikir.
- Bağlantı sorununu anahtarı yeniden üreterek çözmeye çalışmak ve WordPress, OpenCart ya da MCP bağlantılarını da koparmak.
Sık Karşılaşılan Sorunlar
- API anahtarı gerekli. Anahtarı X-SP-Auth başlığıyla ya da Authorization: Bearer ile gönderin.: İstekte anahtar başlığı yoktur ya da yanlış adla gönderilmiştir. Başlık adını Başlık satırındaki değerle birebir yazın.
- API anahtarı geçersiz.: Anahtar yanlış kopyalanmış, iptal edilmiş ya da Yeniden üret ile değiştirilmiştir (401). Paneldeki güncel anahtarı sunucu ayarlarınıza girin.
- Anahtar bu projeye ait değil.: İstek yolundaki projectId ile anahtarın projesi farklıdır. handshake yanıtındaki proje kimliğini kullanın.
- Bu API anahtarı yalnız izin verilen IP adreslerinden kullanılabilir; istek … adresinden geldi ve listede yok.: IP kısıtı açıkken isteğin geldiği adres listede değildir (403 SP_API_IP_DENIED). Kullanım tablosundaki Listeye ekle ile adresi ekleyin.
- SEO Hata Düzeltme bu proje için kapalı. Anahtar çalışır; ancak düzeltme uçları (rules, applied) 403 döner.: Projede otomatik düzeltme kapalıdır. Kanal & Kurulum görünümünden düzeltmeyi açın; handshake ve status uçları bu sırada da çalışır.
- Siten düzeltmeleri almıyor: Son 24 saatte bu anahtarla çekim yapılmamıştır. Zamanlanmış görevin çalıştığını ve en az 15 dakikada bir rules ucunu çağırdığını kontrol edin.
- Geçersiz "since" — ISO 8601 tarih bekleniyor.: since parametresine cursor dışında bir değer gönderilmiştir. Önceki yanıttaki cursor değerini olduğu gibi kullanın; ilk çağrıda since göndermeyin.
- Çok fazla istek. Biraz sonra tekrar dene.: Anahtar başına dakikada 300 ya da IP başına dakikada 600 istek sınırı aşılmıştır (429). Yanıttaki Retry-After süresi kadar bekleyin ve döngünüzü cursor ile seyrekleştirin.
İlgili Kılavuzlar
Bu adımları kendi sitenizde uygulayın
Önce ücretsiz site analiziyle sitenizdeki sorunları görün. Hesabınız varsa rehberde anlatılan sayfayı panelde açın.