DijiImza — Biyometrik İmza Entegrasyonu

→ Entegrasyon Akışı

1 Oturum Açın — PDF Gönderin

POST https://imza.digiimza.com/api/v1/signature-sessions

İstek alanları

* document_base64 veya document_url'den yalnızca biri gönderilir.

signature_boxes — İmza Kutusu Koordinatları

PDF üzerinde imzanın görüneceği alanları tanımlar. Birden fazla sayfa veya alan için dizi olarak gönderin. Koordinatlar PDF point birimidir (başlangıç: sol üst köşe).

// Tek kutu — tek sayfa
"signature_boxes": [
  { "page": 1, "x": 72, "y": 650, "width": 180, "height": 60 }
]

// Birden fazla sayfa / alan
"signature_boxes": [
  { "page": 1, "x": 72,  "y": 650, "width": 180, "height": 60 },
  { "page": 3, "x": 100, "y": 720, "width": 200, "height": 70 }
]

Örnek istek

pythonimport base64, requests, uuid

with open("sozlesme.pdf", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

r = requests.post(
    "https://imza.digiimza.com/api/v1/signature-sessions",
    headers={
        "Authorization":   "Bearer <API_ANAHTARINIZ>",
        "Content-Type":    "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "document_base64":      b64,
        "signer_name":          "Ahmet Yılmaz",
        "external_document_id": "SOZLESME-001",
        "signature_boxes": [
            { "page": 1, "x": 72, "y": 650, "width": 180, "height": 60 }
        ],
    }
)
session_id = r.json()["session_id"]

Başarılı yanıt

json{
  "session_id":      "d8ba41a6-9853-464d-8dad-cf64ab0f6867",
  "status":         "awaiting_signature",
  "document_sha256": "846864d5...",
  "expires_at":      "2026-09-17T12:30:00+00:00"
}

2 iframe'i Sayfanıza Ekleyin

session_id'yi sunucu tarafında render edin ve src adresi olarak verin:

html<iframe
  src="https://imza.digiimza.com/biometric-sign/{{ session_id }}"
  style="width: 100%; height: 360px; border: none; border-radius: 8px;"
  allow="camera; microphone"
></iframe>

Kullanıcı bu alanda imzasını çizer ve Onayla butonuna basar. Kalem, dokunmatik ve mouse desteklenir.

3 İmzayı Dinleyin

İmza tamamlandığında DijiImza iframe'i sayfanıza postMessage gönderir. Aşağıdaki dinleyiciyi ekleyin:

javascriptwindow.addEventListener('message', (event) => {
  // Güvenlik: sadece DijiImza'dan gelen mesajları işleyin
  if (event.origin !== 'https://imza.digiimza.com') return;

  switch (event.data?.type) {

    case 'DIJIIMZA_COMPLETE':
      // İmza başarıyla tamamlandı
      // event.data → { session_id, signature_id, point_count, result_sha256 }
      imzaTamamlandi(event.data.session_id);
      break;

    case 'DIJIIMZA_ERROR':
      // Hata oluştu
      console.error(event.data.code, event.data.message);
      break;

    case 'DIJIIMZA_EXPIRED':
      // Oturum süresi doldu (30 dakika)
      alert('Süre doldu, lütfen tekrar deneyin.');
      break;
  }
});

4 İmzalı PDF'i İndirin

GET https://imza.digiimza.com/api/v1/signature-sessions/{session_id}/document

DIJIIMZA_COMPLETE aldıktan sonra sunucunuzdan çağırın:

pythonr = requests.get(
    f"https://imza.digiimza.com/api/v1/signature-sessions/{session_id}/document",
    headers={"Authorization": "Bearer <API_ANAHTARINIZ>"}
)
with open("imzali_sozlesme.pdf", "wb") as f:
    f.write(r.content)

✦ Tam Entegrasyon Örneği

html<!-- 1. Backend'de session aç, session_id'yi template'e aktar -->

<!-- 2. iframe -->
<iframe id="imza-alani"
  src="https://imza.digiimza.com/biometric-sign/{{ session_id }}"
  style="width:100%;height:360px;border:none;border-radius:8px"
></iframe>

<!-- 3. postMessage dinleyici -->
<script>
window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://imza.digiimza.com') return;

  if (event.data?.type === 'DIJIIMZA_COMPLETE') {
    // Kendi backend'inize bildir
    await fetch('/imza-tamamlandi', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ session_id: event.data.session_id })
    });

    document.getElementById('imza-alani').style.display = 'none';
    alert('İmzanız alındı!');
  }
});
</script>

! Yaygın Hatalar