Bildiro API

Kendi yazılımınızdan, kendi WhatsApp numaranız üzerinden programatik mesaj gönderin. Sipariş onayları, randevu hatırlatmaları, doğrulama kodları ve işlemsel bildirimler için tasarlandı.

Bildiro API, tek bir HTTP isteğiyle WhatsApp mesajı göndermenizi sağlar. Numaranızı bir kez QR ile bağlarsınız, bir API anahtarı üretirsiniz ve yazılımınızdan mesaj tetiklersiniz. Kuyruk beklemeden, saniyeler içinde.

Nasıl Çalışır?

Bildiro, yazılımınız ile WhatsApp arasında bir köprü görevi görür:

Yazılımınız  ──►  api.bildiro.com/v1/messages  ──►  Bildiro motoru  ──►  WhatsApp
   (HTTP isteği)        (API anahtarı ile)         (bağlı numaranız)      (alıcı)

1. Panelden WhatsApp numaranızı QR kodu ile bağlarsınız → bir instance oluşur.
2. Bir API anahtarı (stw_live_...) üretirsiniz.
3. Yazılımınızdan /v1/messages ucuna istek atarsınız.
4. Bildiro, bağladığınız numara üzerinden mesajı iletir.

Hızlı Başlangıç

Bir mesaj göndermek için ihtiyacınız olan her şey tek istekte:

curl -X POST https://api.bildiro.com/v1/messages \
  -H "Authorization: Bearer stw_live_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "abc123def456-1",
    "numara": "905551112233",
    "mesaj": "Siparişiniz hazırlanıyor! 🎉"
  }'

Başarılı yanıt:

{
  "message_id": "3EB08425C66F54B1FC91B6",
  "status": "sent"
}

Kimlik Doğrulama

Tüm API istekleri bir API anahtarı ile kimlik doğrulaması gerektirir. Anahtarınızı panelden API Anahtarları ekranından üretirsiniz.

İki yöntemden biriyle gönderebilirsiniz

# Önerilen: Authorization başlığı
Authorization: Bearer stw_live_ANAHTARINIZ

# Alternatif: X-Api-Key başlığı
X-Api-Key: stw_live_ANAHTARINIZ

Numara (Instance)

Her mesaj, bağladığınız bir WhatsApp numarası (instance) üzerinden gönderilir. instance_id, bu numarayı temsil eden benzersiz kimliktir.

• Numaranızı panelden Numaralar ekranında QR kodu ile bağlarsınız.
• Bağlanınca size bir instance_id verilir (ör. abc123def456-1).
• Bu kimliği mesaj isteklerinizde kullanırsınız.
• Birden çok numara bağlayabilir (paketinize göre) ve her mesajı hangi numaradan göndereceğinizi seçebilirsiniz.

Kota ve Paketler

Her hesabın, seçtiği pakete göre aylık bir mesaj kotası vardır. Kota, canlı anahtarlarla gönderilen mesajlarda düşer.

• Kota aylık dönemler hâlinde hesaplanır (ör. 2026-07).
• Kota dolduğunda, canlı gönderimler 429 kota_asildi hatası döndürür.
• Kalan kotanızı panelden takip edebilirsiniz.
• Test anahtarları (stw_test_) kotadan düşmez — geliştirme sırasında bunları kullanın.

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

Altyapının kararlılığı ve tüm kullanıcılar için adil kullanım amacıyla istekler hız sınırına tabidir. Sınır aşıldığında 429 döner. Aşırı istek atmak yerine, gönderimlerinizi makul aralıklara yayın.

Mesaj Gönder

Bağlı bir numara üzerinden tek bir WhatsApp mesajı gönderir.

İstek Gövdesi (JSON)

Örnek İstek

POST /v1/messages
Authorization: Bearer stw_live_ANAHTARINIZ
Content-Type: application/json

{
  "instance_id": "abc123def456-1",
  "numara": "905551112233",
  "mesaj": "Randevunuz yarın saat 14:00'te. Görüşmek üzere!"
}

Başarılı Yanıt 200

{
  "message_id": "3EB08425C66F54B1FC91B6",
  "status": "sent"
}

Numara Formatı

Numarayı ülke koduyla, başında + veya 0 olmadan, yalnızca rakam olarak gönderin:

Numaraları Listele

Hesabınıza bağlı numaraları (instance) ve bağlantı durumlarını listeler.

GET /v1/instances
Authorization: Bearer stw_live_ANAHTARINIZ

Numara Durumu

Belirli bir numaranın bağlı olup olmadığını döndürür. Mesaj göndermeden önce durumu kontrol etmek için kullanışlıdır.

GET /v1/instance/abc123def456-1/status
Authorization: Bearer stw_live_ANAHTARINIZ

Hesap ve Kota

Hesabınızın paketini, bu dönemki kullanımını, abonelik durumunu ve bağlı numaralarını tek istekte döndürür. Salt okunurdur; kotadan düşmez.

Örnek İstek

curl https://api.bildiro.com/v1/account \
  -H "Authorization: Bearer stw_live_ANAHTARINIZ"

Başarılı Yanıt 200

{
  "hesap": {
    "tenant_id": "abc123def4565f8e9a0b1c2d3e4f5061",
    "ad": "Örnek Ticaret A.Ş.",
    "aktif_mi": true
  },
  "paket": {
    "ad": "Büyüme",
    "limitler": { "kullanici": 3, "mesaj_ay": 3000, "numara": 3 }
  },
  "abonelik": {
    "durum": "aktif",
    "baslangic": "2026-07-19",
    "bitis": "2026-08-19",
    "otomatik_yenile": true
  },
  "donem": {
    "kod": "2026-07",
    "baslangic": "2026-07-01",
    "bitis": "2026-07-31",
    "zaman_dilimi": "Europe/Istanbul"
  },
  "kullanim": {
    "mesaj": { "kullanilan": 2461, "limit": 3000, "kalan": 539, "yuzde": 82 },
    "esik": { "durum": "uyari", "uyari_yuzde": 80, "uyari_asildi": true, "doldu": false },
    "numara": { "kullanilan": 2, "limit": 3 }
  },
  "numaralar": [
    { "instance_id": "abc123def456-1", "durum": "connected", "numara": "905321112233" },
    { "instance_id": "abc123def456-2", "durum": "disconnected" }
  ],
  "veri_kismi": false
}

Alanlar

Örnek: PHP — göndermeden önce kotayı kontrol et

<?php
$ch = curl_init('https://api.bildiro.com/v1/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $anahtar],
    CURLOPT_TIMEOUT        => 10,
]);
$hesap = json_decode(curl_exec($ch), true);
curl_close($ch);

$esik = $hesap['kullanim']['esik']['durum'];

if ($esik === 'doldu') {
    // Kota bitti: göndermeyi denemek 429 üretir. Kuyruğu beklet, operatörü uyar.
    throw new RuntimeException('Aylık mesaj kotası doldu.');
}

if ($esik === 'uyari') {
    error_log(sprintf(
        'Bildiro kotası %%%d — %d mesaj kaldı (dönem %s).',
        $hesap['kullanim']['mesaj']['yuzde'],
        $hesap['kullanim']['mesaj']['kalan'],
        $hesap['donem']['kod']
    ));
}

Örnek: Node.js

const yanit = await fetch('https://api.bildiro.com/v1/account', {
  headers: { Authorization: `Bearer ${anahtar}` }
});
const hesap = await yanit.json();

const { kullanilan, limit, kalan } = hesap.kullanim.mesaj;
console.log(`${hesap.paket?.ad ?? 'Paket yok'} — ${kullanilan}/${limit || '∞'} (kalan: ${kalan ?? '∞'})`);

// Bağlı olmayan numaraya göndermek 503 üretir; önce eleyin.
const hazirNumaralar = hesap.numaralar.filter(n => n.durum === 'connected');
if (hazirNumaralar.length === 0) {
  throw new Error('Bağlı numara yok — panelden QR ile bağlayın.');
}

if (hesap.kullanim.esik.doldu) {
  throw new Error('Kota doldu, gönderim durduruldu.');
}

Webhook — Genel Bakış

Mesajınız teslim edildiğinde, okunduğunda veya numaranıza cevap geldiğinde Bildiro sizin adresinize imzalı bir POST isteği gönderir. Sürekli sormanız (polling) gerekmez.

• Panelde Webhook ekranından adresinizi kaydeder, hangi olayları istediğinizi seçersiniz.
• Kayıt sırasında bir imza sırrı (whsec_…) üretilir — yalnız bir kez gösterilir.
• Her istek X-Bildiro-Imza başlığıyla imzalanır; doğrulamak zorundasınız.
• Başarısız teslimatlar üstel geri çekilmeyle tekrar denenir, panelde teslimat geçmişini görürsünüz.

İstek Başlıkları

Zarf

Her olay aynı dış yapıyla gelir; olaya özgü alanlar veri içindedir.

{
  "surum": "v1",
  "event_id": "evt_00112233445566778899aabbccddeeff",
  "olay": "message.delivered",
  "zaman": "2026-07-27T09:14:22Z",
  "tenant_id": "abc123def4565f8e9a0b1c2d3e4f5061",
  "veri": { /* olaya özgü — aşağıda */ }
}

Olaylar ve Gövdeler

Gelen mesaj (message.received)

Müşterinizin yanıtı bu olayla düşer — otomatik yanıt, destek akışı ve onay/ret toplama bunun üzerine kurulur.

{
  "surum": "v1",
  "event_id": "evt_9f2c1d0e7b5a4839c6d2e1f0a3b4c5d6",
  "olay": "message.received",
  "zaman": "2026-07-27T09:15:03Z",
  "tenant_id": "abc123def4565f8e9a0b1c2d3e4f5061",
  "veri": {
    "instance_id": "abc123def456-1",
    "message_id": "3EB0F1A2B3C4D5E6",
    "numara": "905551112233",
    "mesaj": "Evet, randevuyu onaylıyorum"
  }
}

Grup ve yayın (broadcast) mesajları gönderilmez; medya mesajları şimdilik kapsam dışıdır (yalnız metin).

Teslim durumu (message.delivered / message.read)

{
  "surum": "v1",
  "event_id": "evt_5a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "olay": "message.delivered",
  "zaman": "2026-07-27T09:14:22Z",
  "tenant_id": "abc123def4565f8e9a0b1c2d3e4f5061",
  "veri": {
    "instance_id": "abc123def456-1",
    "message_id": "3EB08425C66F54B1FC91B6",
    "durum": "delivered"
  }
}

message_id, POST /v1/messages yanıtında aldığınız kimliktir — kendi kaydınızla bu alandan eşleştirin.

İmza Doğrulama

İmza şu şekilde üretilir:

imza_tabani = "{X-Bildiro-Zaman}" + "." + {ham_govde}
imza        = "v1=" + HMAC_SHA256(imza_tabani, imza_sirriniz)   // hex

Zaman damgası imza tabanına dahildir: bu sayede eski bir gövde yeni bir zaman damgasıyla tekrar oynatılamaz. Kabul penceresi olarak ±300 saniye önerilir.

Örnek: PHP

<?php
$sir   = getenv('BILDIRO_WEBHOOK_SIRRI');   // panelden aldığınız whsec_… değeri
$govde = file_get_contents('php://input');  // HAM gövde — yeniden kodlamayın
$imza  = $_SERVER['HTTP_X_BILDIRO_IMZA'] ?? '';
$zaman = (int) ($_SERVER['HTTP_X_BILDIRO_ZAMAN'] ?? 0);

// 1) Replay koruması
if ($zaman <= 0 || abs(time() - $zaman) > 300) {
    http_response_code(400);
    exit;
}

// 2) İmza — hash_equals SABİT ZAMANLIDIR, '==' kullanmayın
$beklenen = 'v1=' . hash_hmac('sha256', $zaman . '.' . $govde, $sir);
if (!hash_equals($beklenen, $imza)) {
    http_response_code(401);
    exit;
}

$olay = json_decode($govde, true);

// 3) Idempotency: aynı olay iki kez gelebilir
if (zaten_islendi($olay['event_id'])) {
    http_response_code(200);
    exit;
}

// 4) Önce yanıt, sonra iş
http_response_code(200);
fastcgi_finish_request();
isle($olay);

Örnek: Node.js (Express)

const crypto = require('crypto');

// DİKKAT: express.json() ham baytı atar — webhook yolunda express.raw kullanın.
app.post('/bildiro/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sir   = process.env.BILDIRO_WEBHOOK_SIRRI;
  const govde = req.body;                          // Buffer — HAM gövde
  const imza  = req.get('X-Bildiro-Imza') || '';
  const zaman = parseInt(req.get('X-Bildiro-Zaman') || '0', 10);

  if (!zaman || Math.abs(Date.now() / 1000 - zaman) > 300) return res.sendStatus(400);

  const beklenen = 'v1=' + crypto.createHmac('sha256', sir)
    .update(zaman + '.' + govde.toString('utf8'), 'utf8')
    .digest('hex');

  const a = Buffer.from(beklenen);
  const b = Buffer.from(imza);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const olay = JSON.parse(govde.toString('utf8'));

  res.sendStatus(200);                              // önce yanıt
  isle(olay).catch(console.error);                 // sonra iş
});

Örnek: Python (Flask)

import hmac, hashlib, time, os
from flask import request, abort

sir = os.environ['BILDIRO_WEBHOOK_SIRRI'].encode()

@app.post('/bildiro/webhook')
def webhook():
    govde = request.get_data()                      # HAM gövde (bytes)
    imza  = request.headers.get('X-Bildiro-Imza', '')
    zaman = int(request.headers.get('X-Bildiro-Zaman', '0'))

    if not zaman or abs(time.time() - zaman) > 300:
        abort(400)

    taban    = f'{zaman}.'.encode() + govde
    beklenen = 'v1=' + hmac.new(sir, taban, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(beklenen, imza):
        abort(401)

    olay = request.get_json()
    # olay['event_id'] daha önce işlendiyse atla, sonra 200 dön
    return '', 200

Tekrar Deneme ve Idempotency

2xx dışında bir yanıt veya ağ hatası aldığımızda teslimatı üstel geri çekilmeyle tekrar deneriz:

6. deneme de başarısızsa olay ölü mektup olur. Panelin Webhook → Son Teslimatlar tablosundan gövdesiyle birlikte görür ve Yeniden Dene ile elle gönderebilirsiniz.

• Zaman damgası her denemede tazelenir (eski damga replay penceresine takılırdı), ancak event_id değişmez.
• Bir uç uzun süre yanıt vermezse kuyruğunuz sınırlanır; en eski olaylar ölü mektuba düşer ve panelde görünür.
• Sırrınızı yenilediğinizde eski sır anında geçersizdir; yeni sırrı alıcı tarafınıza yerleştirene kadar imza doğrulamanız başarısız olur.

Hata Kodları

Bildiro standart HTTP durum kodları kullanır. Hatalı yanıtlar bir error alanı içerir.

Örnek Hata Yanıtı

{
  "error": "kota_asildi",
  "mesaj": "Aylık mesaj kotanız doldu."
}

Tekrar Denemeler

• 429 (hız limiti) aldığınızda kısa bir bekleme (ör. üstel geri çekilme: 2, 4, 8 sn) ile tekrar deneyin.
• 429 (kota) aldığınızda tekrar denemek işe yaramaz — kota yenilenene kadar bekleyin veya paket yükseltin.
• Aynı mesajı çok kez göndermemeye dikkat edin; tekrar denemeden önce önceki yanıtı kontrol edin.

Örnek: PHP

<?php
$ch = curl_init('https://api.bildiro.com/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer stw_live_ANAHTARINIZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'instance_id' => 'abc123def456-1',
        'numara'      => '905551112233',
        'mesaj'       => 'Siparişiniz kargoya verildi 📦',
    ]),
]);
$yanit = curl_exec($ch);
$kod   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($kod === 200) {
    $veri = json_decode($yanit, true);
    echo "Gönderildi: " . $veri['message_id'];
} else {
    echo "Hata ($kod): " . $yanit;
}

Örnek: Node.js

const yanit = await fetch('https://api.bildiro.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer stw_live_ANAHTARINIZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    instance_id: 'abc123def456-1',
    numara: '905551112233',
    mesaj: 'Doğrulama kodunuz: 482913',
  }),
});

const veri = await yanit.json();
if (yanit.ok) {
  console.log('Gönderildi:', veri.message_id);
} else {
  console.error('Hata:', yanit.status, veri.error);
}

Örnek: Python

import requests

yanit = requests.post(
    'https://api.bildiro.com/v1/messages',
    headers={
        'Authorization': 'Bearer stw_live_ANAHTARINIZ',
        'Content-Type': 'application/json',
    },
    json={
        'instance_id': 'abc123def456-1',
        'numara': '905551112233',
        'mesaj': 'Randevunuz onaylandı ✅',
    },
)

if yanit.status_code == 200:
    print('Gönderildi:', yanit.json()['message_id'])
else:
    print('Hata:', yanit.status_code, yanit.text)

Güvenli ve Sağlıklı Kullanım

Bildiro, WhatsApp'ın resmî Business API'sini değil, çok cihazlı web protokolünü kullanan bir bağlantı yöntemine dayanır. Numaranızın sağlığını korumak için:

• İşlemsel kalın. Sipariş, randevu, doğrulama gibi kullanıcı eylemine bağlı mesajlar gönderin. Onaysız toplu pazarlama, numara engellenme riskini ciddi artırır.
• Kademeli başlayın. Yeni bağlanan bir numarayla ilk günlerde düşük hacimle başlayıp zamanla artırın (ısınma).
• Onaylı alıcılara gönderin. Mesaj göndereceğiniz kişilerin onayını almış olun. Bu hem yasal bir yükümlülüktür (6563 sayılı Kanun, İYS) hem de spam şikayetlerini azaltır.
• Makul hız kullanın. Ani ve yoğun gönderim yerine doğal bir ritim tutun.
• Anahtarınızı koruyun. API anahtarını sunucu tarafında saklayın, istemciye göndermeyin.

Sık Sorulan Sorular

API anahtarımı nasıl alırım?

Panele giriş yapın → önce Numaralar ekranından WhatsApp numaranızı QR ile bağlayın → sonra API Anahtarları ekranından bir canlı anahtar üretin. Anahtar yalnızca bir kez gösterilir, güvenli saklayın.

instance_id'yi nereden bulurum?

Numaranızı bağladığınızda panelin Numaralar ekranında görünür. Programatik olarak GET /v1/instances ile de listeleyebilirsiniz.

Test ederken kotam düşer mi?

Hayır. stw_test_ ile başlayan test anahtarlarıyla yaptığınız gönderimler kotadan düşmez. Geliştirme sırasında test anahtarını kullanın, canlıya geçince stw_live_ anahtarına geçin.

Medya (resim, dosya) gönderebilir miyim?

Şu an API metin mesajı gönderimini destekler. Medya desteği yol haritamızdadır; güncellemeler için bu dokümanı takip edin.

Mesajım gitmedi, ne yapmalıyım?

Yanıttaki HTTP kodunu ve error alanını kontrol edin. instance_not_connected ise numaranızı panelden yeniden bağlayın; kota_asildi ise kotanız dolmuştur; yetkisiz ise anahtarınızı kontrol edin. Sorun sürerse destek@bildiro.com.

Numaram engellenirse ne olur?

Bu yönteme özgü bir risktir. Numaranız WhatsApp tarafından kısıtlanırsa gönderim yapılamaz. Riski azaltmak için işlemsel kullanım, onaylı alıcı listesi ve makul hacim önerilir. Ayrıntı için Kullanıcı Sözleşmesi'ni inceleyin.

Sorularınız için destek@bildiro.com · Bu doküman bildiro.com/docs adresinde güncel tutulur.