GelsinSatışlar Public REST API v1

API Dokümantasyonu & Genel Bakış

GelsinSatışlar Public REST API, e-ticaret altyapılarınızı (ikas, Shopify, WooCommerce), ön muhasebe sistemlerinizi ve özel yazılımlarınızı WhatsApp CRM panonuza bağlamanızı sağlar.

Hiç Bilmeyenler İçin Basitçe Anlatım

API Nedir? (Bir Garson Örneğiyle)

Bir lokantaya gittiğinizi düşünün. Siz müşterisiniz, mutfak da veritabanı (sistemin kalbi). Siz mutfağa girip tencereleri karıştıramazsınız. Aranızda garson vardır. Siparişinizi garsona söylersiniz, garson mutfağa iletir ve yemeğinizi getirir.

API tam olarak bu garsondur.Programınız (müşteri) ile GelsinSatışlar'ın veritabanı (mutfak) arasındaki kuryedir. Siz API'ye "şu telefon numarasına mesaj gönder" dersiniz; API gider, işi yapar ve sonucu size getirir. Mesaj göndermek, müşteri listesini çekmek, toplu kampanya başlatmak. Hepsi bu "garson" üzerinden yapılır.

Uç Nokta (Endpoint)

Garsonun oturduğu masa adresi gibidir. Her işin ayrı adresi vardır. "/api/v1/messages" mesaj gönderme adresidir.

API Anahtarı (Bearer Token)

GelsinSatışlar'ın size verdiği kimlik kartıdır. İsteklerin gerçekten sizden geldiğini kanıtlar.

JSON

Bilgilerin yazıldığı ortak dil. Tıpkı menünün yazıldığı dil gibi. Herkes (her program) anlar.

1. Base URL (Temel Adres)

Tüm API istekleri güvenli HTTPS protokolü üzerinden aşağıdaki kök adrese yapılır:

https://gelsinsatislar.com/api/v1

2. Kimlik Doğrulama (Authentication)

API isteklerinizi yetkilendirmek için her istekte HTTP Authorization başlığında (Header) API anahtarınızı iletmeniz gerekmektedir:

Basitçe Anlatım

Header (başlık), gönderdiğiniz isteğin üstüne yapıştırılan bir etikettir. Kargoda adres etiketi gibi. Bu etikete "Ben GelsinSatışlar müşterisiyim, kimliğim şu" yazarsınız. "Bearer" kelimesi de "taşıyıcı" demektir; yani "bu kimlik kartını taşıyorum" anlamına gelir. GelsinSatışlar bu etiketi görünce isteği size ait kabul eder.

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

Güvenlik Uyarısı: API Anahtarınızı Gizli Tutun

API anahtarlarınız hesabınıza tam erişim yetkisine sahip olabilir. Anahtarınızı asla istemci tarafı (frontend / mobile app) kodlarında açık şekilde saklamayın. Yalnızca sunucu tarafında (Backend / Webhook) kullanı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:

Başarılı Yanıt (200 / 201)

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

Hatalı Yanıt (400 / 401 / 429)

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

Basitçe Anlatım

HTTP durum kodları, garsonun size verdiği kısa cevaplardır: 200 "tamam, getirdim!", 400 "istekte hata var, doğru yazmamışsın", 401 "kimlik kartın geçersiz", 429 "çok hızlı istek atıyorsun, biraz yavaşla" demektir. Kodun 2 ile başlaması başarı, 4 ile başlaması sizin kaynaklı hata, 5 ile başlaması ise bizim tarafımızda bir sorun olduğu anlamına gelir.

4. HTTP Durum & Hata Kodları

HTTP Kod	Durum	Açıklama
200 OK	Başarılı	İstek başarılı bir şekilde işlendi ve veri döndü.
201 Created	Oluşturuldu	Yeni bir mesaj veya müşteri kaynağı başarıyla oluşturuldu.
400 Bad Request	Hatalı İstek	Eksik parametre, E.164 uyumsuz telefon veya geçersiz JSON.
401 Unauthorized	Yetkisiz	Geçersiz API Anahtarı veya yetersiz Scope erişimi.
429 Too Many Requests	Hız Sınırı Aşımı	Dakikalık istek limitine ulaşıldı.

5. Sayfalama ve Keyset Cursor

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

Basitçe Anlatım

Cursor imlecini bir kitap ayracı gibi düşünün. Okuduğunuz yeri kaybedersiniz diye ayraç koyarsınız; aynı şekilde API de size "buraya kadar geldik, devamını istersen şu ayracı ver" der. limit ile sayfa başına kaç kayıt istediğinizi söylersiniz (varsayılan 50, en fazla 100).

# İ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 alıp ikinci sayfaya geç
curl -X GET "https://gelsinsatislar.com/api/v1/contacts?limit=50&cursor=eyJvZmZzZXQiOjUwfQ" \
  -H "Authorization: Bearer gelsinsatislar_live_YOUR_API_KEY"

Neden sayfa sayfa? Binlerce kaydı tek istekte göndermek hem yavaş hem de ağır olurdu. Sayfalama, veriyi kontrollü ve hızlı şekilde almanızı sağlar.