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.
Uç nokta referansı
Uç noktaları filtreleyip parametreleri, örnek istekleri ve yanıt tanımlarını açabilirsiniz. OpenAPI 3.1 JSON tanımını açın veya . Koleksiyonu içe aktarın, apiKey değişkenine anahtarınızı girin.
17 uç nokta
GET /api/v1/me
Read the account and scopes bound to this API key. No scope is required.
Gerekli kapsam: Geçerli API anahtarı yeterli
curl -X GET 'https://your-crm.example.com/api/v1/me' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/contacts
List account contacts newest first, using cursor pagination.
Gerekli kapsam: contacts:read
limit(query, isteğe bağlı)cursor(query, isteğe bağlı) — Opaque next_cursor from the preceding page.search(query, isteğe bağlı)tag(query, isteğe bağlı)
curl -X GET 'https://your-crm.example.com/api/v1/contacts' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
POST /api/v1/contacts
Find or create a contact by phone; 200 for an existing contact, 201 for a new contact.
Gerekli kapsam: contacts:write
curl -X POST 'https://your-crm.example.com/api/v1/contacts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"phone":"+905000000000","name":"Örnek Kişi"}'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/contacts/{id}
Read one contact. A foreign account ID returns 404.
Gerekli kapsam: contacts:read
id(path, zorunlu)
curl -X GET 'https://your-crm.example.com/api/v1/contacts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
PATCH /api/v1/contacts/{id}
Update name/email/company or replace tags; null clears a scalar field.
Gerekli kapsam: contacts:write
id(path, zorunlu)
curl -X PATCH 'https://your-crm.example.com/api/v1/contacts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"company":"Örnek Şirket"}'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
DELETE /api/v1/contacts/{id}
Permanently delete a contact and its related conversations/messages. Returns deletion counts.
Gerekli kapsam: contacts:write
id(path, zorunlu)
curl -X DELETE 'https://your-crm.example.com/api/v1/contacts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/conversations
List account conversations using cursor pagination.
Gerekli kapsam: conversations:read
limit(query, isteğe bağlı)cursor(query, isteğe bağlı) — Opaque next_cursor from the preceding page.status(query, isteğe bağlı)contact_id(query, isteğe bağlı)
curl -X GET 'https://your-crm.example.com/api/v1/conversations' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/conversations/{id}
Read one conversation. A foreign account ID returns 404.
Gerekli kapsam: conversations:read
id(path, zorunlu)
curl -X GET 'https://your-crm.example.com/api/v1/conversations/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/conversations/{id}/messages
List messages newest first after verifying conversation ownership.
Gerekli kapsam: messages:read
id(path, zorunlu)limit(query, isteğe bağlı)cursor(query, isteğe bağlı) — Opaque next_cursor from the preceding page.
curl -X GET 'https://your-crm.example.com/api/v1/conversations/{id}/messages' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
POST /api/v1/messages
Send a message through the configured WhatsApp provider. Sandbox keys simulate writes.
Gerekli kapsam: messages:send
curl -X POST 'https://your-crm.example.com/api/v1/messages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"to":"+905000000000","type":"text","text":"Merhaba"}'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
POST /api/v1/broadcasts
Accept a template campaign for asynchronous delivery; poll its ID for progress.
Gerekli kapsam: broadcasts:send
curl -X POST 'https://your-crm.example.com/api/v1/broadcasts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"template_name":"order_update","template_language":"tr","recipients":[{"to":"+905000000000","params":["A123"]}]}'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/broadcasts/{id}
Read campaign status and recipient progress.
Gerekli kapsam: broadcasts:send
id(path, zorunlu)
curl -X GET 'https://your-crm.example.com/api/v1/broadcasts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/webhooks
List all registered webhook endpoints; next_cursor is always null.
Gerekli kapsam: webhooks:manage
curl -X GET 'https://your-crm.example.com/api/v1/webhooks' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
POST /api/v1/webhooks
Register an HTTPS endpoint. Its signing secret is returned once at creation.
Gerekli kapsam: webhooks:manage
curl -X POST 'https://your-crm.example.com/api/v1/webhooks' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/webhook","events":["message.received"]}'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
GET /api/v1/webhooks/{id}
Read a webhook endpoint without its signing secret.
Gerekli kapsam: webhooks:manage
id(path, zorunlu)
curl -X GET 'https://your-crm.example.com/api/v1/webhooks/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
PATCH /api/v1/webhooks/{id}
Update url/events/is_active. Re-enabling resets the failure streak.
Gerekli kapsam: webhooks:manage
id(path, zorunlu)
curl -X PATCH 'https://your-crm.example.com/api/v1/webhooks/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"is_active":false}'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
DELETE /api/v1/webhooks/{id}
Delete a registered webhook endpoint.
Gerekli kapsam: webhooks:manage
id(path, zorunlu)
curl -X DELETE 'https://your-crm.example.com/api/v1/webhooks/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Dene
İsteği bu sayfadan gerçek API'ye gönderir. Anahtarınız yalnızca bu sekmede, bellekte tutulur ve kaydedilmez. Yazma uçlarını denemek için gelsinsatislar_test_ ile başlayan bir test anahtarı kullanın; canlı anahtar gerçek veriyi değiştirir.
Hızlı Başlangıç (Quick Start)
API'yı kullanmaya başlamak için aşağıdaki adımları izleyin:
API Anahtarı Oluşturun
GelsinSatışlar panosundan Ayarlar → API Anahtarları → Yeni API Anahtarı yolunu izleyerek anahtarınızı oluşturun. Anahtar yalnızca bir kez gösterilir.
Test İsteği Gönderin
Aşağıdaki komutu terminale yapıştırarak anahtarınızın çalıştığını doğrulayın:
curl -X GET "https://gelsinsatislar.com/api/v1/me" \
-H "Authorization: Bearer gelsinsatislar_live_YOUR_API_KEY" \
-H "Content-Type: application/json"Başarılı yanıt alırsanız, API anahtarınız aktif ve doğru kapsamlara sahip demektir. Artık mesaj gönderme, müşteri yönetimi ve kampanya başlatma uç noktalarını kullanabilirsiniz.
Temel Kavramlar
API'yı etkin bir şekilde kullanabilmek için aşağıdaki kavramları tanımanız önerilir:
Uç Nokta (Endpoint)
Her API operasyonunun erişildiği belirli bir URL adresi. Örneğin /api/v1/messages mesaj gönderme uç noktasıdır.
API Anahtarı (Bearer Token)
İsteklerinizi yetkilendirmek için kullandığınız kimlik bilgisi. Her istekte iletilerek talebin sizden geldiğini doğrular.
JSON
Veri alışverişinde kullanılan standart UTF-8 metin tabanlı format. Tüm istek ve yanıtlar JSON olarak gönderilir ve alınır.
1. Base URL (Temel Adres)
Tüm API istekleri güvenli HTTPS protokolü üzerinden aşağıdaki kök adrese yapılır:
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"API anahtarları 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.
Kapsam (Scope) Referansı
Her API anahtarı yalnızca kendisine atanan kapsam (...) ile çalışır. Gereksiz kapsam vermekten kaçının:
| Kapsam | İzin Verir |
|---|---|
| messages:send | WhatsApp mesajı gönderme |
| messages:read | Mesajları ve iletim durumlarını okuma |
| contacts:read | Müşterileri listeleme ve okuma |
| contacts:write | Müşteri oluşturma ve güncelleme |
| conversations:read | Sohbetleri listeleme ve okuma |
| broadcasts:send | Toplu kampanya başlatma ve kampanya durumunu okuma |
| webhooks:manage | Webhook uç noktalarını yönetme |
2.1 Anahtar Türleri ve Kısıtlamalar
Canlı Anahtar (live)
gelsinsatislar_live_ ile başlar. Gerçek mesaj gönderir, gerçek kayıtları oluşturur ve planınızdaki canlı anahtar kotasını kullanır. Kotadan yalnızca aktif anahtarlar sayılır — iptal ettiğiniz anahtar yerini serbest bırakır.
Test Anahtarı (sandbox)
gelsinsatislar_test_ ile başlar. Okuma uçları gerçek veriyi döner; yazma uçları hiçbir işlem yapmaz, örnek bir yanıt döner (sandbox: true alanı ve X-Gelsinsatislar-Mode: test başlığı). Kotadan sayılmaz; hesap başına en fazla 3 tanedir.
IP Kısıtlaması
Bir anahtarı yalnızca belirli kaynak adreslerden kullanılabilir hale getirebilirsiniz: anahtar oluştururken ya da detay ekranından IP listesine tek adres (203.0.113.4) veya CIDR bloğu (203.0.113.0/24; IPv6 de desteklenir) yazın. Liste boşsa anahtar her adresten çalışır. Liste doluysa listede olmayan bir IP 403 alır ve istemcinin IP'si belirlenemiyorsa istek reddedilir (kapalı devre).
Anahtarın İzlenmesi
Her anahtarın kendi hız sınırı bütçesi vardır (dakikada 120 istek). Aşıldığında 429 ve Retry-After döner. Ayarlar → API anahtarları bölümünde bir anahtara tıklayarak son 30 günün istek, 429 ve 403 sayılarını, günlük dağılımı ve son olayları görebilirsiniz.
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.
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."
}
}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:
| HTTP Kod | Durum | Açıklama |
|---|---|---|
| 200 OK | Başarılı | İstek başarıyla 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 formatına uymayan telefon numarası veya geçersiz JSON gövdesi. |
| 401 Unauthorized | Yetkisiz | Geçersiz API anahtarı veya yetersiz kapsam (scope) erişimi. |
| 429 Too Many Requests | Hız Sınırı Aşımı | Dakikalık istek limitine ulaşıldı. Bir süre bekleyip tekrar deneyin. |
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:
| Hata Kodu | HTTP | Açıklama |
|---|---|---|
| unauthorized | 401 | Eksik, hatalı biçimde yazılmış, bilinmeyen, iptal edilmiş veya süresi dolmuş API anahtarı. |
| forbidden | 403 | Geçerli anahtar ancak gerekli kapsama (scope) sahip değil. |
| rate_limited | 429 | Anahtar başına hız sınırı aşıldı. |
| bad_request | 400 | Geçersiz istek formatı veya eksik parametre. |
| not_found | 404 | Belirtilen kaynak bulunamadı veya farklı bir hesaba ait. |
| internal | 500 | Sunucu tarafı beklenmeyen hata. |
| whatsapp_not_configured | 400 | WhatsApp yapılandırması yapılmamış (yalnızca mesaj gönderme). |
| meta_error | 502 | İstek Meta'ya ulaştı ancak Meta tarafından reddedildi. |
| template_malformed | 500 | Şablon mesaj yapısı hatalı (yalnızca template gönderimleri). |
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.
| Başlık | Açıklama |
|---|---|
| X-RateLimit-Limit | Pencere içinde izin verilen toplam istek sayısı. |
| X-RateLimit-Remaining | Mevcut pencere içinde kalan istek hakkı. |
| X-RateLimit-Reset | Pencerenin sıfırlanacağı Unix zaman damgası (saniye). |
| Retry-After | Yeniden deneme için beklenmesi gereken süre (saniye). Yalnızca 429 yanıtlarında döner. |
{
"data": null,
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded for this API key"
}
}