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.

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:

{
  "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 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.

Ü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 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

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

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

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:

{
  "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.):

{
  "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:

{
  "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 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:

{
  "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ı.

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.

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 içinde onlara karşı canlı istekler çalıştırabilirsiniz. Her birinin kendi kılavuzu vardır: AI Temsilcileri, Giriş Noktaları ve Yayınlar.

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 — entegrasyonunuz için doğru kimlik doğrulama yöntemini seçin.
• Hatalar ve Sayfalandırma — hataları yönetin ve sonuçlar arasında gezinin.
• API Erişimi — anahtarınızı oluşturun ve uygulamalı örnekleri inceleyin.