Tüm uçlar POST ile çağrılır ve Kimlik doğrulama bölümünde anlatılan başlıklar ile imza gerektirir. Aşağıdaki yollar, taban adresten sonra {clientKey} önekiyle birlikte yazılmıştır; doğrudan bağlantıda clientKey değeri direct'tir. Örneklerdeki tüm değerler uydurmadır.
Yanıtlar { success, statusCode, status, message, data } zarfında döner; veri data içindedir. Hata kodu varsa data.code alanındadır.
Tek olay: dış sistemde alınan KVKK/ETK kararlarını bildir
Bir olay (externalEventId) 1–50 karar içerir. Aynı Idempotency-Key (yoksa externalEventId) + aynı gövde güvenle yeniden gönderilebilir (saklı sonuç döner); aynı anahtar + farklı gövde 409'dur. Her karar için sonuç APPLIED / DUPLICATE / REJECTED(code) olarak döner. ETK kararları commit sonrası İYS kuyruğuna alınır; KVKK gitmez. İmza: X-Rizaal-Signature: v1=<hex HMAC-SHA256(secret, timestamp + "." + rawBody)>.
Parametreler
Tek olay: dış sistemde alınan KVKK/ETK kararlarını bildir — parametreler
Ad
Yeri
Zorunlu
Açıklama
Idempotency-Key
Başlık
Hayır
Opsiyonel; yoksa externalEventId kullanılır. 191 karakterden uzun anahtarlar reddedilmez, SHA-256 ile kısaltılır.
Onayın alındığı yöntem (zorunlu; kanıt zincirinde EXT:VOICE|SMS|WA|WEB|AGENT olarak hash'e girer).
decisions[].evidence.ip
string
Hayır
Örnek: 203.0.113.10.
decisions[].evidence.userAgent
string
Hayır
Örnek: Mozilla/5.0.
decisions[].evidence.sourceUrl
string
Hayır
Örnek: https://form.example.com/consent.
decisions[].evidence.cdrId
string
Hayır
Çağrı kaydı kimliği (OPSİYONEL; çağrı kaydı zorunlu değil). Örnek: cdr-8841.
decisions[].evidence.recordingRef
string
Hayır
Örnek: rec/2026/10/13/abc.wav.
decisions[].evidence.agentId
string
Hayır
Örnek: agent-17.
decisions[].evidence.recordingSha256
string
Hayır
Çağrı ses kaydı dosyasının SHA-256 özeti (64 hex). Kayıt Rıza AL'a gönderilmez; özeti mühürlenir, kaydın sonradan değiştirilmediği bu özetle ispatlanır. Örnek: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.
true: ETK ONAY kararı 3 iş gününden eski olduğu için (İYS H467) geçerli onay olarak işlenmedi; son kullanıcıdan YENİDEN ONAY alınmalı. code=CONSENT_TOO_OLD_REAPPROVAL_REQUIRED ile birlikte gelir; bağlantıya consent.reapproval_required webhook'u da gönderilir.
results[].kind
string
Hayır
Örnek: ETK.
results[].channel
string
Hayır
Örnek: MESAJ.
Tek olay: dış sistemde alınan KVKK/ETK kararlarını bildir — yanıt örneğijson
Her olay kendi externalEventId'siyle ayrı idempotent işlenir; bir olayın hatası (CUSTOMER_MISMATCH, IDEMPOTENCY_CONFLICT) yalnız o olayın error alanında döner. Idempotency-Key verilirse her olayın anahtarı <key>:<externalEventId> olur.
Parametreler
Toplu: en çok 100 olay, sonuçlar olay bazlı — parametreler
Ad
Yeri
Zorunlu
Açıklama
Idempotency-Key
Başlık
Hayır
—
X-Rizaal-Signature
Başlık
Evet
—
X-Rizaal-Timestamp
Başlık
Evet
—
X-Rizaal-Api-Key
Başlık
Hayır
—
Authorization
Başlık
Hayır
—
clientKey
Yol
Evet
İstemci anahtarı; doğrudan bağlantıda direct.
İstek alanları
Toplu: en çok 100 olay, sonuçlar olay bazlı — istek alanları
Alan
Tip
Zorunlu
Açıklama
events
dizi (nesne)
Evet
1..100 olay; her olay kendi idempotency kimliğiyle ayrı işlenir.
events[].externalEventId
string
Evet
Dış sistemin olay kimliği (≤191). Aynı kimlik + aynı gövde güvenle yeniden gönderilebilir. Örnek: evt-2026-10-13-0001.
events[].customer
nesne
Evet
—
events[].customer.externalCustomerId
string
Evet
Dış sistemdeki müşteri kimliği. Anahtarın bağlı olduğu müşteriyle AYNI olmalı; aksi halde 422 CUSTOMER_MISMATCH. Örnek: cust-1042.
events[].contact
nesne
Evet
—
events[].contact.externalContactId
string
Hayır
Dış sistemdeki kişi kimliği (opak; makbuza yazılır). Örnek: lead-77.
events[].contact.externalContactType
string
Hayır
Dış sistemdeki kişi türü (opak; makbuza yazılır). Örnek: LEAD.
events[].contact.phone
string
Hayır
Telefon. phone veya email'den en az biri zorunlu. Türkiye numaraları +90 / 0 / çıplak biçimlerde kabul edilir. Örnek: +905321234567.
events[].contact.email
string
Hayır
Örnek: ayse@example.com.
events[].contact.fullName
string
Hayır
Yalnız kişi Rıza AL'da yoksa yeni kayıt için kullanılır. Örnek: Ayşe Yılmaz.
events[].decisions
dizi (nesne)
Evet
1..50 karar.
events[].decisions[].kind
ETK | KVKK
Evet
—
events[].decisions[].channel
MESAJ | ARAMA | EPOSTA
Hayır
ETK için ZORUNLU (MESAJ=SMS, ARAMA, EPOSTA); KVKK'da yok sayılır.
events[].decisions[].consentTypeSlug
string
Hayır
KVKK kararında Rıza AL consent type kodu (varsayılan: KVKK). Bilinmeyen kod REJECTED/UNKNOWN_CONSENT_TYPE. Örnek: KVKK.
events[].decisions[].decision
ONAY | RET
Evet
—
events[].decisions[].decidedAt
string
Evet
Kararın alındığı an (ISO-8601). Saat dilimi offset'i ZORUNLU (Z veya +03:00); offset ayrıca saklanır. Örnek: 2026-10-13T14:05:30+03:00.
Onayın alındığı yöntem (zorunlu; kanıt zincirinde EXT:VOICE|SMS|WA|WEB|AGENT olarak hash'e girer).
events[].decisions[].evidence.ip
string
Hayır
Örnek: 203.0.113.10.
events[].decisions[].evidence.userAgent
string
Hayır
Örnek: Mozilla/5.0.
events[].decisions[].evidence.sourceUrl
string
Hayır
Örnek: https://form.example.com/consent.
events[].decisions[].evidence.cdrId
string
Hayır
Çağrı kaydı kimliği (OPSİYONEL; çağrı kaydı zorunlu değil). Örnek: cdr-8841.
events[].decisions[].evidence.recordingRef
string
Hayır
Örnek: rec/2026/10/13/abc.wav.
events[].decisions[].evidence.agentId
string
Hayır
Örnek: agent-17.
events[].decisions[].evidence.recordingSha256
string
Hayır
Çağrı ses kaydı dosyasının SHA-256 özeti (64 hex). Kayıt Rıza AL'a gönderilmez; özeti mühürlenir, kaydın sonradan değiştirilmediği bu özetle ispatlanır. Örnek: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.
true: ETK ONAY kararı 3 iş gününden eski olduğu için (İYS H467) geçerli onay olarak işlenmedi; son kullanıcıdan YENİDEN ONAY alınmalı. code=CONSENT_TOO_OLD_REAPPROVAL_REQUIRED ile birlikte gelir; bağlantıya consent.reapproval_required webhook'u da gönderilir.
events[].results[].kind
string
Hayır
Örnek: ETK.
events[].results[].channel
string
Hayır
Örnek: MESAJ.
events[].index
number
Evet
İstekteki olay sırası (0 tabanlı). Örnek: 0.
events[].error
nesne
Hayır
Olay düzeyinde hata (olay hiç işlenmedi; results boş). Diğer olaylar etkilenmez.
events[].error.code
CUSTOMER_MISMATCH | IDEMPOTENCY_CONFLICT
Evet
—
events[].error.message
string
Evet
Örnek: Müşteri kimliği bağlantıyla eşleşmiyor..
Toplu: en çok 100 olay, sonuçlar olay bazlı — yanıt örneğijson
Gövdedeki phone veya email ile şirket kapsamında kişi bulunur (PII URL'de dolaşmaz); telefon/e-posta yanıtta DÖNMEZ. İmza diğer POST uçlarıyla aynıdır (ham gövde). Birden çok kişi eşleşirse 422 AMBIGUOUS_CONTACT.
Parametreler
Kişinin dış kanal rıza kararlarını sorgula — parametreler
Ad
Yeri
Zorunlu
Açıklama
X-Rizaal-Signature
Başlık
Evet
—
X-Rizaal-Timestamp
Başlık
Evet
—
X-Rizaal-Api-Key
Başlık
Hayır
—
Authorization
Başlık
Hayır
—
clientKey
Yol
Evet
İstemci anahtarı; doğrudan bağlantıda direct.
İstek alanları
Kişinin dış kanal rıza kararlarını sorgula — istek alanları
Alan
Tip
Zorunlu
Açıklama
phone
string
Hayır
Örnek: +905321234567.
email
string
Hayır
Örnek: ayse@example.com.
Kişinin dış kanal rıza kararlarını sorgula — istek örneğijson
{ "phone": "+90 555 000 00 00" }
Yanıt alanları
Kişinin dış kanal rıza kararlarını sorgula — yanıt alanları (data içinde)
Alan
Tip
Zorunlu
Açıklama
found
boolean
Evet
—
decisions
dizi (nesne)
Evet
Yeniden eskiye sıralı dış kanal kararları (en çok 200). Telefon/e-posta DÖNMEZ.
decisions[].kind
string
Evet
Örnek: ETK.
decisions[].channel
string | null
Evet
Örnek: MESAJ.
decisions[].consentTypeCode
string | null
Evet
Örnek: KVKK.
decisions[].decision
string
Evet
Örnek: ONAY.
decisions[].method
string
Evet
Örnek: VOICE_CALL.
decisions[].decidedAt
string
Evet
Örnek: 2026-10-13T11:05:30.000Z.
decisions[].decidedAtOffset
string
Evet
Örnek: +03:00.
decisions[].receivedAt
string
Evet
Örnek: 2026-10-13T11:06:00.000Z.
decisions[].receiptId
string
Evet
Makbuz kimliği (kaynak). Örnek: 12.
decisions[].externalEventId
string
Evet
Örnek: evt-2026-10-13-0001.
Kişinin dış kanal rıza kararlarını sorgula — yanıt örneğijson
Tek istekte en çok 500 kişi (phone veya email; isteğe bağlı externalContactId). Durum, kaynağı ne olursa olsun (dış sistem, İYS, web onay/geri çekme sayfası) kişinin Rıza AL'daki GEÇERLİ ETK kanal değeridir; RET kazanır. Yalnız ALLOWED ileti/arama için yeterlidir; bekleyen yeniden onay DENIED + reapprovalRequired:true döner. Bulunan kişiler bağlantı için takibe alınır: sonraki değişiklikleri consent.changed webhook'uyla (sorguda verilen externalContactId ile) bildirilir. Her kişi bağlantının dakikalık bütçesinden 1 birim harcar. Belirsiz/geçersiz girdi yalnız kendi satırında error döner. Telefon/e-posta yanıtta DÖNMEZ. İmza diğer POST uçlarıyla aynıdır.
Parametreler
Toplu güncel izin durumu: kişilerin ARAMA/MESAJ/EPOSTA kanallarındaki geçerli ETK durumu — parametreler
Ad
Yeri
Zorunlu
Açıklama
X-Rizaal-Signature
Başlık
Evet
—
X-Rizaal-Timestamp
Başlık
Evet
—
X-Rizaal-Api-Key
Başlık
Hayır
—
Authorization
Başlık
Hayır
—
clientKey
Yol
Evet
İstemci anahtarı; doğrudan bağlantıda direct.
İstek alanları
Toplu güncel izin durumu: kişilerin ARAMA/MESAJ/EPOSTA kanallarındaki geçerli ETK durumu — istek alanları
Alan
Tip
Zorunlu
Açıklama
contacts
dizi (nesne)
Evet
1..500 kişi. Her kişi bağlantının dakikalık bütçesinden 1 birim harcar.
contacts[].phone
string
Hayır
Telefon (+905…, 905…, 05…, 5…; boşluk/tire toleranslı). phone veya email zorunlu; ikisi birlikte verilirse önce telefon aranır. Örnek: +905321234567.
contacts[].email
string
Hayır
Örnek: ayse@example.com.
contacts[].externalContactId
string
Hayır
Dış sistemdeki kişi kimliği (opak, PII olmamalı). Yanıtta aynen döner ve kişinin sonraki consent.changed webhook'larında externalContactId olarak gelir. Örnek: lead-88231.
Toplu güncel izin durumu: kişilerin ARAMA/MESAJ/EPOSTA kanallarındaki geçerli ETK durumu — istek örneğijson
AMBIGUOUS_CONTACT: birden çok kişi eşleşti. INVALID_CONTACT: telefon geçersiz ve e-posta yok. Diğer kişiler etkilenmez.
contacts[].channels
nesne
Evet
Kişi bulunamazsa tüm kanallar NONE.
contacts[].channels.ARAMA
nesne
Evet
—
contacts[].channels.ARAMA.status
ALLOWED | DENIED | NONE
Evet
ALLOWED: geçerli onay var. DENIED: izin yok — ret, geri çekme, izin talebinde verilmemiş kanal ya da bekleyen yeniden onay. NONE: bu kanal için hiç karar yok (sorulmamış ya da yanıt bekleyen yeni bir izin talebi var). Yalnız ALLOWED ileti/arama için yeterlidir.
contacts[].channels.ARAMA.decidedAt
string | null
Evet
Bu kanaldaki geçerli kararın Rıza AL'a işlendiği an (UTC). Örnek: 2026-10-13T11:05:30.000Z.
contacts[].channels.ARAMA.source
EXTERNAL | WEB | IYS | ADMIN_PANEL | IMPORT | OTHER | null
Evet
Geçerli kararın kaynağı: EXTERNAL (dış sistem), WEB (onay/geri çekme sayfası), IYS (İYS), ADMIN_PANEL, IMPORT, OTHER.
Yalnız source=EXTERNAL iken: dış sistemin bildirdiği onay yöntemi.
contacts[].channels.ARAMA.reapprovalRequired
boolean
Evet
true: bu kanalda bekleyen yeniden onay var (ETK ONAY 3 iş gününden eski geldi); durum DENIED döner.
contacts[].channels.ARAMA.iys
nesne
Evet
İYS'teki ARAMA durumu, Rıza AL status'undan AYRI ve bağımsızdır. Arama kararı için nasıl kullanılacağı istemciye/hukuk görüşüne aittir.
contacts[].channels.ARAMA.iys.status
ONAY | RET | NONE | UNKNOWN
Evet
Numaranın İYS'teki ARAMA izni (şirketin İYS hesabı üzerinden; Rıza AL kaydı/kanıtı DEĞİLDİR). ONAY: İYS'te geçerli ARAMA onayı var. RET: ret/geri çekme. NONE: İYS'te ARAMA kaydı yok. UNKNOWN: değer şu an verilemiyor (reason).
contacts[].channels.ARAMA.iys.checkedAt
string | null
Evet
Değerin İYS'den alındığı an (UTC). Değer en fazla 24 saat eskidir; daha eskiyse UNKNOWN/PENDING döner ve yenilenir. UNKNOWN'da null. Örnek: 2026-11-03T09:12:00.000Z.
Yalnız UNKNOWN'da. PENDING: arka planda sorgulanıyor, sonraki sorguda gelir. LOOKUP_FAILED: İYS sorgusu tekrar tekrar başarısız oldu (yeniden kuyruğa alındı). SKIPPED: Rıza AL'da bu numara için ARAMA kararı var (ALLOWED/DENIED), İYS sorgusu yapılmadı. NO_PHONE: geçerli bir TR cep numarası yok. NOT_CONFIGURED: şirketin İYS'i bağlı değil. MODULE_LOCKED: şirketin paketinde İYS modülü yok.
contacts[].channels.MESAJ
nesne
Evet
—
contacts[].channels.MESAJ.status
ALLOWED | DENIED | NONE
Evet
ALLOWED: geçerli onay var. DENIED: izin yok — ret, geri çekme, izin talebinde verilmemiş kanal ya da bekleyen yeniden onay. NONE: bu kanal için hiç karar yok (sorulmamış ya da yanıt bekleyen yeni bir izin talebi var). Yalnız ALLOWED ileti/arama için yeterlidir.
contacts[].channels.MESAJ.decidedAt
string | null
Evet
Bu kanaldaki geçerli kararın Rıza AL'a işlendiği an (UTC). Örnek: 2026-10-13T11:05:30.000Z.
contacts[].channels.MESAJ.source
EXTERNAL | WEB | IYS | ADMIN_PANEL | IMPORT | OTHER | null
Evet
Geçerli kararın kaynağı: EXTERNAL (dış sistem), WEB (onay/geri çekme sayfası), IYS (İYS), ADMIN_PANEL, IMPORT, OTHER.
Yalnız source=EXTERNAL iken: dış sistemin bildirdiği onay yöntemi.
contacts[].channels.MESAJ.reapprovalRequired
boolean
Evet
true: bu kanalda bekleyen yeniden onay var (ETK ONAY 3 iş gününden eski geldi); durum DENIED döner.
contacts[].channels.EPOSTA
nesne
Evet
—
contacts[].channels.EPOSTA.status
ALLOWED | DENIED | NONE
Evet
ALLOWED: geçerli onay var. DENIED: izin yok — ret, geri çekme, izin talebinde verilmemiş kanal ya da bekleyen yeniden onay. NONE: bu kanal için hiç karar yok (sorulmamış ya da yanıt bekleyen yeni bir izin talebi var). Yalnız ALLOWED ileti/arama için yeterlidir.
contacts[].channels.EPOSTA.decidedAt
string | null
Evet
Bu kanaldaki geçerli kararın Rıza AL'a işlendiği an (UTC). Örnek: 2026-10-13T11:05:30.000Z.
contacts[].channels.EPOSTA.source
EXTERNAL | WEB | IYS | ADMIN_PANEL | IMPORT | OTHER | null
Evet
Geçerli kararın kaynağı: EXTERNAL (dış sistem), WEB (onay/geri çekme sayfası), IYS (İYS), ADMIN_PANEL, IMPORT, OTHER.
Toplu güncel izin durumu: kişilerin ARAMA/MESAJ/EPOSTA kanallarındaki geçerli ETK durumu — durum kodları
HTTP
Anlamı
200
Başarılı.
400
Geçersiz gövde / 500'den fazla kişi / phone ve email eksik.
401
Kimlik doğrulama başarısız.
402
MODULE_NOT_IN_PLAN: doğrudan (direct) bağlantıda şirketin paketinde API Erişimi modülü yok.
413
Gövde 256 KB'ı aşıyor.
429
İstek limiti aşıldı (Retry-After başlığıyla).
API anahtarınızı ve bağlantınızı yönetmek için panelde Hesabım → Şirket Ayarları → API Erişimi sekmesini kullanın. Hesabım sayfasını aç (giriş yapmanız gerekir).