API v2

API v2, yeni WbizTool REST API'sidir: her uygulama için yalnızca ihtiyaç duyduğu erişime sahip tek bir anahtar, kaynak tarzı URL'ler, gerçek HTTP durum kodları, imzalı JSON webhook'ları ve güvenli yeniden denemeler. Bu sayfa her istekte ortak olanları anlatır. Her endpoint kaynak sayfalarında açıklanır.

Temel URL#

https://wbiztool.com/api/v2

Yollar sonda eğik çizgi olmadan yazılır (/api/v2/messages), ancak sonda eğik çizgi de kabul edilir. Var olmayan bir adres 404 ve not_found koduyla yanıt verir.

Hızlı örnek#

Anahtarınızı GET /me ile kontrol edin. Her kapsamla çalışır ve hiçbir şey göndermez:

curl https://wbiztool.com/api/v2/me \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

import os
import requests

response = requests.get(
    "https://wbiztool.com/api/v2/me",
    headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/me", {
  headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
console.log(response.status, await response.json());

<?php
$ch = curl_init('https://wbiztool.com/api/v2/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$body = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n";
print_r($body);
curl_close($ch);

{
  "workspace": { "id": 5012, "name": "Acme Bakery" },
  "key": {
    "id": 7,
    "name": "Order system",
    "mode": "live",
    "scopes": ["messages:send", "messages:read"],
    "limited_to_numbers": false,
    "number_ids": [],
    "expires_at": null
  },
  "plan": { "name": "Starter" },
  "limits": {
    "requests_per_minute": 60,
    "requests_per_day": 10000,
    "messages_per_number_per_day": 1000,
    "messages_remaining": null
  }
}

Plan sınırsız mesaj gönderiyorsa messages_remaining değeri null olur. Çalışma alanının etkin bir planı yoksa plan değeri null olur.

Anahtarlar#

Anahtarınızı her istekte Authorization başlığında gönderin:

Authorization: Bearer wbz_live_…

client_id yoktur: anahtar kendi çalışma alanını belirtir. Bir v2 anahtarı wbz_live_ veya wbz_test_ ile başlar ve ardından 38 harf ve rakam gelir. v1 anahtarları v2'de çalışmaz (v1_key_on_v2 alırlar), v2 anahtarları da v1'de çalışmaz.

Anahtar oluşturun#

Sahipler anahtarları Ayarlar → API anahtarları sayfasındaki API v2 anahtarları kartında oluşturur: v2 anahtarı oluştur'a tıklayın, ardından şunları seçin:

• Ad: anahtarı kullanacak uygulama, en fazla 50 karakter.
• Anahtar türü: Canlı gerçek mesajlar gönderir; Test her şeyi kontrol eder ve hiçbir şey göndermez (bkz. Test modu).
• Neler yapabilir: kapsamlar veya Her şey.
• Kullanabileceği numaralar: sonradan eklenenler dahil tüm numaralar veya yalnızca bazıları (bkz. Bazı numaralarla sınırlı anahtarlar).
• Geçerlilik süresi: süresiz veya 30 gün, 90 gün ya da 1 yıl.

Anahtar yalnızca bir kez gösterilir. Hemen kopyalayın ve sunucunuzda, örneğin bir ortam değişkeninde saklayın. WbizTool anahtarın yalnızca bir hash'ini ve son dört karakterini saklar; bu yüzden kaybolan bir anahtar yeniden gösterilemez: onu iptal edin ve yeni bir anahtar oluşturun.

Bir çalışma alanında iptal edilmemiş en fazla 10 v2 anahtarı olabilir. Kart her anahtarın son dört karakterini, kapsamlarını, numaralarını, bitiş tarihini ve en son ne zaman ve hangi IP adresinden kullanıldığını gösterir. İptal et bir anahtarı ve onun oluşturduğu webhook uç noktalarını hemen durdurur. Bitiş tarihi geçmiş bir anahtar api_key_expired alır.

Kapsamlar#

Her anahtar yalnızca kapsamlarının izin verdiği işlemleri yapabilir. Bunların dışındaki bir istek 403 ve missing_scope ile yanıt verir; hatadaki required_scope hangi kapsamın gerektiğini söyler.

GET /me belirli bir kapsam gerektirmez. Kayıtlı bir kişiye to.contact_id ile göndermek için yalnızca messages:send gerekir.

Bazı numaralarla sınırlı anahtarlar#

Bazı numaralarla sınırlı bir anahtar yalnızca bu numaralarla çalışır:

• Yalnızca bu numaralardan gönderir ve yalnızca onların mesajlarını listeler, okur ve iptal eder. from içindeki başka bir numara number_not_allowed alır.
• GET /numbers yalnızca bu numaraları listeler. Anahtar onları yeniden bağlayabilir, ancak yeni bir numara ekleyemez.
• Yalnızca bu numaralardan gönderen hatırlatıcıları görür ve değiştirir; yeni bir hatırlatıcı da from olarak bunlardan birini belirtmelidir.
• Webhook uç noktalarını hiç yönetemez, çünkü uç noktalar tüm çalışma alanının olaylarını alır.

GET /me, limited_to_numbers değerini ve anahtarın kullanabileceği number_ids listesini gösterir.

İstekler#

• Giriş ve çıkış JSON'dur. Gövdeleri Content-Type: application/json olarak gönderin. Tek istisna, multipart/form-data kullanan dosya yüklemedir. Hatalar dahil her yanıt JSON'dur.
• Alan adları snake_case biçimindedir ve bilinmeyen alanlar reddedilir: txt gibi bir yazım hatası yok sayılmak yerine validation_failed ile yanıt verir.
• Telefon numaraları + ile uluslararası biçimdedir (E.164), örneğin +919876543210. Boşluklara ve tirelere izin verilir; + olmadan yazılan bir numara invalid_phone ile reddedilir.
• Zamanlar fark (offset) içeren ISO 8601 biçimindedir, örneğin 2026-10-20T09:30:00+05:30 veya 2026-10-20T04:00:00Z. Farkı olmayan bir zaman invalid_datetime ile reddedilir. Yanıtlardaki zamanlar UTC'dir ve Z ile biter; tek istisna, hatırlatıcının kendi saat diliminde verilen next_run_at değeridir.
• ID'ler tam sayıdır, örneğin bir numaranın id değeri (gönderirken from) veya bir mesajın id değeri.
• Durum kodları söyledikleri anlama gelir: 200 tamam, 201 oluşturuldu, 202 kabul edildi (kuyruğa alındı), 400 istek yanlış, 401 anahtar yanlış, 402 mesaj kalmadı, 403 izin yok, 404 bulunamadı, 409 çakışma, 413 çok büyük, 415 yanlış içerik türü, 422 bir değer kullanılamıyor, 429 çok fazla istek, 5xx bizim tarafımız.

Yanıtlar Cache-Control: no-store taşır.

Hatalar#

Her hatanın biçimi aynıdır:

{
  "error": {
    "code": "invalid_phone",
    "message": "This is not a valid phone number. Write it in international format with +, e.g. +919876543210.",
    "field": "to.phone",
    "docs": "https://wbiztool.com/docs/api/v2/errors/#invalid_phone",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817"
  }
}

• code sabittir: kodunuzda ona göre dallanın. message geliştirici için İngilizce bir metindir ve değişebilir.
• field, hatanın ilgili olduğu alanı belirtir (to.phone, to[3].phone, schedule.cron) veya null olur.
• docs, hatalar sayfasındaki koda bağlantı verir.
• request_id, X-Request-Id başlığıyla aynıdır. Bizimle iletişime geçerseniz bunu belirtin.
• Bazı hatalar ek ayrıntılar içerir; örneğin not_cancellable hatasında status, storage_full hatasında used ve limit. Bir istekte birden fazla sorun varsa errors diğerlerini, her biri field ve message ile listeler.

Her kod, HTTP durumu ve ne yapmanız gerektiği hatalar sayfasındadır.

Idempotency-Key#

Bir ağ hatası veya zaman aşımı, isteğin işe yarayıp yaramadığından emin olmamanıza yol açar. Bir şey oluşturan POST isteğiyle bir Idempotency-Key başlığı gönderirseniz isteği güvenle yeniden gönderebilirsiniz:

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{"to": {"phone": "+919876543210"}, "text": "Hi Asha, your order #1042 is ready."}'

• Değeri siz belirlersiniz: 1 ile 255 arasında yazdırılabilir karakterden oluşan benzersiz herhangi bir dize; örneğin bir UUID veya kendi sipariş ID'niz. Her yeni istek için yeni bir değer oluşturun ve bir değeri yalnızca aynı isteğin yeniden denemesi için tekrar kullanın.
• Yeniden deneme ilk yanıtı geri alır ve Idempotent-Replayed: true başlığını taşır. Hiçbir şey iki kez yapılmaz: ikinci bir mesaj, hatırlatıcı, dosya veya uç nokta oluşmaz.
• Anahtarlar ilk istekten itibaren 24 saat geçerlidir ve API anahtarınıza aittir: çalışma alanının başka bir API anahtarı aynı değeri çakışma olmadan kullanabilir.
• Aynı anahtar, farklı istek: daha önce farklı bir yöntem, yol veya gövde için kullanılmış bir anahtarla gelen istek 422 idempotency_key_reused ile yanıt verir.
• Hâlâ işleniyor: anahtarla gelen ilk istek hâlâ işlenirken yapılan bir yeniden deneme Retry-After: 1 ile 409 idempotency_in_progress yanıtını verir. Biraz bekleyin ve yeniden gönderin.
• Hatalar saklanmaz. İlk istek bir hatayla yanıt verdiyse hiçbir şey saklanmaz: isteği düzeltin ve aynı anahtarla yeniden gönderin.
• Gizli anahtarlar tekrar gösterilmez. POST /webhooks isteğinin tekrarı, uç noktanın yalnızca ilk yanıtta gösterilen secret değerini içermez.

POST /messages, POST /messages/batch, POST /numbers, POST /reminders, POST /media, POST /number-checks ve POST /webhooks üzerinde çalışır ve hepsinde isteğe bağlıdır. Diğer istekler başlığı yok sayar. Boş veya çok uzun bir değer 400 invalid_idempotency_key ile yanıt verir.

Hız sınırları#

Her anahtar dakikada 60 istek ve günde 10.000 istek yapabilir. Bunlar sabit pencerelerdir: dakika penceresi saatteki dakika başında, gün penceresi 00:00 UTC'de başlar. Sınır aşıldığında istek 429 rate_limited ile yanıt verir.

Geçerli bir anahtarla yapılan isteklerin yanıtları şu başlıkları taşır:

Bunlardan ayrı olarak:

• Yanlış anahtarlar: tek bir IP adresinden yanlış anahtarla dakikada 30'dan fazla istek, Retry-After: 60 ile 429 too_many_auth_failures yanıtını alır.
• Numara başına mesajlar: bir numara 24 saatte en fazla 1.000 mesaj gönderir (adil kullanım). Bunu aşan bir gönderim 429 number_daily_cap_reached ile yanıt verir.

Sayfalama#

Büyüyebilen listeler (GET /messages, /reminders, /media, /number-checks ve bir kontrolün /results listesi) en yeniden başlayarak sayfalar halinde gelir:

{
  "data": [ … ],
  "next_cursor": "eyJpZCI6OTgxNzI2MywidCI6IjIwMjYtMTAtMThUMTA6MTU6MDIuMzExWiIsImYiOiI0NGIxMzZmYTM1NWIifQ"
}

• limit sayfa boyutunu belirler; 1 ile 100 arasında (varsayılan 25).
• Sonraki sayfayı almak için aynı isteği, cursor değerini önceki sayfanın next_cursor değerine ayarlayarak gönderin. Son sayfada next_cursor değeri null olur.
• Diğer filtreleri aynı tutun: farklı filtrelerle kullanılan bir cursor 400 invalid_cursor ile yanıt verir. Cursor olmadan baştan başlayın.
• Cursor'ı içeriği anlamsız bir dize olarak ele alın. Siz sayfalar arasında gezinirken eklenen öğeler sayfaları kaydırmaz.

curl "https://wbiztool.com/api/v2/messages?limit=100&cursor=eyJpZCI6OTgxNzI2MywidCI6..." \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

GET /numbers ve GET /webhooks her şeyi tek bir data listesinde döndürür.

İstek ID'leri#

Hatalar dahil her yanıtta req_4f1c2a9b8e7d6c5b4a392817 gibi bir X-Request-Id başlığı bulunur. Hatalar aynı değeri request_id olarak taşır. Bunu kaydedin ve bizimle iletişime geçerseniz belirtin: isteği, anahtarınızın kendisini değil yalnızca ID'sini kaydeden günlüklerimizde bulmamızı sağlar.

Kendi X-Request-Id değerinizi gönderirseniz (en fazla 100 yazdırılabilir karakter), bu değer X-Client-Request-Id olarak geri gelir; böylece yanıtları kendi günlüklerinizle eşleştirebilirsiniz.

Test modu#

Bir test anahtarı (wbz_test_…), hiçbir şey göndermeden bir entegrasyon geliştirmenizi ve test etmenizi sağlar. Ayarlar → API anahtarları sayfasında Anahtar türü: Test seçerek bir tane oluşturun. GET /me, "mode": "test" gösterir.

Bir test anahtarının canlı anahtar gibi yaptıkları:

• POST /messages ve POST /messages/batch, canlı bir gönderimin kontrol ettiği her şeyi kontrol eder: alıcı, metin, medya, send_at ve expires_at, gönderen numara ile anahtarın kapsamları ve numaraları. Aynı hatalar aynı hata yanıtlarını alır.
• Kapsamlar, numaralar, hız sınırları ve Idempotency-Key aynı şekilde çalışır.
• Çalışma alanının geri kalanındaki her okuma (GET /me, /numbers, /reminders, /media, /number-checks, /webhooks) gerçek verileri salt okunur olarak gösterir.

Farklı olanlar:

• Hiçbir şey gönderilmez. Bir test gönderimi bunun yerine test mesajı olarak saklanır ve planın mesajlarını veya numaranın günlük 1.000 mesajını kullanmaz; bu yüzden hiçbir zaman no_credits veya number_daily_cap_reached almaz.
• Durumu kendiliğinden ilerler: önce queued, oluşturulduktan 5 saniye sonra sent ve 15 saniye sonra delivered (zamanlanmış bir mesajda send_at zamanından itibaren sayılır). expires_at zamanı gönderilmesinden önce gelen bir mesaj expired olur. Test mesajları hiçbir zaman read veya failed olmaz.
• Bir test anahtarı yalnızca kendi test mesajlarını görür. GET /messages ve GET /messages/{id} yalnızca onları gösterir; DELETE /messages/{id} ise bir test mesajını queued veya scheduled durumundayken iptal eder. Canlı anahtarlar test mesajlarını hiçbir zaman görmez. GET /messages isteğinin status filtresi test anahtarlarında desteklenmez ve test_mode_unsupported ile yanıt verir; number, since ve until çalışır.
• Diğer yazma işlemleri 403 test_mode_unsupported ile reddedilir: numara bağlamak, hatırlatıcı oluşturmak, değiştirmek veya silmek, medya yüklemek veya silmek, numara kontrolü başlatmak ve webhook uç noktası eklemek, kaldırmak, gizli anahtarını yenilemek veya test etmek.
• Test mesajları için webhook olayı gönderilmez.
• Test mesajları 30 gün saklanır.

Kaynaklar#

• Mesajlar: şimdi veya daha sonra gönderin, en fazla 1.000 alıcıya gönderin, geçmişi okuyun, iptal edin.
• Numaralar: WhatsApp numaralarınızı ve Telegram hesaplarınızı listeleyin, bir WhatsApp numarasını QR kodla veya eşleştirme koduyla bağlayın.
• Hatırlatıcılar: cron zamanlamasına göre tekrarlanan mesajlar.
• Medya: dosyaları bir kez yükleyin ve media_id ile gönderin.
• Numara kontrolleri: hangi numaraların WhatsApp'ta olduğunu öğrenin.
• Webhook'lar: bir mesaj gönderildiğinde, başarısız olduğunda, iptal edildiğinde veya süresi dolduğunda imzalı olaylar.
• Hatalar: tüm hata kodları.
• v1'den v2'ye geçiş: her v1 endpoint'i ve alanı ile v2'deki karşılığı.