İzin uçları
İzin girişi, toplu giriş, sorgu ve güncel durum uçlarının kullanımı; yöntem değerleri, zaman alanları ve iş kuralları.
Son güncelleme:
Uçlara genel bakış
| Uç | Amaç |
|---|---|
POST /consents | Tek olay gönderir (1 olay = 1–50 karar). |
POST /consents/batch | Toplu gönderim: en çok 100 olay; her olay ayrı ve idempotent işlenir. |
POST /consents/query | Kişinin dış kanaldan gelmiş kararlarını (makbuzları) sorgular. |
POST /consents/status | En çok 500 kişinin güncel izin durumunu döner. Arama/ileti öncesi doğrulama için kullanılmalıdır. |
Alan alan istek/yanıt tabloları ve örnekler için Uç referansı bölümüne bakın. Bu sayfa kullanım ve kuralları anlatır.
Yanıt zarfı
Başarı ve hata aynı zarfı kullanır. Veri data içindedir; makine okunur hata kodu varsa data.code alanındadır.
{ "success": true, "statusCode": 200, "status": "OK", "message": "Success", "data": { } }
{ "success": false, "statusCode": 422, "status": "UNPROCESSABLE_ENTITY",
"message": "Müşteri kimliği bağlantıyla eşleşmiyor.", "data": { "code": "CUSTOMER_MISMATCH" } }İzin girişi
Her olay bir externalEventId, bağlantınızdaki customer.externalCustomerId, kişiyi tanıtan contact (telefon veya e-posta) ve 1–50 decisions öğesi içerir. ETK kararlarında channel zorunludur (MESAJ = SMS, ARAMA, EPOSTA).
{
"externalEventId": "evt-ornek-0001",
"customer": { "externalCustomerId": "musteri-ornek-1" },
"contact": {
"externalContactId": "kisi-ornek-1",
"phone": "+90 555 000 00 00",
"email": "ayse.yilmaz@ornek.com",
"fullName": "Ayşe Yılmaz"
},
"decisions": [
{
"kind": "KVKK",
"decision": "ONAY",
"decidedAt": "2026-10-13T14:05:30+03:00",
"evidence": { "method": "VOICE_CALL" }
},
{
"kind": "ETK",
"channel": "MESAJ",
"decision": "ONAY",
"decidedAt": "2026-10-13T14:05:41+03:00",
"evidence": { "method": "VOICE_CALL" }
},
{
"kind": "ETK",
"channel": "EPOSTA",
"decision": "RET",
"decidedAt": "2026-10-13T14:05:52+03:00",
"evidence": { "method": "VOICE_CALL" }
}
]
}{
"success": true,
"statusCode": 200,
"status": "OK",
"message": "Success",
"data": {
"externalEventId": "evt-ornek-0001",
"duplicate": false,
"results": [
{ "index": 0, "status": "APPLIED", "kind": "KVKK" },
{ "index": 1, "status": "APPLIED", "kind": "ETK", "channel": "MESAJ" },
{ "index": 2, "status": "DUPLICATE", "kind": "ETK", "channel": "EPOSTA" }
]
}
}Kanıt yöntemi (evidence.method)
evidence.method zorunludur; eksik veya geçersizse istek 400 döner. Yöntem kanıt zincirine yazılır ve sonradan değiştirilemez; bu yüzden doğru değeri seçin.
| Değer | Anlamı |
|---|---|
VOICE_CALL | Çağrı sırasında sözlü onay veya ret. |
SMS_REPLY | Kişinin SMS'e yanıtı. |
WHATSAPP | WhatsApp üzerinden verilen karar. |
WEB_FORM | Dış sisteminizin web formu. |
AGENT_MANUAL | Temsilcinin elle girişi. |
Sözlü onay için çağrı kaydı veya ek kanıt göndermeniz gerekmez; cdrId, recordingRef ve agentId yalnızca isteğe bağlı izlenebilirlik alanlarıdır. Ses kaydı, döküm veya senaryo için yalnızca SHA-256 özetlerini gönderebilirsiniz; dosyaların kendisi Rıza AL'a iletilmez. KVKK aydınlatma metni sürümü gönderilmez; metin yönetimi dış sisteminizin sorumluluğundadır.
Zaman alanları
| Alan | Anlamı | Nerede |
|---|---|---|
decidedAt | İznin verildiği veya geri çekildiği an (sizin bildirdiğiniz). Saat dilimi offset'i zorunludur (Z veya +03:00). Sıralama ve geçerlilik hesapları bu alana göredir. | İstek, sorgu yanıtı, webhook |
receivedAt | İsteğin Rıza AL'a ulaştığı an (sunucu saati). | Sorgu yanıtı |
checkedAt | Durum ucunun yanıtı hesapladığı an. | Durum yanıtı |
Toplu giriş
Gövde { "events": [ ... ] } biçimindedir; her öğe tek olay isteğiyle aynıdır (en çok 100 olay). Yanıt data.events[] dizisidir ve her öğe index taşır. Bir olayın hatası yalnızca o olayın hata alanında döner (error); HTTP yanıtı yine 200 olur, o olay işlenmemiştir ve results boştur. Toplu istekte error.code yalnızca CUSTOMER_MISMATCH veya IDEMPOTENCY_CONFLICT olur.
Sorgu
POST /consents/query gövdesinde phone veya email bulunur. Yalnızca dış kanaldan gönderdiğiniz kararlar (makbuzlar) döner; yeniden eskiye sıralıdır ve en çok 200 kayıt içerir. Telefon ve e-posta yanıtta dönmez. Birden çok kişi eşleşirse 422 AMBIGUOUS_CONTACT alırsınız.
Güncel izin durumu
POST /consents/status, dialer veya toplu gönderim öncesi doğrulama içindir. Gövdede 1–500 kişi bulunur; her kişi için phone veya email verilir (ikisi birlikte verilirse önce telefon denenir). externalContactId isteğe bağlıdır, opak olmalıdır ve kişisel veri içermemelidir.
| Durum | Anlamı | Arama/ileti |
|---|---|---|
ALLOWED | Geçerli onay var. | Yapılabilir (yalnızca bu durumda). |
DENIED | İzin yok: ret, geri çekme (İYS, onay sayfası, dış sistem), talebinde verilmemiş kanal veya bekleyen yeniden onay (reapprovalRequired: true). | Yapılamaz. |
NONE | Bu kanal için hiç karar yok (kişi bulunamadı, sorulmamış veya yanıt bekleyen yeni bir izin talebi var). | Yapılamaz. |
- Durum, Rıza AL rehberinde görünen değerle aynıdır; kaynak fark etmez, RET kazanır.
sourcedeğeriEXTERNAL,WEB,IYS,ADMIN_PANEL,IMPORTveyaOTHERolabilir.methodyalnızcasource=EXTERNALiken dolu gelir.- Satır bazlı hata (
AMBIGUOUS_CONTACT,INVALID_CONTACT) yalnızca o kişiyi etkiler; diğer satırlar sonuç döner. - Bekleyen yeniden onay şirket kapsamlıdır: hangi bağlantıdan gelmiş olursa olsun ilgili kanalı
DENIEDyapar. - Bulunan kişiler takibe alınır: sonraki değişiklikleri, kişiyi hiç bildirmemiş olsanız bile, sorguda verdiğiniz
externalContactIdileconsent.changedwebhook'u olarak alırsınız. Takip, son sorgudan sonra belirli bir süre (şu an 180 gün) geçerlidir ve her sorgu süreyi yeniler. - Her kişi istek sınırınızdan 1 birim tüketir.
ARAMA kanalında İYS durumu
channels.ARAMA.iys, numaranın İYS'teki ARAMA kaydının özetidir. Rıza AL status değerinden ayrı ve bağımsızdır; Rıza AL kaydı oluşturmaz ve status değerini değiştirmez. Aramanın bu alana dayanarak yapılıp yapılamayacağı sizin ve hukuk danışmanınızın değerlendirmesine bağlıdır.
| Değer | Anlamı |
|---|---|
ONAY | İYS'te geçerli ARAMA onayı var. |
RET | İYS'te ret veya geri çekme var. |
NONE | İYS'te ARAMA kaydı yok (veya onay İYS'e iletilememiş). |
UNKNOWN | Değer şu an verilemiyor; reason alanına bakın. |
| Değer | Anlamı ve yapılacak |
|---|---|
PENDING | Değer henüz alınmadı veya bayat; arka planda sorgulanıyor. Birkaç dakika sonra yeniden sorgulayın. |
LOOKUP_FAILED | İYS sorgusu başarısız oldu ve yeniden sıraya alındı. Daha sonra tekrar deneyin. |
SKIPPED | Rıza AL'da bu numara için ARAMA kararı var; İYS sorgusu yapılmadı. |
NO_PHONE | Geçerli bir TR cep numarası yok (e-posta ile sorgu veya yabancı numara). |
NOT_CONFIGURED | Şirketinizin İYS bağlantısı kurulu değil. |
MODULE_LOCKED | Paketinizde İYS modülü yok. |
- İstek sırasında İYS'e gidilmez; değer önbellekten okunur. Değer en fazla yaklaşık 24 saat eskidir, daha eskiyse yenilenir (
PENDING). iysalanındaki değişiklikler webhook ile gönderilmez; güncel değer için yeniden sorgulayın.- İYS'te başka bir aracı kanal üzerinden verilmiş ve hesabınıza yansımamış bir onay
NONEgörünebilir.
İş kuralları
Kişi eşleme
- Kişi yalnızca bağlantınızın şirketinde aranır; başka şirketin kişisine dokunulmaz.
- Önce telefon (
+90 555…,0555…,555…aynı kişidir), eşleşme yoksa e-posta denenir. - 1 eşleşme varsa o kişi kullanılır, 0 eşleşmede yeni kişi oluşturulur (
fullNameile), birden çok eşleşmede tahmin yapılmaz veAMBIGUOUS_CONTACTdöner.
decidedAt sınırları
- Şu andan 5 dakikadan fazla ileride olamaz (
DECIDED_AT_IN_FUTURE). - KVKK ve ETK RET kararları, şu an için 30 günden eski olamaz (
DECISION_TOO_OLD). - ETK ONAY için 30 gün kuralı değil, aşağıdaki 3 iş günü kuralı geçerlidir.
ETK onayı: 3 iş günü kuralı ve yeniden onay
İYS, ETK onayının en çok 3 iş günü eski olmasını bekler. decidedAt değeri 3 iş gününden eski bir ETK ONAY kararı geçerli onay olarak işlenmez: sonuç REJECTED + CONSENT_TOO_OLD_REAPPROVAL_REQUIRED olur ve reapprovalRequired: true döner. Rıza AL bir yeniden onay kaydı açar ve olayı gönderen bağlantınıza consent.reapproval_required webhook'u yollar. Kişiden yeni onay alıp yeni bir externalEventId ile göndermeniz gerekir. İş günü hesabı Europe/Istanbul takvimine göredir; hafta sonu, resmi tatil, dini bayram ve arife günleri iş günü sayılmaz. ETK RET ve KVKK kararları bu kuralla asla reddedilmez.
RET her zaman uygulanır
RET kararı, kayıtlı kararlardan daha eski bir decidedAt taşısa bile uygulanır. Yalnızca daha yeni bir karara aykırı bir ONAY, STALE_DECISION ile reddedilir.
Aynı veya eski karar
- Kayıtlı durum zaten aynıysa ve yeni karar daha yeni değilse sonuç
DUPLICATEolur (değişiklik yok). - Aynı değerde ama daha yeni
decidedAtise sonuçAPPLIEDolur ve zaman güncellenir; İYS'e yalnızca değer değiştiyse veya ilk kez iletilir. - Alıcı değeri (telefon/e-posta) boşsa o kanal için İYS'e iletim yapılmaz.
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).
