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:

Durum	Anlam
`opted_in`	Onay verilmiş ve geri alınmamış.
`opted_out`	Onay geri alınmış veya açık bir opt-out kaydedilmiş.
`unknown`	Çift için onay kaydı yok — varsayılanı gönderim geçidiniz belirler.

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.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "jordan@example.com",
    "channels": ["email", "sms"],
    "opt_in": true,
    "source": "web_form",
    "consent_type": "marketing",
    "lawful_basis": "consent",
    "purpose": "Weekly product newsletter and order updates",
    "consent_text_version": "tos-2026-04",
    "consent_proof_url": "https://example.com/proofs/abc123.png"
  }'

201 Created döndürür:

{
  "contact_id": "cnt_9f…",
  "consent_record_ids": ["cr_a1…", "cr_b2…"],
  "channels": ["email", "sms"],
  "state": "opted_in",
  "valid_until": null
}

Alan	Tür	Notlar
`contact_id` / `identifier`	string	İkisinden birini sağlayın.
`channels`	string[]	Kanal kümesinden bir veya daha fazla; tekilleştirilmiş ve sıralıdır.
`opt_in`	boolean	Zorunlu. `true` = opt-in, `false` = opt-out.
`source`	string	Onayın nasıl yakalandığı (örn. `web_form`, `import`, `double_opt_in`). Varsayılan `consent_api`.
`consent_type`	string	Amaç kategorisi; örn. `marketing`, `transactional`. Varsayılan `messaging`.
`lawful_basis`	enum	GDPR Madde 6 dayanağı: `consent`, `contract`, `legal_obligation`, `vital_interests`, `public_task`, `legitimate_interests`.
`purpose`	string	Kullanımı açıklayan serbest metin (≤ 500).
`consent_text_version`	string	Veri sahibinin kabul ettiği bildirimin sürümü.
`consent_proof_url`	string (url)	Ekran görüntüsüne veya imzalı belgeye bağlantı.
`valid_until`	string (ISO-8601 UTC)	Onayın sona erdiği mutlak an. Yalnızca opt-in — opt-out’ta yoksayılır. `expires_in_days` ile karşılıklı olarak dışlayıcıdır.
`expires_in_days`	integer	Göreli geçerlilik penceresi (bugünden itibaren 1–3650 gün). Yalnızca opt-in. `valid_until` ile karşılıklı olarak dışlayıcıdır.
`metadata`	object	İsteğe bağlı özel anahtar/değer çiftleri.

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.

curl "https://api.orbit.devotel.io/api/v1/compliance/consent/lookup?identifier=jordan@example.com&channel=sms" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "contact_id": "cnt_9f…",
  "channel": "sms",
  "state": "opted_in",
  "source": "web_form",
  "granted_at": "2026-04-02T10:11:00.000Z",
  "revoked_at": null,
  "lawful_basis": "consent",
  "purpose": "Weekly product newsletter and order updates",
  "consent_text_version": "tos-2026-04",
  "consent_proof_url": "https://example.com/proofs/abc123.png",
  "valid_until": null,
  "expired": false,
  "requires_reconfirmation": false
}

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:

Alan	Tür	Notlar
`valid_until`	string \| null	Onayın sona erdği an; onayın hiç sona ermediği durumlarda (veya çift opt-out durumdaysa) `null`.
`expired`	boolean	Opt-in onayının `valid_until` değeri artık geçmişte kaldığında `true`. Süresi dolmuş bir onayı gönderim geçidinizde artık-onay-olmayan olarak değerlendirin.
`requires_reconfirmation`	boolean	`expired` aynası — yeniden izin akışı tetikleme ipucu. Yeni bir opt-in kaydı (isteğe bağlı yeni bir pencere ile) kaydettirerek temizleyin.

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.

curl "https://api.orbit.devotel.io/api/v1/compliance/consent/expiring?within_days=30&status=all" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Sorgu parametreleri:

Parametre	Tür	Notlar
`within_days`	integer	İleriye bakış ufku (0–3650, varsayılan 30). `valid_until` değeri şu an + `within_days` değerine eşit veya öncesinde olan onayları döndürür; süresi dolmuş onaylar her zaman dahildir.
`channel`	enum	İsteğe bağlı — tek bir kanal ile sınırlayın.
`status`	enum	`all` (varsayılan), `expired` (`valid_until` zaten geçilmiş) veya `expiring` (hâlâ geçerli ancak ufukta).
`limit`	integer	Sayfa boyutu (1–100, varsayılan 50).
`cursor`	string	Opak sayfalama imleci — değişim yapılmadan ileri geri aktarılmalıdır.

{
  "within_days": 30,
  "channel": null,
  "status": "all",
  "as_of": "2026-05-01T09:00:00.000Z",
  "items": [
    {
      "id": "cr_b2…",
      "contact_id": "cnt_9f…",
      "channel": "sms",
      "consent_type": "marketing",
      "source": "web_form",
      "lawful_basis": "consent",
      "granted_at": "2025-05-02T10:11:00.000Z",
      "valid_until": "2026-04-20T00:00:00.000Z",
      "expired": true,
      "status": "expired",
      "requires_reconfirmation": true
    }
  ],
  "next_cursor": null
}

Öğ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:

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.
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.
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.

{
  "contact_id": "cnt_9f…",
  "channel": null,
  "items": [
    {
      "id": "cr_b2…",
      "channel": "sms",
      "consent_state": "opted_in",
      "granted": true,
      "source": "web_form",
      "granted_at": "2026-04-02T10:11:00.000Z",
      "revoked_at": null,
      "lawful_basis": "consent",
      "created_at": "2026-04-02T10:11:00.000Z"
    }
  ],
  "next_cursor": "eyJ0…"
}

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.

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.

curl "https://api.orbit.devotel.io/api/v1/compliance/consent/export?format=csv&state=opted_out" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -o consent-proof-of-record.csv

Sorgu parametreleri:

Parametre	Tür	Notlar
`format`	enum	`csv` (varsayılan — RFC-4180, bir elektronik tabloda açılır) veya `json`.
`channel`	enum	Tek bir kanaldaki onayları kısırla.
`state`	enum	`all` (varsayılan), `opted_in`, `opted_out` veya `unknown`.
`contact_id`	string	Onayı tek bir kişiyle sınırlayın — keşif taleplerinin şekli.
`from` / `to`	string	Kayıt `created_at` üzerinde tarih aralığı. Düz `YYYY-MM-DD` tarihi veya RFC-3339 tarih saati kabul eder.
`limit`	integer	Dahil edilecek satır sayısı (1–50.000, varsayılan 50.000).

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.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent/managers \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Consent Manager",
    "manager_id": "acme-cm-001",
    "manager_url": "https://cm.acme.example",
    "public_key": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----",
    "country_code": "IN"
  }'

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.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent/receipts \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "cnt_9f…",
    "consent_manager_id": "acme-cm-001",
    "channel": "sms",
    "consent_type": "marketing",
    "receipt": {
      "receipt_id": "rcpt_77…",
      "issued_at": "2026-05-01T09:00:00.000Z",
      "purpose": "Promotional SMS",
      "fiduciary_id": "fid_acme",
      "signature": "MEUCIQ…",
      "payload": { "…": "…" }
    }
  }'

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

Bir GDPR Duruşunu Uçstante Uca Kurma — bu onay katmanını besleyen sıra.
Onaylı Onay (Çift Opt-In) El Sıkışmaları — düz bir onay kaydı üzerindeki başlat/onayla/durum akışı.
Onay Duruşu: Bilinmeyen-Onay Politikaları — defter satırı olmayan kişilere neyin gönderileceğine karar veren (pazarlama gönderileri veya CDP fanout) kuruluş düzeyindeki düğmeler.
Opt-Out ve Suppression Listeleri — opt-out’ları toplu içe aktarma ve suppression listesinin gönderimleri nasıl kapıdışı yaptığını.
DSAR — onay kaydı üzerinde erişim/silme taleplerini yerine getirme.
DLT-Hindistan Onboarding — Hint SMS’teki DPDP onayıyla eşleşen kayıt katmanı.
API Referans → Uyum — tam istek/yanıt şemaları (canlı API’den yeniden üretilmiştir).

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Onay Yönetimi ve Makbuzlar

Onay Yönetimi ve Makbuzlar

Kanallar ve durumlar

Onay kaydetme

Onay sorgulama

Süresi dolmakta olan onayları bulma

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

Onay geçmişi

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

İmzalı makbuz saklama

Saklanan makbuzu yeniden doğrulama

İlgili referanslar

​Onay Yönetimi ve Makbuzlar

​Kanallar ve durumlar

​Onay kaydetme

​Onay sorgulama

​Süresi dolmakta olan onayları bulma

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

​Onay geçmişi

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

​Bir Consent Manager kaydetme

​İmzalı makbuz saklama

​Saklanan makbuzu yeniden doğrulama

​İlgili referanslar

Onay Yönetimi ve Makbuzlar

Kanallar ve durumlar

Onay kaydetme

Onay sorgulama

Süresi dolmakta olan onayları bulma

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

Onay geçmişi

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

Bir Consent Manager kaydetme

İmzalı makbuz saklama

Saklanan makbuzu yeniden doğrulama

İlgili referanslar