Skip to main content

Onay Yönetimi ve Makbuzlar

Düzenlemeye tabi bir kanalda bir kişiye mesaj göndermeden önce genellikle hukuki bir dayanağa — çoğunlukla da onaya — ihtiyacınız vardır. Orbit’in onay API’si; kimin hangi kanalda, ne zaman ve hangi hukuki dayanakla opt-in veya opt-out yaptığının kayıt sistemidir. Her yazma işlemi, gönderimlerinizin denetlendiği yüzeylere yayılır; dolayısıyla onayı burada kaydetmek, bir mesajı gerçekten engelleyen (veya engelini kaldıran) eylemdir. Ayrıca tüm kayıt izini denetime hazır CSV veya JSON dosyası olarak dışa aktarabilirsiniz. Aşağıdaki tüm uç noktalar şu kökte bulunur: https://api.orbit.devotel.io/api/v1/compliance.
Onayı Orbit’te kaydetmek denetlenebilir bir iz oluşturur; ancak tek başına bir gönderimi hukuken geçerli kılmaz. Geçerli onay almaktan ve gönderdiğiniz içerikten siz sorumlusunuz. Bu sayfa hukuki tavsiye değildir.

Kanallar ve durumlar

Onay kanal başına takip edilir. Desteklenen kanal kümesi şunlardır: email, fax, instagram, line, messenger, push, rcs, sms, viber, voice, whatsapp. Bir (contact, channel) çifti üç durumdan birine çözümlenir:

Onay kaydetme

POST /compliance/consent, tek bir çağrıda bir veya daha fazla kanalda opt-in veya opt-out kaydeder. Kişiyi contact_id ile ya da identifier ile (e-posta, E.164 telefon veya WhatsApp ID — Orbit türü otomatik olarak çözümleyerek) tanımlayın.
201 Created döndürür:
Hem valid_until hem expires_in_days sağlamak belirsizlik yaratır ve 422 VALIDATION_ERROR ile reddedilir. Bir pencere ayarladığınızda 201 yanıtı çözümlenen valid_until değerini (mutlak geçerlilik anı) yansıtır; sona ermeyen bir onay veya opt-out için bu değer null’dır. Zaten opt-in durumda olan bir kanal için onayı tazelemek, meta veri/kanıtı yeniler ancak orijinal granted_at korunur — yalnızca geçerlilik süresi güncellenir. Bir yazma işleminin yaptıkları. Kaydedilen her kanal, senkronize dört yüzeyi günceller: consent_records denetim tablosu, gönderim kontrol noktalarınızın okuduğu hızlı yol olan kişinin channel_preferences aynası, suppression_list (opt-out durumunda) ve uçuş halindeki kampanya yığınlarının değişikliği ~10 dakika içinde uygulamasını sağlayan kısa ömürlü bir Redis STOP-fence’i.
Yazma işlemleri kısmen-hata-güvenlidir: bir kanal başarısız olursa diğerleri yine de uygulanır. Kısmi bir yazmayı tespit etmek için consent_record_ids.length değerini istediğiniz kanal sayısıyla karşılaştırın. Zaten opt-in durumda olan bir kanal için onayı yeniden kaydetmek, meta veri/kanıtı tazeler ancak orijinal granted_at değerini korur.

Onay sorgulama

GET /compliance/consent/lookup, tek bir (contact, channel) çiftinin güncel durumunu döndürür — gönderim öncesi geçit olarak kullanın.
state değerinin unknown olması, çift için kayıt olmadığı anlamına gelir — uygulamanız, bunun onay anlamına mı gelip gelmediğine (bazı işlemsel akışlar) veya gönderimi engellemesi gerekip gerekmediğine (çoğu pazarlama akışı) karar verir. Son üç alan, zamana bağlı onay hakkında bilgi verir ve her zaman mevcuttur:

Süresi dolmakta olan onayları bulma

GET /compliance/consent/expiring, geçerlilik penceresi dolmuş veya dolmak üzere olan opt-in’leri kiracı genelinde tarar — bu, yeniden izin (yeniden onay) kampanyasının girdisidir. Yalnızca valid_until taşıyan onaylar döndürülür; sona ermeyen onaylar hiçbir zaman görünmez.
Sorgu parametreleri:
Öğeler en eski süresi dolan önce olacak şekilde sıralanır. Her biri status (expired veya expiring) taşır; böylece “hemen yeniden onay zorunlu” ile “pencere kapanmadan uyar” ayrımı yapabilirsiniz. Yeniden onay, sıradan bir POST /compliance/consent opt-in’dir — isteğe bağlı olarak taze bir valid_until veya expires_in_days ile.
next_cursor değerini opak olarak ele alın ve değişim olmadan ileri geri aktarın; null değeri son sayfa anlamına gelir. Geçersiz veya eski bir imleç, hata yerine yeni bir ilk sayfa olarak işlenir.

Onaylı onay (çift opt-in) el sıkışmaları

Düz POST /compliance/consent, onayı belirtir — kendi yüzeyiniz onayı aldıktan sonra kayıt sistemidir. Kanıt katmanı kayıtlı bir alıcı yanıtı gerektirdiğinde (TCPA açık yazılı onay, AB onaylı opt-in, 10DLC kampanya incelemesi), yönetilen çift opt-in el sıkışmasını devreye alın:
  1. POST /compliance/consent/double-opt-in — başlat: çift için beklemede (henüz onay verilmemiş) satır kaydedir ve onay istemi metnini döndürür.
  2. Alıcı yanıt verir; metni POST /compliance/consent/double-opt-in/confirm — onayla: bekleyen isteme olumlu bir anahtar kelime, çifti onaylanmış bir opted_in onayına dönüştürür.
  3. GET /compliance/consent/double-opt-in/status — oku: yan etkisiz (side-effect free) olarak mevcut durum (opted_in | opted_out | pending | none) artı confirmed / awaiting_reply bayrakları.
Onaylanan el sıkışmaları, bu sayfanın belgeleddiği onay defterine kaydedilir — /lookup, /history ve dışa aktarım, bunları aynı şekilde okur. Onaylanana kadar bekleyen bir el sıkışması onay verisi değildir. Kiracıya ait: platform adına hiçbir el sıkışması başlatılmaz. Tam mekaniği Onaylı Onay (Çift Opt-In) El Sıkışmaları sayfasında bulun.

Onay geçmişi

GET /compliance/consent/history, bir kişiye ait tam sayfalanabilir denetim izini döndürür — her onay verme ve geri alma, en yeniden eskiye. Sorgu parametreleri: contact_id veya identifier (bir zorunlu), isteğe bağlı bir channel filtresi, limit (≤ 100, varsayılan 50) ve bir opak cursor.
Bir TCPA denetimi “mevcut durum nedir” diye sormaz — “her verme ve iptali göster” der. /history’yi channel filtresiz okumak kanal-üstü diziyi döndürür:
En eski öğeden başlayarak okuyun: SMS’te opt-in (cr_a0…), STOP (cr_a1…), yeni opt-in (cr_b2…), ikinci STOP (cr_c3…) — ve anahtar kelime STOP scope all iddia ettiği için aynı saniye voice kanalına eşlenmiş bir opted_out satırı (cr_d4…) damgalar. Bu eşlik denetim kanıtıdır.
next_cursor değerini opak ele alın — bir sonraki sayfayı almak için değişim yapılmadan aktarın. Geçersiz veya eski bir imleç, hata yerine yeni bir ilk sayfa olarak işlenir.

Uygulamalı örnek — iptal et, ardından denetim için zaman damgasını oku

Aynı kişi için aynı kanıtta buluşan iki iptal yolu: STOP anahtar kelimesi ve Onay API’si. İkisinin de /history’de buluşması defterin özüdür — giriş noktasından bağımsız tek bir iz vardır.
  1. Anahtar kelime yolu. Alıcı SMS numaranıza STOP yanıt verir. API çağrısı gerekmez: Orbit inbound_keyword kaynağıyla opted_out yazar ve numara için scope-all engelleme satırı ekler.
  2. API yolu. Arayüzünüz çağırır (eşdeğer sonuç):
  3. İptali denetim için geri oku. Her iki yoldan hemen sonra geçmişi çekin ve satırı revoked_at ile doğrulayın:
    En yeni öğe consent_state: "opted_out", granted: false ve 2026-06-04T09:12:35.000Z gibi bir revoked_at gösterir. Aynı yanıt içindeki önceki verme satırı artık kendi revoked_at’inde aynı anı taşır — verme ve iptal zaman damgasıyla bağlanmış: defteri tek bir hikâye yapan budur, ilişkisiz iki tablo değil.
  4. Send gate ile doğrula. Engelleme defterini (Opt-Out & Suppression Lists) status=active ile dışa aktarın ve numaranın kilitli olduğunu doğrulayın, yeniden izin sonrası filtrelenmiş /history’yi tekrar okuyun. Denetim kanıtı, onay satırı ve engelleme satırının tutarlılığıdır.

Onay-kanıt kaydını dışa aktarma

GET /compliance/consent/export, kiracı genelindeki onay izinizi tek bir dosya olarak indirir — TCPA denetimi, GDPR Madde 7(1) ispat yükü veya keşif talebi (“kim, ne zaman, hangi kanalda, hangi kaynağı kullanarak opt-in veya opt-out yaptı”) yanıtı. /lookup ve /history’nin toplu muadilidir.
Sorgu parametreleri: Her satır bir onay olayının, kişinin tanımlayıcılarıyla birleşmesini taşır — record_id, contact_id, email, phone, whatsapp_id, channel, consent_state, granted, consent_type, source ve GDPR ispat-yükü sütunları lawful_basis, purpose, policy_template, consent_text_version, consent_proof_url, ip_address, valid_until ile onay verme/ret/güncelleme zaman siempeleri. CSV indirmeleri, tarihli bir dosya adı (consent-proof-of-record-YYYY-MM-DD.csv) ile gelir ve bir okuma önbelleğini asla geçmez (Cache-Control: no-store). format=json isteyin ve yanıt bunun yerine columns / items / count zarfı döndürmesi gerçekleşir — programatik tüketiciler için aynı veriler. Erişim, owner ve admin anahtarlarıyla sınırlıdır — içerik kiracı genelinde ham alıcı tanımlayıcıları ortaya çıkarır; bu, suppression import ile aynı güven katmanıdır. Her dışa aktarım çalıştırması, filtreleri ve satır sayısıyla denetim günlüğüne yazılır.
Defteriniz 50.000 satırı aştığında dışa aktarım, kemanı kesi seker: CSV yanıtları X-Export-Truncated: true başlığını taşır ve JSON zarfı truncated: true ayarlar. Kanal veya duruma göre daraltın, ya da from/to kullanarak ardışık tarih pencereleriyle sayfalayın.

Hindistan’ın Dijital Kişisel Veri Koruma Yasası (DPDP), Consent Manager kavramını tanıtır — veri sahibinin adını kullanarak kriptografik olarak imzalanmış onay makbuzlarını basan sorumluluk sahibi kayıtlı aracı. Orbit, kullanıcılarınızın kullanıdığı yöneticileri kaydedebilir ve verdikleri makbuzları doğrular. POST /compliance/consent/managers (admin/owner), bir yönetici kaydeder ve her makbuzu doğrulamak için kullanılan ortak anahtarını (ECDSA P-256 SPKI PEM) saklar.
  • GET /compliance/consent/managers, kayıtlı yöneticileri listeler (etkin olanlar önce).
  • PUT /compliance/consent/managers/{id}, bir yöneticiyi günceller veya devre dışı bırakır (kısmi güncelleme; tüm alanlar isteğe bağlı).

İmzalı makbuz saklama

POST /compliance/consent/receipts, yönetici tarafından imzalanan bir makbuzu doğrular ve onay olarak kalıcı hale getirir. İmza (ECDSA P-256 / SHA-256, IEEE-P1363, base64url), kayıtlı yöneticinin ortak anahtarına karşı, herhangi bir şey depolanmadan önce, yük üzerinde JCS’den esinlenen, sıralı anahtarlı bir JSON kanonikleştirmesiyle kontrol edilir. Bu kanonikleştirme, nesne anahtarlarını UTF-16 kod birimi ile artana göre sıralar ve anlamsız boşlukları siler; ancak tam bir RFC 8785 uygulaması değildir — özellikle JCS’nin zorunlu sayı serileştirme kurallarını uygulamıyor. Spec’e tam uyan bir RFC 8785 doğrulayıcısı eşleşen bir hash üreteceğini varsaymak yerine, makbuzları Orbit’in kullandığı aynı sıralı anahtar biçibiyle imzalayın.
201 döndürür: { "id": …, "receipt_id": …, "verified": true }. Hatalı imza veya kayıtsız/inaktif yönetici, 422 CONSENT_RECEIPT_INVALID döndürür — ayrıntı, yükün değiştirilmiş olabileceğini veya yöneticinin anahtarları rotasyon ettiğini notlar.

Saklanan makbuzu yeniden doğrulama

POST /compliance/consent/receipts/{id}/verify, daha önce saklanmış bir makbuzu yöneticinin güncel anahtarıyla yeniden kontrol eder — bir denetim sırasında makbuzun hâlâ geçerli olduğunu ve yöneticinin hâlâ etkin olup olmadığını doğrulamak için kullanın. {id}, onay kaydı kimliği ya da receipt_id kabul eder.
Onay makbuzları, kiracının consent_managers migrasyonunu gerektirir. Bunu önceden geçen kiracılarda, okuma yolları hoş bir şekilde bozulur: yönetici listesi boş bir liste döndürür ve yeniden doğrulama uç noktası 404 döndürür. Makbuz basmak fail-closed’dur; dolayısıyla POST /compliance/consent/receipts, migrasyon öncesi kiracılarda bozulma yerine 422 CONSENT_RECEIPT_INVALID döndürür — makbuz basmadan önce migrasyonu çalıştırın.

İlgili referanslar