Doküman Onayı ve İmza

SDK, çerez onayının yanı sıra bir kişinin bir dokümanın belirli bir sürümünü onayladığını da kaydedebilir — kullanım koşulları, mesafeli satış sözleşmesi, aydınlatma metni veya kendi sisteminizin ürettiği bir doküman.

Onay kodu cmp.js dosyasının parçası değildir. Aşağıdaki iki metottan birini ilk kez çağırdığınızda otomatik olarak (veya data-modules="documents" ile önceden) yüklenir; bkz. Paketler ve talep üzerine yüklenen modüller.

Onay almanın iki yolu

1. `CMP.showDocumentApproval(slug, options)` — HashEntry’nin diyaloğu

Dokümanın aktif sürümünü yükler, “Kabul et” ve “Reddet” butonları bulunan bir diyalogda gösterir ve kişi kabul ettiğinde onayı kaydeder.

const result = await CMP.showDocumentApproval('distance-sales-agreement', {
  language: 'en',                          // isteğe bağlı, varsayılan olarak SDK dili
  metadata: { order_id: 'ORD-54321' },     // isteğe bağlı
  approvalToken: tokenFromYourBackend      // isteğe bağlı / zorunlu, aşağıya bakın
});

if (result.success && result.decision === 'accepted') {
  continueCheckout(result.consent_token);
} else if (result.decision === 'rejected') {
  // kişi reddetti
} else {
  showError(result.error);                 // { code, status, message }
}

Seçenek	Açıklama
`language`	Gösterilecek doküman sürümünün dili.
`metadata`	Kayıtla birlikte saklanan anahtar/değer çiftleri (`CMP.setMetadata` ile birleştirilir).
`approvalToken`	Backend’inizin ürettiği tek kullanımlık onay token’ı.

Geriye dönük uyumluluk için, bu anahtarlardan hiçbirini içermeyen düz bir nesne metadata olarak değerlendirilir.

Reddetme, diyaloğu kapatır ve document:rejected event’ini tetikler; sunucuya kayıt gönderilmez. Kaydetme geçici bir hatayla başarısız olursa diyalog açık kalır ve kişi “Kabul et” butonuna yeniden basabilir — yeniden deneme aynı idempotency anahtarını (ve aynı token’ı) kullanır.

2. `CMP.approveDocument(slug, options)` — kendi arayüzünüz

Hiçbir şey göstermeden bir onay kaydeder; formunuzdaki bir onay kutusu, kendi sözleşme görüntüleyiciniz veya kendi oluşturduğunuz bir imza alanı (signature pad) için.

const result = await CMP.approveDocument('terms-of-service', {
  approvalToken: tokenFromYourBackend,
  metadata: { order_id: 'ORD-54321' }
});

Seçenek	Gönderildiği ad	Açıklama
`version_id`	`document_version_id`	Onaylanacak sürüm. Verilmezse SDK, `language` için aktif sürümü çözümler.
`version`	—	`version_id` verdiğinizde sonuçta döndürülen sürüm etiketi.
`language`	`language`	Sürümün dili.
`decision`	`decision`	`'accepted'` (varsayılan) veya `'rejected'`.
`visitor_id`	`visitor_id`	Kişi için sizin referansınız (en fazla 100 karakter). Onay token’ı kullanıldığında yok sayılır — bunun yerine token’ın `subject` değeri saklanır.
`approvalToken`	`approval_token`	Tek kullanımlık onay token’ı.
`document_content_base64`	`custom_document_content`	Sisteminizin ürettiği bir dokümanın içeriği (HTML, düz metin veya PDF; çözülmüş hâliyle yaklaşık 500 KB’a kadar).
`document_mime_type`	`custom_document_mime_type`	`text/html`, `text/plain` veya `application/pdf`.
`signature`	üst düzey alanlar	Bkz. `signature` (imza) alanları.
`metadata`	`metadata`	Kayıtla birlikte saklanan anahtar/değer çiftleri.

Aynı doküman, sürüm ve karar için zaman olarak çakışan iki çağrı tek bir isteği ve tek bir sonucu paylaşır; dolayısıyla çift tıklama iki kayıt oluşturmaz.

Tek kullanımlık onay token’ları

Tarayıcı SDK’sı isteklerini, sayfa kaynağınızda görünür olan site API anahtarıyla imzalar. Bu nedenle tarayıcıdan gönderilen bir doküman onayı, onu sayfanıza erişimi olan birinin gönderdiğini kanıtlar; içindeki ad veya e-posta adresi ise ne yazıldıysa odur.

Onay token’ı, kimin onay verdiğine backend’inizin kefil olmasını sağlar:

Oturum açmış kullanıcıyı bilen backend’iniz POST /tool/v1/s2s/approval-tokens çağrısını yapar (bkz. REST API) ve bir token (hat_…) alır.
Token’ı sayfaya aktarır ve SDK’ya approvalToken olarak verirsiniz.
SDK onu üst düzey approval_token alanı olarak gönderir. Sunucu token’ı atomik olarak tüketir, kişinin kimliğini tarayıcıdan değil token’dan alır ve kaydı identity_assurance: tenant_attested ile saklar.

Kurallar:

Bir token tek bir site ve tek bir doküman (isteğe bağlı olarak tek bir sürüm) için, sınırlı bir süre boyunca (varsayılan 10 dakika, en fazla 1 saat) ve bir kez geçerlidir.
Bir doküman, panelde token’ı zorunlu kılacak şekilde yapılandırılabilir. Böyle bir doküman için token verilmediğinde SDK, istek göndermeden hemen başarısız olur: error.code = "APPROVAL_TOKEN_REQUIRED". Sunucu da aynı kuralı uygular.
Sunucu kodları değiştirilmeden aktarılır: APPROVAL_TOKEN_REQUIRED, APPROVAL_TOKEN_INVALID (bilinmeyen, süresi dolmuş, daha önce kullanılmış veya başka bir site/doküman için üretilmiş), APPROVAL_TOKEN_CONFLICT (tarayıcının gönderdiği bir imzalayan alanı veya doküman içeriği, token’ın kefil olduğu bilgiyle çelişiyor).
Ağ hatasında veya 5xx yanıtında SDK, aynı token ve aynı idempotency anahtarıyla yeniden dener; sunucu tekrarı aynı istek olarak değerlendirir. Kesin bir 4xx yanıtından sonra hiçbir şey yeniden denenmez ve onaylar hiçbir zaman çevrimdışı kuyruğa alınmaz. Yeniden denemek için yeni bir token üretin.

`signature` (imza) alanları

approveDocument, çizilmiş bir imzayla veya açık bir beyanla alınan onaylar için bir signature nesnesi kabul eder. SDK bir imza alanı (signature pad) içermez: imza alanını (veya beyan onay kutusunu) siz oluşturur ve sonucu iletirsiniz.

await CMP.approveDocument('service-contract', {
  approvalToken: tokenFromYourBackend,
  signature: {
    image_base64: canvas.toDataURL('image/png'),
    mime_type: 'image/png',
    signer_name: 'Jane Doe',
    signer_email: '[email protected]',
    declaration_text: 'I have read and accept the service contract.',
    input_type: 'touch',
    stroke_count: 14,
    drawing_duration_ms: 3200,
    screen_resolution: '390x844'
  }
});

Alan	Gönderildiği ad	Notlar
`image_base64`	`signature_image`	PNG, JPEG veya WebP; çözülmüş hâliyle yaklaşık 150 KB’a kadar.
`mime_type`	`signature_mime_type`
`signer_name`, `signer_email`, `signer_phone`, `signer_id_number`	aynı adlar	Bir onay token’ı kefil olmadığı sürece, imzalayanın kendisi hakkında beyan ettikleri.
`declaration_text`	`declaration_text`	Kişinin kabul ettiği cümle (en fazla 1000 karakter).
`input_type`	`input_type`	`touch`, `mouse` veya `pen`.
`stroke_count`, `drawing_duration_ms`, `strokes_data`	aynı adlar	Çizim telemetrisi.
`screen_resolution`	`screen_resolution`

Bunların tümü metadata içinde değil, isteğin üst düzey alanları olarak gönderilir. otp_verified / otp_reference alanları tarayıcıdan kabul edilmez; yalnızca sunucudan sunucuya (S2S) rotada veya bir onay token’ı aracılığıyla dikkate alınır.

Burada “basit elektronik imza” ne anlama gelir

Bu şekilde oluşturulan bir kayıt basit elektronik imzadır: belirli bir doküman sürümüne eklenen ve imzalayanın imzalamak için kullandığı elektronik biçimdeki veriler (çizilen görüntü, beyan, teknik bağlam). Gelişmiş veya nitelikli elektronik imza (Türkiye’de 5070 sayılı Kanun kapsamındaki adıyla “güvenli elektronik imza”) değildir — imzalayana sertifika düzenlenmez ve HashEntry imzalayanın kimliğini doğrulamaz.

Delilin gösterdikleri:

hangi doküman sürümünün (içerik hash’i ile), ne zaman, hangi IP adresinden ve user agent’tan, hangi beyan edilmiş imzalayan bilgileriyle onaylandığı;
kaydın yazıldığı andan beri değiştirilmediği (bkz. Delilleri çevrimdışı doğrulama);
kimliğin ne kadar güçlü desteklendiği, identity_assurance alanında:

Değer	Anlamı
`self_declared`	İmzalayan bilgileri tarayıcıdan geldi. Kimse bunları doğrulamadı.
`tenant_attested`	Backend’iniz, tek kullanımlık bir onay token’ıyla veya sunucudan sunucuya (S2S) rotada tamamlanmış bir OTP kontrolünü beyan ederek kişiye kefil oldu. Güvence size aittir: HashEntry, bunu HashEntry’nin kontrol ettiğini değil, sizin teyit ettiğinizi kaydeder.

Basit elektronik imzanın belirli bir sözleşme için yeterli olup olmadığı, uygulanacak hukuka ve işlemin türüne bağlıdır; bazı işlemler belirli bir şekil şartı gerektirir. Hangi düzeye ihtiyacınız olduğunu hukuk danışmanınıza sorun.

Doküman sürümü değiştiğinde

Sunucu 409 CONFIG_OUTDATED yanıtını verirse SDK, dokümanın aktif sürümünü yeniden okur:

değişmemişse (sunucunun önbelleği soğuktu) → aynı istek bir kez daha gönderilir;
değişmişse → onay yeniden gönderilmez. Sonuç success: false ve error.code = "DOCUMENT_VERSION_CHANGED" olur ve document:error tetiklenir.

İkinci durumda dokümanı yeniden gösterin (kişi yeni sürümü görmemiştir) ve yeni bir onay alın — token kullanıyorsanız yeni bir token ile.

Sonuçlar, event’ler ve hatalar

CMP.on('document:approved', ({ slug, version, consentId }) => {});
CMP.on('document:rejected', ({ slug, version }) => {});
CMP.on('document:error',    ({ slug, version, code, status, message }) => {});

`error.code`	Ne yapmalı
`MODULE_LOAD_FAILED`	Modül dosyası yüklenemedi (ağ, reklam engelleyici, CSP). Yeniden denemek için tekrar çağırın.
`DOCUMENT_NOT_FOUND`, `VERSION_NOT_FOUND`	Slug’ı, dokümanın siteye bağlı olduğunu ve istenen dilde aktif bir sürümünün bulunduğunu kontrol edin.
`APPROVAL_TOKEN_REQUIRED`	Backend’inizde bir token üretin ve iletin.
`APPROVAL_TOKEN_INVALID`, `APPROVAL_TOKEN_CONFLICT`	Yeni bir token üretin; imzalayan alanlarının token ile eşleştiğinden emin olun.
`DOCUMENT_VERSION_CHANGED`	Dokümanı yeniden gösterin.
`CONFIG_OUTDATED`	Verdiğiniz sürüm aktif değil ve yeniden kontrol edilemedi.
`NETWORK_ERROR`, `TIMEOUT`, `RATE_LIMIT_EXCEEDED`, `QUEUE_OVERLOADED`	Geçici. Kişinin yeniden denemesine izin verin.
`VALIDATION_ERROR` ve boyut hataları (`SIGNATURE_IMAGE_TOO_LARGE`, `CUSTOM_DOCUMENT_TOO_LARGE`, …)	İsteği düzeltin.

Bir onayı yalnızca result.success === true olduğunda verilmiş sayın. result.consent_token değerini saklayın: sonraki doğrulama ve delil dışa aktarımı için kaydı tanımlar.