Server-to-Server (REST API) Entegrasyonu

Müşterilerinize kendi özel arayüzlerinizi (bir mobil uygulama içi sözleşme ekranı veya tamamen sizin tasarladığınız bir web onay deneyimi) sunuyorsanız, yasal onayı kendi Backend (sunucu) sisteminizde alıp, HashEntry Consent Log sistemine Backend’den Backend’e aktarabilirsiniz.

Doğrulama (Authentication)

API istekleri X-API-Key HTTP başlığı üzerinden HashEntry panelinden aldığınız size özel (Site) API anahtarı ile yapılmalıdır.

HMAC İstek İmzalama

Tüm POST istekleri, istek bütünlüğü ve tekrar koruması için HMAC-SHA256 ile imzalanmalıdır. JS SDK bunu otomatik yapar; sunucu tarafı entegrasyonlarda imzalamayı kendiniz uygulamanız gerekir.

Gerekli Başlıklar

Başlık	Açıklama
X-API-Key	Site API anahtarınız
X-Signature	Canonical isteğin HMAC-SHA256 imzası
X-Timestamp	Unix zaman damgası (saniye) — sunucu zamanından ±300s içinde olmalı
X-Nonce	İstek başına benzersiz UUID — tekrar saldırılarını önler

İmzalama Algoritması

1. timestamp = anlık Unix zaman damgası (saniye)
2. nonce = rastgele UUID
3. bodyHash = SHA-256(istek gövdesi JSON dizesi)
4. canonical = "{METHOD}\n{PATH}\n{timestamp}\n{nonce}\n{bodyHash}"
5. signature = HMAC-SHA256(canonical, apiKey)

Örnek (Node.js)

const crypto = require('crypto');

const apiKey = 'he_live_xxx';
const body = JSON.stringify({ consent_type: 'cookie_consent', decision: 'accept', ... });
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');

const canonical = `POST\n/tool/v1/consents\n${timestamp}\n${nonce}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', apiKey).update(canonical).digest('hex');

// Başlıklar:
// X-API-Key: he_live_xxx
// X-Signature: {signature}
// X-Timestamp: {timestamp}
// X-Nonce: {nonce}

S2S Doğrulama (Server-to-Server)

Otomatik backend entegrasyonları için, API anahtarı doğrulamasını JWT Bearer token’ları ile birleştiren S2S Auth akışını kullanabilirsiniz.

Nasıl Çalışır

1. HashEntry Paneli üzerinden api_user rolünde bir üye oluşturun (Ayarlar → Ekip → Davet Et)
2. API kullanıcısı POST /api/v1/auth/login ile JWT token alır
3. S2S isteklerinde her iki başlığı da ekleyin:

X-API-Key: he_live_xxx
Authorization: Bearer {jwt_token}

S2S Endpoint’leri

Metot	Endpoint	Açıklama
POST	/tool/v1/s2s/consents	Tekil onay kaydı
POST	/tool/v1/s2s/consents/batch	Toplu onay kaydı
GET	/tool/v1/s2s/consents/export	Onay kayıtlarını dışa aktarım

Not: api_user rolü yalnızca S2S API erişimine izin verir — bu rol ile panel girişi yapılamaz.

Onay (Consent) Kaydetme

Sisteminizde kullanıcının belirlediği işlemleri (çerez onayı, sözleşme onayı vs.) kalıcı ve zaman damgalı olarak kaydetmek için kullanılır.

Endpoint: POST https://system.hashentry.com/tool/v1/consents

Gerekli Başlıklar:

Content-Type: application/json
X-API-Key: SİZİN_SİTE_API_ANAHTARINIZ
X-Signature: {hmac_imzası}
X-Timestamp: {unix_zaman_damgası}
X-Nonce: {benzersiz_uuid}

Senaryo 1: Özel Çerez (Cookie) Onayı İsteği (JSON)

Eğer çerez izinlerini kendi özel ekranınız ile aldıysanız:

{
  "consent_type": "cookie_consent",
  "decision": "accept",
  "document_version_id": "cerez-politikasi-versiyon-uuidsi",
  "visitor_region": "tr",
  "compliance_framework": "kvkk",
  "metadata": {
    "categories": {
      "necessary": true,
      "analytics": true,
      "marketing": false
    }
  }
}

Senaryo 2: Sipariş/Doküman Onayı İsteği (JSON)

Örneğin bir e-ticaret siteniz var ve kullanıcı “Siparişi Tamamla” demeden önce “Mesafeli Satış Sözleşmesi’ni okudum ve onaylıyorum” kutucuğunu işaretledi:

{
  "consent_type": "document_approval",
  "decision": "accept",
  "document_version_id": "mesafeli-satis-sozlesmesi-versiyon-uuidsi",
  "ip_address": "192.168.1.5",
  "user_agent": "Mozilla/5.0 ...",
  "metadata": {
    "order_id": "ORD-54321",
    "customer_no": "CUST-999"
  }
}

Başarılı Yanıt Beklentisi (201 Created)

{
  "message": "Consent kaydedildi",
  "data": {
    "consent_token": "ct_1234abc...",
    "proof_hash": "sha256:abcd12...",
    "created_at": "2026-03-27T14:00:00+03:00"
  }
}

Burada dönen proof_hash, kullanıcının yasal geçerli onay kaydının değiştirilemez kanıtıdır (SHA-256).

Gelişmiş Özellikler

Server-to-Server entegrasyonda aşağıdaki yetenekleri kullanabilirsiniz:

• Batch (Toplu) Aktarım: Eğer sisteminiz anlık olarak API isteği yapamıyorsa (örn. yoğun trafiğe sahip offline-first uygulamalar), aldığınız onayları biriktirip POST /tool/v1/consents/batch ile toplu olarak HashEntry’ye gönderebilirsiniz.
• Aktif Doküman Sorgulama: Kullanıcınıza sunacağınız sözleşme metnini veya HTML çıktısını her zaman en güncel halinde tutmak için GET /tool/v1/documents/{slug}/active endpoint’ini çağırabilirsiniz. Müşteri bir dokümanı güncellediğinde uygulamanız her zaman en güncel sürümün metni ile onayı isteyecektir.