Entegrasyonlara genel bakış

Bu rehberde: 28 sağlayıcının nasıl bağlandığını, "proje bazlı" ile "organizasyon geneli" farkını, izin ekranı (OAuth) akışını, webhook adreslerini ve güvenliği öğrenirsiniz.

⏱ 15 dakika

Entegrasyon nedir?#

Entegrasyon, OrqLabs'ın sizin adınıza kullandığı bir dış hesaptır: bir X hesabı, bir WhatsApp numarası, bir Google Analytics mülkü, bir Serper anahtarı. Her sağlayıcının kendi kartı, bağlantı formu ve kurulum rehberi vardır.

Sağlayıcı kataloğu#

Her kartın ④ Kurulum rehberi bağlantısı o sağlayıcının rehberini yan panelde açar.

Üç bağlantı türü#

Token, API anahtarı, parola ve özel formların tümünde düğme Bağla'dır.

Dikkat: İzin ekranı sağlayıcıları için platform yöneticisinin ilgili uygulamayı önceden tanımlamış olması gerekir (META_APP_ID, INSTAGRAM_APP_ID, X_CLIENT_ID, LINKEDIN_CLIENT_ID, GOOGLE_CLIENT_ID, TIKTOK_CLIENT_KEY ve secret'ları). Tanımlı değilse kartta "Bu OAuth uygulaması platformda henüz yapılandırılmamış" uyarısı görürsünüz ve Bağla pasiftir.

İzin ekranı akışı adım adım#

1. Entegrasyonlar sayfasında karttaki Bağla düğmesine basın.
2. Proje bazlı sağlayıcılarda Proje seçin.
3. OrqLabs sizi sağlayıcıya yönlendirir.
4. Sağlayıcıda hesabınızı seçin ve izinleri onaylayın. İstenen izinler her rehberin İzinler ve kapsamlar bölümünde yazılıdır.
5. Sağlayıcı sizi OrqLabs'ın geri dönüş adresine gönderir. OrqLabs izni alır, şifreler ve sizi Entegrasyonlar sayfasına döndürür.
6. Kart Bağlı görünür. Bağlantıyı test et ile doğrulayın.

Geri dönüş adresini sağlayıcı konsoluna birebir girmeniz gerekir:

https://api.orqlabs.com/api/v1/integrations/oauth/<sağlayıcı>/callback

Sağlayıcı adı küçük harftir; örneğin google_analytics, x, linkedin. Tam adresi bağlantı penceresinden kopyalayın. http/https farkı ve sondaki / bile hataya yol açar.

Geliştirici notu: Akış GET /orgs/:orgId/integrations/oauth/<provider>/start?projectId=&redirect= ile başlar; dönüşte {APP_URL}/app/<slug>/integrations?connected=<id> adresine yönlenirsiniz. Yerel geliştirmede geri dönüş adresi http://localhost:4000/api/v1/integrations/oauth/<provider>/callback olur.

Proje bazlı mı, organizasyon geneli mi?#

• Proje bazlı: marka hesapları. Bir Instagram hesabı, bir WhatsApp numarası, bir GA4 mülkü tek bir markaya aittir. Her marka için ayrı bağlantı kurabilirsiniz. İş akışı çalışırken kendi projesinin hesabını kullanır.
• Organizasyon geneli: paylaşılan anahtarlar. Serper, Tavily, Hunter, Apollo, HubSpot, Google Sheets, Notion, Slack, Webhook, Anthropic ve OpenAI tüm projelerde geçerlidir; plan limitinden bir kez düşer.

Bir hesabı başka projeye taşımak için karta tıklayın; ayrıntı panelindeki Proje alanını değiştirip Kaydet deyin.

Node'lar ve ajanlar hesabı nasıl seçer?#

• Hesap gerektiren kutularda denetçi panelinde Bağlı hesap listesi çıkar. Yalnızca uygun sağlayıcının bağlı hesapları görünür.
• Ajan kutularında Entegrasyonlar çoklu seçimi vardır. Boşsa ajan projenin tüm hesaplarını kullanabilir.
• Bir ajan aracının ihtiyaç duyduğu hesap bağlı değilse adım hata notuyla döner; rapor yine üretilir, yalnızca o veri kaynağı eksik kalır.

Güvenlik ve şifreleme#

• Tüm kimlik bilgileri veritabanında AES-256-GCM ile şifrelenir.
• API hiçbir zaman kimlik bilgilerini döndürmez. Kartta yalnızca son 4 karakteri görürsünüz.
• Loglara kimlik bilgisi yazılmaz.
• Gelen webhook'lar imza doğrulamasından geçer (Meta, Slack, Twilio, Discord). Doğrulanamayan istek reddedilir.
• Yalnızca Sahip ve Yönetici bağlayabilir, düzenleyebilir ve kaldırabilir. Üye kullanır; İzleyici yalnızca görür.
• Her ekleme/kaldırma Ayarlar → Denetim günlüğü'ne yazılır.

Geliştirici notu: Şifreleme anahtarı CREDENTIALS_ENCRYPTION_KEY (32 byte hex).

Bağlantıyı test etme#

② Bağlantıyı test et sağlayıcıya küçük bir istek atar:

Başarısızsa mesaj bir kodla başlar: AUTH (izin geçersiz), RATE_LIMIT, INVALID (yanlış kimlik veya eksik alan), UPSTREAM (sağlayıcı hatası). Çözüm için ilgili rehberin Sık karşılaşılan hatalar bölümüne bakın.

Analitik hesaplarında ayrıca Şimdi senkronize et düğmesi vardır.

Kimlik bilgilerini yenileme#

• İzin ekranı: erişim süresi dolduğunda OrqLabs otomatik yeniler. Yenileme başarısızsa kart "Yeniden yetkilendirme gerekli" olur ve bildirim gelir. Yeniden yetkilendir aynı kaydı korur; iş akışları bozulmaz.
• Token / API anahtarı: entegrasyon kartında Kimlik bilgileri → Güncelle ile yeni değeri girin (boş bıraktığınız alanlar değişmez). Eski anahtarı sağlayıcıda iptal edin.
• ⑤ Bağlantıyı kes kalıcıdır; bu hesabı kullanan kutular bir sonraki çalıştırmada hata verir.
• Önerilen döngü: kalıcı token'ları 90 günde bir, API anahtarlarını sızıntı şüphesinde hemen yenileyin.

Webhook gerektiren sağlayıcılar#

WhatsApp, Telegram, Slack, Discord, Messenger ve Twilio SMS gelen mesajları webhook ile alır.

Her hesap için adres kalıbı:

https://api.orqlabs.com/api/v1/webhooks/<sağlayıcı>/<hesap kimliği>

Adresi (③) ve varsa doğrulama token'ını (④) ayrıntı panelinden kopyalayın. Telegram için OrqLabs kaydı sizin yerinize yapar; diğerlerinde adresi sağlayıcı konsoluna girmeniz gerekir.

Geliştirici notu: Yerel geliştirmede PUBLIC_WEBHOOK_URL için ngrok http 4000 çıktısını kullanın.

Plan limitleri#

Bağlı hesap sayısı: FREE 2, STARTER 8, PRO 30, ENTERPRISE sınırsız. Kendi yapay zekâ anahtarınız (BYOK) FREE planda kapalıdır. Limit dolduğunda Bağla "Plan limitine ulaşıldı" uyarısı verir.

Sık sorulan sorular#

Şifremi OrqLabs'a veriyor muyum? Hayır. İzin ekranında sağlayıcının kendi sayfasında izin verirsiniz. Token ve anahtar yöntemlerinde de şifrenizi değil, sağlayıcının ürettiği ayrı bir anahtarı girersiniz.

Bir hesabı iki projede kullanabilir miyim? Proje bazlı hesaplar tek projeye aittir. İkinci proje için aynı hesabı tekrar bağlayın.

Hesabı kaldırınca verilerim silinir mi? Yalnızca bağlantı silinir. Yayınlanan içerikler ve raporlar kalır.

Bağla düğmesi pasif, neden? Ya plan limitine ulaştınız ya da OAuth uygulaması platformda yapılandırılmamış. Kartın üzerindeki uyarıyı okuyun.

Sonraki adım#

• İlk entegrasyonunuzu bağlama
• WhatsApp Business (Cloud API)
• Google Analytics 4
• Güvenlik ve gizlilik