API rehberleri
Uç nokta başvurusundan farklı olarak bu sayfa, sık yapılan işleri baştan sona anlatır. Örneklerde gelsinsatislar_test_ anahtarı kullanın: okuma uçları gerçek veriyi döner, yazma uçları simüle edilir.
1. İlk isteğiniz: anahtarı doğrulayın
Ayarlar → API anahtarları bölümünden bir anahtar oluşturun. GET /api/v1/me uç noktası kapsam gerektirmez; anahtarın bağlı olduğu hesabı ve taşıdığı kapsamları döner. Entegrasyonunuzun ilk adımı olarak bunu çağırarak anahtarın geçerli ve beklediğiniz kapsamlarda olduğunu doğrulayın.
curl "https://gelsinsatislar.com/api/v1/me" \
-H "Authorization: Bearer $GELSINSATISLAR_API_KEY"Anahtarı kaynak koduna yazmayın; ortam değişkeninde tutun. 401 alırsanız anahtar geçersiz ya da iptal edilmiştir, 403 alırsanız çağırdığınız uç nokta için gerekli kapsam anahtarda yoktur.
2. WhatsApp mesajı gönderme
POST /api/v1/messages için messages:send kapsamı gerekir. WhatsApp kuralı gereği müşterinin son mesajından sonraki 24 saat içinde serbest metin (type: "text") gönderebilirsiniz. Pencere dışında yalnızca Meta onaylı şablon (type: "template") gönderilir.
curl -X POST "https://gelsinsatislar.com/api/v1/messages" \
-H "Authorization: Bearer $GELSINSATISLAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "+905000000000", "type": "text", "text": "Siparişiniz kargoya verildi." }'Telefon numaralarını uluslararası biçimde (+90…) gönderin. Başarılı gönderim 201 döner; teslim durumu (sent, delivered, read) için message.status_updated webhook olayına abone olun (bkz. 5. bölüm).
3. Kişileri kendi sisteminizle eşitleme
POST /api/v1/contacts telefona göre kişiyi bulur ya da oluşturur: kişi varsa 200, yeniyse 201 döner. Bu yüzden aynı isteği tekrar göndermek güvenlidir. Etiketleri değiştirmek için PATCH /api/v1/contacts/{id} kullanın; tags gönderdiğinizde mevcut etiketlerin yerine geçer.
const res = await fetch("https://gelsinsatislar.com/api/v1/contacts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GELSINSATISLAR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ phone: "+905000000000", name: "Örnek Kişi", tags: ["toptan"] }),
});
const { data } = await res.json(); // res.status: 200 = mevcut, 201 = yeniİmleç (cursor) opak bir değerdir; yorumlamayın, olduğu gibi bir sonraki isteğe verin. Kişi silmek (DELETE) ilişkili sohbetleri ve mesajları da kalıcı olarak siler.
4. Toplu mesaj başlatma ve izleme
POST /api/v1/broadcasts en fazla 1.000 alıcıya onaylı bir şablonu asenkron gönderir ve 202 ile kampanya kaydını döner. Gönderim arka planda sürer; ilerlemeyi GET /api/v1/broadcasts/{id} ile sorgulayın. Her iki uç da broadcasts:send kapsamı ister.
const headers = {
Authorization: `Bearer ${process.env.GELSINSATISLAR_API_KEY}`,
"Content-Type": "application/json",
};
const start = await fetch("https://gelsinsatislar.com/api/v1/broadcasts", {
method: "POST",
headers,
body: JSON.stringify({
name: "Kasım kampanyası",
template_name: "kampanya_duyuru",
template_language: "tr",
recipients: [{ to: "+905000000000", params: ["%20"] }],
}),
});
const { data: broadcast } = await start.json();
let status = broadcast.status;
while (status !== "completed") {
await new Promise((r) => setTimeout(r, 5000));
const res = await fetch(`https://gelsinsatislar.com/api/v1/broadcasts/${broadcast.id}`, { headers });
status = (await res.json()).data.status;
}Sorgulamayı birkaç saniyede bir yapın; oran sınırı (dakikada 120 istek) aşılırsa 429 ve Retry-After başlığı döner. Alıcı listesi 1.000'i aşarsa listeyi parçalara bölüp birden fazla kampanya başlatın. Durum alanının tüm değerleri için Toplu Mesaj API sayfasına bakın.
5. Webhook alıcısı yazma
Olayları anlık almak için POST /api/v1/webhooks ile HTTPS adresinizi ve dinlenecek olayları kaydedin (webhooks:manage kapsamı). İmza sırrı (secret) yalnızca kayıt yanıtında bir kez gösterilir; güvenli bir yerde saklayın.
Alıcınızda üç kural uygulayın: (1) imzayı ham gövde üzerinden doğrulayın, JSON ayrıştırıp yeniden serileştirmeyin; (2) id alanını saklayıp aynı olayı bir kereden fazla işlemeyin, çünkü yeniden denemeler aynı olayı tekrar teslim eder; (3) hızlıca 2xx dönün, ağır işi kuyruğa alın. Başarısız teslimatlar 1, 2, 4, 8 ve 16 dakika arayla yeniden denenir; 15 ardışık hatada uç nokta otomatik devre dışı kalır (tekrar etkinleştirmek için PATCH ile is_active: true gönderin).
import express from "express";
import crypto from "node:crypto";
const app = express();
const SECRET = process.env.GELSINSATISLAR_WEBHOOK_SECRET;
const seen = new Set(); // üretimde kalıcı bir depo (Redis, veritabanı) kullanın
function verify(rawBody, header) {
const m = /t=(\d+),v1=([0-9a-f]+)/.exec(header ?? "");
if (!m) return false;
const [, t, v1] = m;
// Öneri: çok eski zaman damgalarını reddedin (tekrar saldırısına karşı)
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", SECRET).update(t + "." + rawBody).digest("hex");
return v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
// Ham gövde için express.raw kullanın (express.json DEĞİL)
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const raw = req.body.toString("utf8");
if (!verify(raw, req.get("X-Gelsinsatislar-Signature"))) return res.sendStatus(401);
const event = JSON.parse(raw);
if (seen.has(event.id)) return res.sendStatus(200); // tekrar teslim
seen.add(event.id);
// event.event: "message.received", "lead.stage_changed", ...
// Ağır işi kuyruğa alın, burada hızlıca yanıt verin
res.sendStatus(200);
});
app.listen(3000);Tüm olay türleri ve yük alanları için Webhooks sayfasındaki olay kataloğuna bakın.
6. Sipariş, satış ve ödeme olaylarını kendi sisteminize aktarma
ikas, Shopify gibi mağaza entegrasyonları panelden bağlanır (bkz. Entegrasyonlar). Kendi sisteminizi (ERP, muhasebe, BI) satış sürecine bağlamak için şu olaylara abone olun: lead.created ve lead.stage_changed (satış kartı açıldığında ve aşama değiştiğinde), order.created (bir entegrasyon siparişi bir satışa bağlandığında) ve payment.completed (doğrulanmış ödeme tamamlandığında).
curl -X POST "https://gelsinsatislar.com/api/v1/webhooks" \
-H "Authorization: Bearer $GELSINSATISLAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://sistemim.example.com/webhook",
"events": ["lead.created", "lead.stage_changed", "order.created", "payment.completed"]
}'Olay yükleri yalnızca belirlenmiş alanları taşır (ör. lead_id, stage_id, amount); dahili özetler, token'lar ve ödeme bağlantıları yüke eklenmez. Ek ayrıntıya ihtiyacınız olursa olay yükündeki kimlikle GET /api/v1/contacts/{id} gibi okuma uçlarını çağırın.