İçeriğe geç
Veri MerkeziVeri MerkeziAPI

API referansı

CTWA Dönüşümleri

Click-to-WhatsApp (CTWA) reklamlarından gelen satış/dönüşümleri Meta'ya bildirir (Conversions API for Business Messaging). Müşteri bir reklama/gönderiye tıklayıp sohbeti başlattığında Meta, ilk gelen mesajın referral nesnesinde ctwa_clid gönderir; bunu kişi bazında saklarız. Satış gerçekleştiğinde POST /conversions ile Purchase (ya da başka) olayı iletilir; ctwa_clid vermezseniz ilgili müşteri (to) için yakalanmış son tıklama kullanılır. İletim için numaranın Meta erişim anahtarında whatsapp_business_manage_events izni gerekir; yoksa 403 manage_events_permission_required döner. Olaylar event_id ile tekilleştirilir (Meta tekilleştirmez).

#Conversion nesnesi

  • event_idstring
    Tekilleştirme kimliği. Verilmezse order_id, o da yoksa türetilir.
  • event_namestring
    Dönüşüm olayı adı (ör. Purchase).
  • ctwa_clidstring
    İlişkilendirilen reklam tıklaması kimliği (yankıda kısmen maskelenir).
  • valuenumber · boş olabilir
    Satış tutarı.
  • currencystring · boş olabilir
    ISO 4217 para birimi (ör. TRY).
  • dataset_idstring · boş olabilir
    Olayın gönderildiği Meta dataset kimliği (WABA başına, otomatik oluşturulur/önbelleğe alınır).
  • statusstring
    İletim durumu.Değerler: sent, failed, permission
  • events_receivedinteger · boş olabilir
    Meta'nın kabul ettiği olay sayısı.
Conversion nesnesi
{
  "ok": true,
  "event_id": "VM261113155546D6",
  "event_name": "Purchase",
  "dataset_id": "1298340012345678",
  "events_received": 1,
  "duplicate": false,
  "ctwa_clid": "ARAb1C…k9Qd"
}

#Dönüşüm (satış) bildir

POST/conversions
Click-to-WhatsApp reklamından gelen bir satış/dönüşüm olayını Meta'ya iletir. ctwa_clid doğrudan gönderilebilir; gönderilmezse to (müşteri numarası) için yakalanmış son reklam tıklaması kullanılır. Değer bildirecekseniz value ile birlikte currency zorunludur. Aynı event_id yeniden gönderilirse olay tekrar iletilmez (duplicate: true). Kapsam: conversions:write
Dataset WABA başına otomatik oluşturulur ve wa_clients'ta önbelleğe alınır; ayrı kurulum gerekmez.
Test anahtarıyla (vmk_test_) çağrı Meta'ya gitmez; simulated: true ve sahte dataset_id döner.
ctwa_clid yankıda güvenlik için kısmen maskelenir; tam değeri GET /conversions/click ile alırsınız.

İstek gövdesi

  • phone_number_idstringzorunlu
    Dönüşümün ilişkili olduğu numaranın phone_number_id değeri (yalnız rakam).
  • event_namestringisteğe bağlı
    Dönüşüm olayı adı. Varsayılan Purchase.Değerler: Purchase, Lead, LeadSubmitted, InitiateCheckout, AddToCart, ViewContent, Subscribe, CompleteRegistration, Contact, Schedule, StartTrialVarsayılan: Purchase
  • tostringisteğe bağlı
    Müşteri WhatsApp numarası. ctwa_clid verilmediğinde bu numara için yakalanmış son reklam tıklaması kullanılır.
  • ctwa_clidstringisteğe bağlı
    İlişkilendirilecek reklam tıklaması kimliği. Verilirse to araması yapılmaz.
  • valuenumberisteğe bağlı
    Satış tutarı. Gönderilirse currency zorunludur.
  • currencystringisteğe bağlı
    ISO 4217 para birimi (3 harf), ör. TRY.
  • event_timeintegeristeğe bağlı
    Olayın gerçekleştiği Unix zaman damgası (saniye). Varsayılan şimdiki zaman.
  • event_idstringisteğe bağlı
    Tekilleştirme kimliği. Verilmezse order_id, o da yoksa ctwa_clid + olaydan türetilir.
  • order_idstringisteğe bağlı
    Sipariş kimliği. event_id verilmezse tekilleştirme için kullanılır.
  • custom_dataobjectisteğe bağlı
    Meta olayına eklenecek ek alanlar (value/currency buraya da yazılır).

Hatalar

DurumKodNe zaman
403insufficient_scopeAnahtarda conversions:write kapsamı yok.
403manage_events_permission_requiredNumaranın Meta erişim anahtarında whatsapp_business_manage_events izni yok; Meta dataset'e yazmayı reddetti.
404number_not_foundphone_number_id hesabınızda aktif değil.
422invalid_event_nameDesteklenmeyen event_name (geçerli değerler listesi mesajda döner).
422ctwa_clid_requiredctwa_clid verilmedi ve to için yakalanmış reklam tıklaması yok.
422currency_requiredvalue gönderildi ama currency yok.
502conversion_failedMeta olayı kabul etmedi (ayrıntı message alanında).
curl -X POST "https://api.verimerkezi.app/wa/conversions" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "event_name": "Purchase",
    "value": 1990,
    "currency": "TRY",
    "to": "905550000000",
    "order_id": "VM261113155546D6"
  }'
Yanıt 200
{
  "ok": true,
  "event_id": "VM261113155546D6",
  "event_name": "Purchase",
  "dataset_id": "1298340012345678",
  "events_received": 1,
  "duplicate": false,
  "ctwa_clid": "ARAb1C…k9Qd"
}

#İletilen dönüşümleri listele

GET/conversions
Hesabınız için en son iletilen dönüşüm olaylarını durum ve hata bilgisiyle döndürür. Kapsam: conversions:read

Sorgu parametreleri

  • limitintegeristeğe bağlı
    Dönecek kayıt sayısı (1–100).Varsayılan: 25

Hatalar

DurumKodNe zaman
403insufficient_scopeAnahtarda conversions:read kapsamı yok.
curl -X GET "https://api.verimerkezi.app/wa/conversions?limit=25" \
  -H "Authorization: Bearer $VM_API_KEY"
Yanıt 200
{
  "ok": true,
  "conversions": [
    {
      "event_id": "VM261113155546D6",
      "event_name": "Purchase",
      "phone_number_id": "1234567890",
      "ctwa_clid": "ARAb1C…k9Qd",
      "value": 1990,
      "currency": "TRY",
      "dataset_id": "1298340012345678",
      "status": "sent",
      "error": null,
      "created_at": "2026-11-13 15:55:46"
    }
  ]
}

#Kişi için yakalanmış tıklamayı getir

GET/conversions/click
Bir müşteri için yakalanmış en güncel CTWA reklam tıklamasını (ctwa_clid ve reklam bilgisi) döndürür. Dönüşümü kendi sisteminizden Meta'ya iletecekseniz tam ctwa_clid'i buradan alırsınız. Kapsam: conversions:read
İlişkilendirme penceresi varsayılan 7 gündür; daha eski tıklamalar found: false döner.

Sorgu parametreleri

  • phone_number_idstringzorunlu
    Numaranın phone_number_id değeri.
  • tostringzorunlu
    Müşteri WhatsApp numarası.

Hatalar

DurumKodNe zaman
403insufficient_scopeAnahtarda conversions:read kapsamı yok.
404number_not_foundphone_number_id hesabınızda yok.
422invalid_requestphone_number_id ve to zorunludur.
curl -X GET "https://api.verimerkezi.app/wa/conversions/click?phone_number_id=1234567890&to=905551234567" \
  -H "Authorization: Bearer $VM_API_KEY"
Yanıt 200
{
  "ok": true,
  "found": true,
  "ctwa_clid": "ARAb1CdEf…xyz0k9Qd",
  "source_id": "120210000000000000",
  "source_type": "ad",
  "headline": "Hemen keşfet",
  "received_at": "2026-11-13 14:02:10"
}