API Dokümantasyonu & Genel Bakış

2. Kimlik Doğrulama (Authentication)

Tüm API istekleri kimlik doğrulaması gerektirir. Her istekte HTTP Authorization başlığında (Header) API anahtarınızı iletmeniz gerekmektedir:

curl -X GET "https://gelsinsatislar.com/api/v1/me" \
  -H "Authorization: Bearer gelsinsatislar_live_9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c" \
  -H "Content-Type: application/json"

Kapsam (Scope) Referansı

Her API anahtarı yalnızca kendisine atanan kapsam (...) ile çalışır. Gereksiz kapsam vermekten kaçının:

3. Standart Yanıt Formatı (Envelope Pattern)

GelsinSatışlar API'sinden dönen tüm başarılı ve hatalı yanıtlar tutarlı bir JSON zarfı (envelope) içinde sunulur. Bu yapı, istemci tarafında tutarlı hata yönetimi ve veri işleme sağlar.

{
  "data": {
    "message_id": "msg_94821a",
    "status": "sent",
    "to": "+905320000000"
  },
  "error": null
}

{
  "data": null,
  "error": {
    "code": "invalid_phone_number",
    "message": "Telefon numarası E.164 formatında olmalıdır."
  }
}

4. HTTP Durum & Hata Kodları

API, HTTP durum kodları kullanarak isteklerin sonucunu belirtir. Aşağıdaki tabloda karşılaşılabilecek durum kodları ve anlamları yer almaktadır:

Alan Hata Kodları (Domain Error Codes)

HTTP durum kodlarına ek olarak, yanıt gövdesindeki error.code alanı bölümeye özel hata bilgisi sağlar. Aşağıdaki kodlar stabil olup programatik olarak güvenle kullanılabilir:

5. Sayfalama ve Keyset Cursor

Müşteri ve sohbet gibi uzun listeler tek seferde döndürülmez. Sonuçlar sayfa sayfa sunulur; her yanıt, bir sonraki sayfaya geçmek için kullanacağınız bir cursor (imleç) değeri döndürür.

# İlk sayfa: 50 kayıt iste
curl -X GET "https://gelsinsatislar.com/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer gelsinsatislar_live_YOUR_API_KEY"

# Yanıttaki next_cursor değerini alarak ikinci sayfaya geç
curl -X GET "https://gelsinsatislar.com/api/v1/contacts?limit=50&cursor=eyJvZmZzZXQiOjUwfQ" \
  -H "Authorization: Bearer gelsinsatislar_live_YOUR_API_KEY"

6. Hız Sınırı (Rate Limit)

API istekleri anahtar bazlı (per-key) olarak dakikada 120 istek ile sınırlandırılmıştır. Bu sınır, saniyede yaklaşık 2 istek anlamına gelir ve çoğu entegrasyon ve otomasyon senaryosu için yeterlidir.

{
  "data": null,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for this API key"
  }
}