# API Başlangıç Kılavuzu Your AI Connector REST API, hesabınız üzerinde kendi entegrasyonunuzu oluşturmanıza olanak tanır. Kişiler oluşturabilir ve arayabilir, kampanyaları, SSS'leri, görevleri ve randevuları yönetebilir, mesaj gönderebilir, web kancaları (webhook) kaydedebilir, analizleri okuyabilir ve mesajlaşma kanallarını bağlayabilirsiniz; kontrol panelinin yaptığı her şeyi kod aracılığıyla gerçekleştirebilirsiniz. Bu, API dokümantasyonunun ana merkez sayfasıdır. Eğer Your AI Connector'ı halihazırda yerleşik bir entegrasyona sahip bir araca bağlıyorsanız, API'ye hiç ihtiyacınız olmayabilir. API, özel entegrasyonlar ve ölçekli otomasyonlar içindir. ::: note **Not:** Bu sayfalar geliştiriciler için yazılmıştır. Geliştirici değilseniz, bu bölümü teknik ekibinizle paylaşın. ::: --- ## Temel URL Her istek aynı temel web adresine gider ve bu dokümanlardaki tüm yollar buna göre görelidir: ``` https://api.youraiconnector.com/v1 ``` Yani kampanya uç noktası `https://api.youraiconnector.com/v1/campaigns`, kişi uç noktası `https://api.youraiconnector.com/v1/contacts` şeklindedir ve bu böyle devam eder. Tüm istekler güvenli bir bağlantı (HTTPS) kullanmalıdır. Düz HTTP istekleri reddedilir. --- ## API anahtarı alma API erişimi **ücretli bir özelliktir**. Planınız bunu içermiyorsa, her istek şu gövdeyle bir `403` döndürür: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` Planınızda API erişimi etkinleştirildikten sonra, kontrol panelinden bir anahtar oluşturun. Adım adım tam kılavuz [API Erişimi](../integrations/api-access.md) bölümündedir — kısaca: anahtarınızı oluşturmak veya yeniden oluşturmak için **Ayarlar → Entegrasyonlar → API Anahtarı** yolunu izleyin. API Anahtarı, Entegrasyonlar altında Webhook'lardan ayrı, kendine ait bir bölümdür ve yalnızca planınızda API erişimi açık olduğunda görünür. Anahtarı bir parola gibi saklayın: hesabınıza tam erişim sağlar. --- ## Kimlik Doğrulama API anahtarınızı dört farklı yolla gönderebilirsiniz. Hepsi, API anahtarı kimlik doğrulamasını kabul eden her uç noktada çalışır. | Yöntem | Nasıl | En uygun olduğu durum | |---|---|---| | Sorgu parametresi | `?apiKey=YOUR_API_KEY` | Hızlı testler, tarayıcı URL'leri, eski kurulumlar | | Başlık (Header) | `X-API-Key: YOUR_API_KEY` | Üretim entegrasyonları | | Bearer başlığı | `Authorization: Bearer YOUR_API_KEY` | Üretim entegrasyonları | | Firebase ID belirteci | `Authorization: Bearer ` | Yalnızca birinci taraf uygulama oturumları | Üretim ortamı için, anahtarınızın sunucu günlüklerine veya tarayıcı geçmişine düşmemesi adına başlık (header) biçimlerinden birini tercih edin. Sorgu parametresi biçimi her zaman çalışır ve tek seferlik testler için en basit yöntemdir. Her yöntemin ayrıntılı dökümü, örnekler ve hangisinin ne zaman kullanılacağına dair rehberlik için [Kimlik Doğrulama](authentication.md) bölümüne bakın. --- ## İlk isteğiniz İşte hesabınızdaki kampanyaları listeleyen eksiksiz ve çalışan bir çağrı. API anahtarınızı kullanır ve en son kampanyaları önce döndürür. **cURL** ```bash curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); console.log(data.campaigns); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/campaigns", params={"limit": 10}, headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() print(data["campaigns"]) ``` Başarılı bir yanıt şu şekilde görünür: ```json { "success": true, "campaigns": [ { "id": "NBCXrhqGPSFsd6MV7pRo", "name": "Inbound WhatsApp Leads", "type": "Incoming from Unknown Contacts", "status": "Live", "enabled": true, "archived": false, "created_at": 1700000000000, "ai_mode": true, "language": "en", "enabled_channels": ["whatsapp", "instagram"] } ], "next_cursor": null } ``` --- ## Başarı ve hata yanıtları Her JSON yanıtı bir `success` bayrağı taşır, böylece durum kodlarını ayrıştırmadan dallanma yapabilirsiniz. Başarılı bir yanıt `success: true` ve o uç nokta için verileri içerir (alan adı değişir — `campaigns`, `contacts`, `data` vb.): ```json { "success": true, "campaigns": [] } ``` Başarısız bir yanıt `success: false`, insan tarafından okunabilir bir `error` mesajı ve HTTP durumuyla eşleşen sayısal bir `error_code` içerir: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Verileri okumadan önce her zaman `success` (veya HTTP durumunu) kontrol edin. Durum kodu tablosunun tamamı ve büyük sonuç kümelerinde nasıl sayfalandırma yapılacağı için [Hatalar ve Sayfalandırma](errors-and-pagination.md) bölümüne bakın. --- ## Hız sınırları Kimliği doğrulanmış istekler, API anahtarı başına **dakikada 300 istek** ile sınırlandırılmıştır. Ayrıca, o hesap için yapılan tüm kimliği doğrulanmış istekleri sayan, **hesap başına dakikada 1.200 istek** gibi daha geniş bir üst sınır da mevcuttur. Her iki sınırı da aşarsanız, `429` yanıtını alırsınız: ```json { "success": false, "error_code": 429, "error": "Rate limit exceeded. Please try again later." } ``` Kısa bir süre bekleyin ve tekrar deneyin. Ayrıca, mevcut kullanımınızı istediğiniz zaman `GET https://api.youraiconnector.com/v1/api-keys/usage` ile kontrol edebilirsiniz; bu, mevcut pencerede kaç istek kullandığınızı ve ne zaman sıfırlanacağını döndürür — istemci tarafında hız sınırlaması oluşturmak için kullanışlıdır. Bkz. [API Anahtarları](api-keys.md). --- ## Kaynak kılavuzları Aşağıdaki kaynak gruplarının her biri; tam yollar, istek alanları ve yanıt şekillerini içeren kendi kılavuzuna sahiptir. | Kaynak | Neleri kapsar | |---|---| | [AI Temsilcileri](agents.md) | AI Temsilcileri oluşturun ve yapılandırın: ayarlar, aktif saatler, bilgi, etiketleme kuralları, araçlar, medya ve taslaklar | | [Giriş Noktaları](entry-points.md) | Yeni bir konuşmayı hangi AI Temsilcisinin yanıtlayacağına karar verin: kanal varsayılanları, WhatsApp numarası başına bir Temsilci, anahtar kelime, yorum ve takipçi kuralları | | [Yayınlar](broadcasts.md) | Bir kişi listesine tek seferlik gönderimler oluşturun, fiyatlandırın, başlatın, duraklatın ve kopyalayın | | [Kampanyalar](campaigns.md) | Kampanyaları ve bot yapılandırmalarını oluşturun, güncelleyin, kopyalayın, etkinleştirin, arşivleyin ve inceleyin | | [Kişiler](contacts.md) | Kişileri oluşturun, arayın, listeleyin, güncelleyin, içe aktarın, etiketleyin ve silin | | [SSS](faqs.md) | AI asistanınızın kullandığı soru-cevap girişlerini yönetin ve bunları kampanyalara bağlayın | | [Bilgi Bankası](knowledge-base.md) | Web sitelerini ve belgeleri AI'nızın bilgisine aktarın ve SSS'leri gruplar halinde birleştirin | | [Görevler](tasks.md) | CRM görevlerini, pano aşamalarını ve görev türlerini oluşturun ve yönetin | | [Mesajlar](messages.md) | Giden mesajlar gönderin ve konuşma geçmişini okuyun | | [Randevular](appointments.md) | Randevu alın, yeniden planlayın, iptal edin ve silin | | [Kanallar](channels.md) | Mesajlaşma kanallarını bağlayın ve bağlantısını kesin, numaralar satın alın ve her kanalda yeni konuşmaları hangi AI Temsilcisinin yanıtlayacağını ayarlayın | | [Şablonlar](templates.md) | WhatsApp mesaj şablonları oluşturun, gönderin ve onay durumlarını kontrol edin | | [Analitik](analytics.md) | Günlük mesaj etkinliği istatistiklerini, kredi kullanımını ve AI maliyet özetlerini okuyun | | [Web kancaları](webhooks.md) | Gerçek zamanlı olay bildirimleri almak için uç noktaları kaydedin | | [Ekip](team.md) | Ekip üyelerini, davetleri, rolleri, izinleri ve departmanları yönetin | | [API Anahtarları](api-keys.md) | API anahtarınızı inceleyin, döndürün ve iptal edin, hız sınırı kullanımını kontrol edin ve sınırlı erişime sahip ek anahtarlar oluşturun | ### Temsilciler, Giriş Noktaları ve Yayınlar AI Temsilcileri, Giriş Noktaları ve Yayınların tümü yayınlanmış OpenAPI spesifikasyonunda yer alır, böylece tam alanlarına göz atabilir ve [API gezgini](reference.md) içinde onlara karşı canlı istekler çalıştırabilirsiniz. Her birinin kendi kılavuzu vardır: [AI Temsilcileri](agents.md), [Giriş Noktaları](entry-points.md) ve [Yayınlar](broadcasts.md). --- ## Bu belgeleri Markdown olarak okuma Bu belgelerdeki her sayfanın düz bir Markdown eşi vardır: sayfa adresini alın ve sonuna `/index.md` ekleyin. Yani bu sayfa `https://docs.youraiconnector.com/api/getting-started/index.md` adresinde de mevcuttur ve bir web sayfası yerine düz metin olarak gelir; bir sayfayı bir yapay zeka asistanına yapıştırmak veya bir betiğe çekmek istediğinizde kullanışlıdır. Tüm seti incelemek için, yayınladığımız her sayfayı listeleyen `https://docs.youraiconnector.com/sitemap.xml` adresinden başlayın. Belgelerin kasıtlı olarak arama motorlarının dışında tutulduğunu unutmayın, bu nedenle bu adreslere doğrudan erişmek, kod içinden ulaşmanın yoludur. Henüz anahtar korumalı bir belge uç noktası ve toplu indirme özelliği bulunmamaktadır; Markdown eşleri ve site haritası arayüzün tamamını oluşturur ve hiçbiri API anahtarı gerektirmez. --- ## Sonraki adımlar - [Kimlik Doğrulama](authentication.md) — entegrasyonunuz için doğru kimlik doğrulama yöntemini seçin. - [Hatalar ve Sayfalandırma](errors-and-pagination.md) — hataları yönetin ve sonuçlar arasında gezinin. - [API Erişimi](../integrations/api-access.md) — anahtarınızı oluşturun ve uygulamalı örnekleri inceleyin.