API Elektronik İmza: Geliştirici REST Rehberi 2026

Giriş

REST elektronik imza API'sini entegre etmek 2026'da geliştirme ekipleri için tartışılmaz bir önkoşul haline gelmiştir. Avrupa'daki işletmelerin %73'ünden fazlasının en az bir sözleşme işlemini dijitalleştirmiş olmasıyla (kaynak: IDC European Digital Transformation Report 2025), güçlü teknik entegrasyonlara olan talep patlama yaşamaktadır. Bir LegalTech SaaS, ERP veya İK platformu geliştiriyor olsanız da, elektronik imza API'sini nasıl tüketileceğini anlamak — OAuth2 kimlik doğrulama, webhook yönetimi, eIDAS uyumluluğu — doğrudan belge akışlarınızın kalitesi ve yasal değerini belirler. Bu REST geliştirici rehberi sizi adım adım eşlik eder: mimari, kimlik doğrulama, belge yaşam döngüsü, gerçek zamanlı webhooks ve güvenlik en iyi uygulamaları.

---

Elektronik İmza REST API'sinin Mimarisi

RESTful İlkeler ve Endpoint Yapısı

İyi tasarlanmış bir elektronik imza REST API'si, açıkça tanımlanmış kaynaklar ve anlamsal HTTP fiillerine dayanır. Temel kaynaklar genellikle şunlardır:

• `/documents` — PDF/DOCX belgelerin yüklenmesi, yönetimi ve alınması
• `/signature-requests` — imza isteklerinin oluşturulması ve yönetimi
• `/signatories` — imzalayanlar ve kimliklerinin yönetimi
• `/audit-trails` — sertifikalı denetim günlüklerinin alınması
• `/templates` — yeniden kullanılabilir belge şablonlarının yönetimi

Her kaynak standart CRUD endpoint'lerini (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) sunar ve normalleştirilmiş HTTP kodları ile JSON yanıtlarını döndürür: `200 OK`, `201 Created`, `400 Bad Request`, `401 Unauthorized`, `422 Unprocessable Entity`, `429 Too Many Requests`.

Sıklıkla göz ardı edilen kritik bir yön: sayfalandırma yönetimi. Olgun API'ler offset/limit yerine cursor-based kalıbını kullanır, bu da binlerce imzalı belge üzerinde bile istikrarlı performans garantisi verir. Hedef API'nin `X-Next-Cursor` başlığını veya body'de `next_page_token` alanını açığa çıkarıp çıkarmadığını doğrulayın.

API Sürümlendirmesi ve Geriye Doğru Uyumluluk

Sürümlendirme, entegratörler için önemli bir dikkat noktasıdır. 2026'da baskın iki yaklaşım şunlardır:

1. URL Sürümlendirmesi: `https://api.certyneo.com/v2/signature-requests` — okunabilir, CDN tarafından önbelleklenebilir, B2B API'ler için önerilir.
2. Başlık Sürümlendirmesi: `Accept: application/vnd.certyneo.v2+json` — mimarilerde daha temiz ama daha az görünür.

En az 12 aylık amortisman politikasına bağlı kalan ve genel bir changelog yayınlayan sağlayıcıları tercih edin. Duyurulmayan bir uyumluluk kırılması imza akışınızda doğrudan yasal sonuçlar doğurabilir (imzasız sözleşmeler, kaçırılan süreler).

---

OAuth2 Kimlik Doğrulaması ve API Çağrı Güvenliği

OAuth2: client_credentials vs authorization_code Akışları

Kimlik doğrulama, tüm elektronik imza API entegrasyonlarının temelini oluşturur. Geliştiriciler için en ilgili iki OAuth2 akışı şunlardır:

Client Credentials Akışı (M2M — Machine to Machine): ``` POST /oauth/token Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET &scope=documents:write signature_requests:write audit_trails:read ``` Bu akış, hiçbir son kullanıcının kimlik doğrulamaya dahil olmadığı sunucu-arası entegrasyonlar için idealdir (toplu işlem, sözleşme otomasyonu).

Authorization Code Akışı + PKCE: uygulamanız bir tanımlanmış son kullanıcının adına hareket ettiğinde önerilir. PKCE (Code Exchange İçin İspat Anahtarı) RFC 7636'dan beri zorunludur ve kesme saldırılarına karşı koruma sağlar.

Temel güvenlik önerileri:

• `client_secret`'i bir vault'ta saklayın (HashiCorp Vault, AWS Secrets Manager) — asla şifrelenmemiş ortam değişkeninde değil
• Otomatik token rotasyonu uygulayın ve sona erme 60 saniye öncesinde bir buffer ekleyin
• Granüler scopes kullanın: yalnızca kesinlikle gerekli izinleri talep edin

API Anahtarları Yönetimi ve Rate Limiting

Hafif entegrasyonlar veya test ortamları için bazı API'ler statik API anahtarları (Bearer Token) sunar. Bunları üretikte kullanıyorsanız sistematik olarak uygulayın:

• Üç aylık anahtar rotasyonu
• IP kısıtlaması (whitelist)
• SIEM aracılığıyla anormal çağrılar için izleme

Rate limiting kaçınılmaz bir gerçektir: imza API'leri genellikle plana bağlı olarak dakika başına 100 ila 1000 çağrı arasında sınırlandırırlar. Jitterli üstel geri alma mekanizması uygulayın: ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` Döndürülen `Retry-After` başlığına `429 Too Many Requests` ile dikkatle uyun.

---

İmza İsteğinin API Aracılığıyla Yaşam Döngüsü

İmza İsteğinin Oluşturulması ve Yapılandırılması

Bir imza isteğinin API aracılığıyla yaşam döngüsü bir durum şemasını izler (`draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`). Burada ayrıntılı teknik adımlar verilmiştir:

Adım 1 — Belge Yükleme: ``` POST /v2/documents Content-Type: multipart/form-data

[email protected] ``` Yanıt: `{ "document_id": "doc_a1b2c3", "checksum_sha256": "e3b0c442..." }`

Adım 2 — İstek Oluşturma: ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Q3 2026 Hizmet Sağlama Sözleşmesi", "signatories": [ { "email": "[email protected]", "first_name": "Marie", "last_name": "Dupont", "signature_level": "advanced", "fields": [{ "type": "signature", "page": 3, "x": 120, "y": 680 }] } ], "expiry_date": "2026-06-05T23:59:59Z", "reminder_settings": { "enabled": true, "frequency_days": 3 } } ```

Adım 3 — Aktivasyon: `POST /v2/signature-requests/req_x9y8z7/activate`

Aktivasyondan sonra imzalayanlar davetlerini alırlar ve istek `in_progress` durumuna geçer.

İmzalı Belge ve Denetim İzinin Alınması

Durumun `completed` olmasına ulaştığında (webhook aracılığıyla algılanabilir — sonraki bölüme bakın), şunları alın:

``` GET /v2/signature-requests/req_x9y8z7/document/signed → Gömülü elektronik imzalar içeren imzalı PDF (ETSI EN 319 132'ye göre PAdES-B-T)

GET /v2/signature-requests/req_x9y8z7/audit-trail → Sertifikalı denetim günlüğü PDF (RFC 3161 nitelikli zaman damgası) ```

Her zaman her iki dosyayı birlikte GED veya DMS'inizde saklayın. Denetim günlüğü, yasal ihtilaf durumunda karşı kanıttır.

---

Webhooks: Gerçek Zamanlı Olaylar ve Hata Yönetimi

Webhook Yapılandırması ve Güvenliği

Webhooks, entegrasyonunuzu maliyetli polling'den reaktif bir olay mimarisine dönüştürür. Webhook endpoint'inizi yapılandırın:

``` POST /v2/webhooks { "url": "https://uygulamanız.com/hooks/certyneo", "events": [ "signature_request.completed", "signature_request.declined", "signatory.signed", "signature_request.expired" ], "secret": "whsec_your_hmac_secret" } ```

Zorunlu HMAC Güvenliği: gelen her payload'u HMAC-SHA256 imzasını `X-Certyneo-Signature` başlığı ile karşılaştırarak doğrulayın: ```python import hmac, hashlib

def verify_webhook(payload: bytes, secret: str, signature_header: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature_header) ``` Asla standart dize karşılaştırması kullanmayın — zamanlama saldırılarına karşı savunmasız.

İdempotence ve Yeniden Gönderme Yönetimi

Webhook'lar zaman aşımı veya 5xx hataları durumunda yeniden gönderilebilir. İdempotencei zorunlu olarak uygulayın:

1. Her webhook payload'undan benzersiz `event_id`'yi çıkartın
2. Veritabanında bu `event_id`'nin zaten işlenip işlenmediğini kontrol edin
3. Sonsuz yeniden gönderişlerden kaçınmak için hemen `200 OK` döndürün (çoğaltmalar için bile)
4. İş mantığı işlemesini asenkron olarak yönetin (queue: Redis, RabbitMQ, SQS)

Altın kural: webhook endpoint'iniz 5 saniye içinde yanıt vermelidir. Ağır iş mantığı (e-posta gönderme, GED arşivleme, ERP bildirimi) asenkron worker'a devredilmelidir.

İmza seviyeleri hakkında daha derin bilgi için API aracılığıyla mevcuttur, lütfen elektronik imza kapsamlı rehberine bakın ve basit, gelişmiş ve nitelikli imzalar arasındaki farkları öğrenin.

---

Entegrasyon En İyi Uygulamaları ve Performans

Sandbox Ortamları ve Test Stratejisi

Her ciddi elektronik imza API'si, üretimden izole edilmiş bir sandbox ortamı sunar. Bu test stratejisini benimseyin:

• Birim testler: API yanıtlarını mock'layın (Wiremock, MSW) iş mantığınızı ağdan bağımsız olarak doğrulamak için
• Entegrasyon testleri: tam yaşam döngüsünü doğrulamak için sandbox'a karşı çalıştırın (oluşturma → imzalama → alma)
• Yük testleri: çevrimiçi olmadan önce darboğazları belirlemek için eşzamanlı istekler simüle edin
• Chaos testleri: zaman aşımları ve 5xx hataları simüle edin ve retry mantığınızı doğrulayın

Sandbox'ta asla gerçek imzaları veya gerçek imzalayanları test etmeyin. Sandbox'ta oluşturulan elektronik imzaların hiçbir yasal değeri yoktur, ki bu testler için tam olarak istediğiniz şeydir.

İzleme, Gözlemlenebilirlik ve Uyarı

Üretimde entegrasyonunuzu şunlarla enstrüman edin:

• Metrikler: API çağrılarının başarı oranı, p95/p99 gecikmesi, endpoint başına hata oranı
• Dağıtılmış izler: korelasyon için headers'da `trace-id` yayın ve loglarınızı sağlayıcı API loglarıyla ilişkilendirin
• Uyarı: hata oranı %1'i aştığında veya p99 gecikmesi 3 saniyeyi aştığında tetikleyin

Farklı sağlayıcılar tarafından sunulan SLA kullanılabilirliğini (uptime) değerlendirmek için elektronik imza çözümleri karşılaştırmasına bakın — API entegrasyonu sırasında sıklıkla hafife alınan bir kriter.

DocuSign veya YouSign'dan başka bir platforma geçiş yapıyorsanız, DocuSign veya YouSign'dan Certyneo'ya geçiş rehberimiz API geçişinin teknik yönlerini ve mevcut webhook uyumluluğunu kapsar.

Entegrasyonunuzun yatırım getirisini tahmin etmek için API otomasyonundan kaynaklanan verimlilik kazançlarını entegre eden elektronik imza ROI hesaplayıcısını kullanın.

Son olarak imzalanacak belgelerin otomatik üretiminde daha ileri gitmek istiyorsanız, API'mize doğal olarak ara yüz olan AI sözleşme oluşturucumuzu keşfedin.

Elektronik İmza API'sine Uygulanabilir Yasal Çerçeve

Elektronik imza API'sini entegre etmek yalnızca teknik bir sorun değil: editör ve müşterilerinin yasal sorumluluğunu birkaç temel metinde doğrudan etkiler.

Düzenleme eIDAS n°910/2014 ve eIDAS 2.0

Düzenleme (AB) n°910/2014 (eIDAS) Avrupa Birliğinde elektronik imzanın yasal çerçevesini belirler. Üç seviye vardır:

• Basit elektronik imza (SES): düşük riskli eylemler için uygun, minimum yasal değer
• Gelişmiş elektronik imza (AES): imzalayıcıya tek şekilde bağlantılı, imzalayıcının münhasır kontrolü altındaki verilerden oluşturulan — eIDAS madde 26
• Nitelikli elektronik imza (QES): tüm AB'de el yazısı imza ile eşdeğer — eIDAS madde 25 §2

Kademeli uygulaması devam eden eIDAS 2.0 düzenlemesi (Düzenleme AB 2024/1183) ile geliştiricilerin, kimlik doğrulama akışlarında Avrupa Dijital Kimlik Cüzdanları (EUDIW)'nin entegrasyonuna hazırlanması gerekir. Teknik çıkarımlar için eIDAS 2.0 rehberine bakın.

Fransız Medeni Kanunu — Maddeler 1366 ve 1367

Fransız hukukunda Medeni Kanunun 1366. maddesi şöyle belirtir: "elektronik yazı, yazının kağıt üzerinde oluşturulmasıyla aynı kanıtlama gücüne sahiptir; bu, bunun kaynağı olan kişinin düzgün bir şekilde tanımlanabileceği ve belgenin bütünlüğü garantilemek için doğası gereği koşullar altında oluşturulduğu ve korunduğu şartıyla."

1. madde, güvenilir elektronik imzanın şartlarını açıklar: imzalayıcının kimliği ve belge bütünlüğü garantisi. Bu gereksinimler teknik olarak sertifikalı denetim günlüklerinin ve imza sırasında kullanılan kimlik kanıtlarının tutulması zorunluluğuna çevrilir — API'niz tarafından açığa çıkarılması ve saklanması gereken unsurlar.

ETSI EN 319 132 Standartları — PAdES

eIDAS uyumlu PDF imzaları için zorunlu teknik format, PAdES (PDF Advanced Electronic Signatures) olup ETSI EN 319 132 standardı tarafından tanımlanır. API'niz en azından PAdES-B-T imzaları (zaman damgasıyla) ve 10+ yıl arşivleme için PAdES-B-LT veya PAdES-B-LTA geçerliliğini garantileyen imzaları üretmelidir.

GDPR n°2016/679 — İmzalayanlar Verileri

İmza işlemi sırasında toplanan kişisel veriler (ad, soyadı, e-posta, IP adresi, AES/QES için kimlik verileri) GDPR'ye tabi kişisel verilerdir. Veri sorumlusu veya veri işlemecisi olarak yükümlülükleriniz şunları içerir:

• Gerekçelendirilmiş bir veri tutma süresi tanımlayın (genellikle zaman aşımı sürelerine uyumlu: ortak hukukta 5 yıl)
• API aracılığıyla otomatik temizlik mekanizması sağlayın (`DELETE /v2/signature-requests/{id}/personal-data`)
• Tedavi işlemini veri işleme faaliyetleri kaydında belgelendir (GDPR madde 30)
• Sağlayıcınız ile DPA (Veri İşleme Anlaşması) yapın

NIS2 Direktifi ve Hizmet Sürekliliği

NIS2 Direktifi (2022/2555) anlamında temel veya önemli kuruluşlar olarak nitelendirilen yazılım editörleri için, üçüncü taraf API entegrasyonu, dijital tedarik zinciri risk analizine belgelendirilmesi gereken bir bağımlılık oluşturur. Sağlayıcınızdan SOC 2 Type II sertifikası ve ≥ %99,9 kullanılabilirlik SLA'sı talep edin.

Kullanım Senaryoları: Elektronik İmza API'si Pratikte

Senaryo 1 — Bir Endüstriyel KOBİ'de Tedarikçi Sözleşmelerinin Otomasyonu

Yıllık yaklaşık 200 tedarikçi sözleşmesini yöneten bir endüstriyel KOBİ, kağıt alışverişlerini ve bir idari asistanın ayda 2 gün harcayan manual takipleri ortadan kaldırmak istedi. Geliştirme ekibi, elektronik imza REST API'sini doğrudan ERP'lerine aşağıdaki akış aracılığıyla entegre etti:

1. Bir satın alma siparişi ERP'de onaylandığında, otomatik olarak `POST /v2/signature-requests` çağrısı tetiklenir
2. Oluşturulan sözleşme PDF'i yüklenir ve referans tedarikçi kontağına imza isteği gönderilir
3. Webhook `signatory.signed` satın alma siparişinin durumunu gerçek zamanlı olarak günceller
4. İmzalı belge ve denetim günlüğü, ikinci bir API çağrısı aracılığıyla GED'e otomatik olarak arşivlenir

Gözlemlenen Sonuçlar (KPMG/IDC 2024-2025 sektör raporları tarafından sunulan aralık): ortalama imza gecikmesi 8 günden 24 saatten az'a düştü, idari takiplere ayrılan zaman %60-70 oranında tasarruf, sıfır belge kaybı.

Senaryo 2 — Hukuk Danışmanlığı Firmaları İçin LegalTech Platformu

Avukat büroları için (5-30 ortaklar) SaaS yazılım çözümü geliştiren bir editör, kullanıcılarının elektronik imza API'sini entegre etmiştir. Bu, vekalet, avukatlık ücret sözleşmeleri ve dava belgelerini doğrudan ofis arayüzünden imzalanabilir hale getirmektedir.

Seçilen teknik mimari, her avukatın kendi adına istekleri kimlik doğrulaması yapması için OAuth2 Authorization Code + PKCE akışını kullanır. `signature_request.completed` webhook'ları otomatik olarak imzalı belgenin hukuki GED'e dosyaya yerleştirilmesini tetikler.

Editör özellikle API aracılığıyla gelişmiş elektronik imzaların (AES) kullanılabilirliğini değerlendirmiştir — Ulusal Barolar Konseyi önerileri tarafından avukatlık ücret sözleşmeleri için gerekli seviye. İlk entegrasyon için geliştirme süresi kıdemli bir backend geliştiriciyi yaklaşık 3 haftaya alarak %85 test kapsamına ulaştı.

Senaryo 3 — Özel Kliniklerin Bir Grubu İçin Dijital Onboarding

Yaklaşık 600 yatak kapasiteli özel kliniklerin bir grubu, hasta bilgilendirilmiş onamı formlarını ve kabul sözleşmelerini daha önce resepsiyon'da yazdırılan ve el ile imzalanan yapılardan demateryalleştirmeyi planladı — binlerce euros'luk yıllık yazdırma maliyetlerine ve resepsiyon bekleme sürelerine neden olan.

API entegrasyonu hastane bilgi sistemini (HIS) elektronik imza platformuna bağladı. Bir hasta kaydedildiğinde, HIS API'yi çağırarak çok taraflı bir imza isteği (hasta + referans doktor) oluşturur. İmza alanı konumlandırması, otomatik olarak şablon metaverilerinden hesaplanır.

GDPR uyumluluğu, API aracılığıyla program edilmiş otomatik temizlik uygulanmasını (`PATCH /v2/signature-requests` + silme onayı webhook'u) gerektirdi. Medeni Kanun yönetmelikleri tarafından (yetişkinler için 20 yıl, sağlık kanunu madde R. 1112-7'ye göre) tanımlanan yasal tutma sürelerine hizalanmıştır. Ölçülen kazançlar kabul süresi %80 azalmış ve yazdırma ve tarama maliyetlerinde %40 tasarrufa ulaşmıştır.

Sonuç

2026'da REST elektronik imza API'sini entegre etmek birkaç boyutun aynı anda yönetilmesini gerektirir: sağlam RESTful mimari, güvenli OAuth2 kimlik doğrulaması, webhook aracılığıyla olay yönetimi ve eIDAS ve GDPR uyum gereksinimleri. Bu sorunları entegrasyon tasarımında önceden göz önüne alan geliştiriciler, maliyetli yeniden yazımlardan ve önemli yasal risklerden kaçınırlar.

Hatırlanması gereken üç temel sütun: API çağrılarını güvenli hale getirin (OAuth2 + minimal scopes + vault), webhook aracılığıyla olayları asenkron ve etkisiz biçimde işleyin, ve imzalı belgeyi sertifikalı denetim günlüğü ile sistematik olarak arşivleyin.

Certyneo, eIDAS uyumlu, belgeli REST API'sini, ücretsiz sandbox'u ve adanmış geliştirici teknik desteğini sağlar. Certyneo hesabınızı oluşturun sandbox API anahtarınıza erişmek ve entegrasyonunuza hemen başlamak için.