eIDAS elektronik imza API'si — Certyneo Developers

curl https://api.certyneo.com/v1/envelopes \ -H "Authorization: Bearer $CERTYNEO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Contrat de prestation", "documents": [{"file_url": "https://your.app/contract.pdf"}], "recipients": [{"email": "client@example.com", "name": "Jane Doe"}], "webhook_url": "https://your.app/webhooks/sign" }'

import Certyneo from '@certyneo/sdk'; const client = new Certyneo({ apiKey: process.env.CERTYNEO_API_KEY }); const envelope = await client.envelopes.create({ title: 'Contrat de prestation', documents: [{ file_url: 'https://your.app/contract.pdf' }], recipients: [{ email: 'client@example.com', name: 'Jane Doe' }], }); console.log(envelope.sign_url); // ready to share with the signer

Webhooks Gerçek zamanlı tepki göster

Altı olay (envelope.sent, viewed, signed, completed, declined, expired) HMAC imzası ile kontrol edilebilir ve otomatik olarak tekrar dene.

envelope.completed

{
  "event": "envelope.completed",
  "envelope_id": "env_3a2f...",
  "signed_at": "2026-05-25T14:32:18Z",
  "evidence_url": "https://api.certyneo.com/v1/envelopes/env_3a2f.../audit-trail.pdf",
  "signers": [
    { "email": "client@example.com", "signed": true, "ip": "82.x.x.x" }
  ]
}

Her payloadun HMAC SHA-256 imzası sunucu tarafında doğrulama yapın.

Başarısızlık durumunda otomatik yeniden deneme: 24 saat içinde 5 deneme ve katlanarak yedekleme.

Ana sayfadan gözlenebilir olay günlüğü: her girişim, geri gönderilen HTTP durumu, vücut görüntüleri.

Webhook URL'si, projede üstü kapalı veya küresel olarak yapılandırılabilir.

Neden özel bir e-imza API?

Elektronik imzanın ürününüze dahil edilmesi kolay değildir. Yasal uyum güvenceleri (eIDAS), teknik güvenilirlik (gerçekten gelen webhooklar) ve veri egemenliği (bulut yasasını önlemek için Avrupa barındırma) gerektirir. Certyneo API üçünü de kapsar.

Geliştiriciler tarafından ve onlar için tasarlanmıştır ve modern REST sözleşmelerini takip eder: Kürsör tabanlı sayfalama, idempotency anahtarları, URL versiyonlama, OpenAPI 3.1 istemcilerinizi otomatik olarak oluşturmak için.

Geliştiricilere açıklanan eIDAS uyumluluğu

eIDAS yönetmeliği üç imza seviyesini tanımlar: basit (SES), ileri (AES) ve nitelikli (QES). Certyneo API, bir müracaat seviyesini `imza_seviye` alanı aracılığıyla seçmenizi sağlar. Varsayılan değer AES'dir (B2B vakalarının %95'inde yeterlidir). QES, elle yazılmış imza ile sıkı yasal eşdeğerlik gerektiren belgeler için kullanılabilir (noter belgesi, kamu hizmeti).

Teknik olarak AES, güçlü bir imzacı kimliği (ortak olarak SMS ile OTP, opsiyonel olarak KYC video) ve zamanlı bir denetim yolu gerektirir. QES, AB nitelikli bir TSP tarafından verilen nitelikli bir sertifika ekler. Tüm bunlar API tarafından yönetilir.

Önerilen entegrasyon mimarisi

En yaygın entegrasyon örneği şu akışı izler:

Arka uçunuz, POST /v1/envelopes'i çağırıp, kullanıcının gözüne sunulacak bir sign_url alır.
Kullanıcıyı sign_url'e yönlendiriyorsunuz veya iframe'e gömüyorsunuz (pro planı üzerinden markanızla).
İmza tamamlandıktan sonra, Certyneo webhook'unuzu envelope.completed olayıyla çağırır.
Veritabanınızı güncelleyip kullanıcıya bildirirsiniz (e-posta, uygulama içi, vb.).

Ücretsiz sınırsız kum kutusu

Sandbox ortamı ücretsizdir ve sınırsızdır. Tüm üretim özellikleri mevcuttur, ancak imzaların yasal değeri yoktur (PDF SANDBOX olarak işaretlenmiştir). Otomatik testler, müşteri demoları, yerel geliştirme için uygundur. Sandbox anahtarları prod anahtarlarından farklıdır, ikisi arasında tam izole.

DocuSign veya Yousign'den göç

Eğer zaten DocuSign veya Yousign birleştirme varsa, API haritası doğrudan: zarflar → zarflar, alıcılar → alıcılar, durum webhooks → durum webhooks. Göç rehberi, uç nokta eşdeğerliklerini uç nokta olarak belgelemektedir. Tam bir göç için 1-3 gün bekleyin, eğer iç bir sargı kullanıyorsanız çok daha az.

Soruları sormak API

API'nin sınır hatası nedir?

1000 soru dakikada varsayılan olarak, yüksek kullanımlar için talep üzerine artan (fabrikalar, çoklu alıcı platformlar). Her yanıt üzerindeki X-RateLimit-Remaining başlığı kalan kotayi gösterir. Aşılsa, API Retry-After ile 429 i iade eder.

API'nin fiyatı ne kadar?

Sandbox ücretsizdir ve sınırsızdır. Üretim, minimum abonelik olmadan, abonelik ücretine (AES imzası, hacimle azalma ile 0,40 €'dan itibaren) çalışır. Girişim planı, güçlendirilmiş bir SLA, IP beyaz listesi ve özel bir teknik hesap içerir.

ALS var mı?

İşletme ve Kurumsal planlarda %99.95 zaman aşımı (yılda en fazla 4 saat zaman aşımı). Durum geçmişi ile kamu durumu sayfası: status.certyneo.com. Kurumsal plan SLA'ya uymadığınızda otomatik kredi içerir.

Hangi kimlik doğrulama yöntemini kullanıyorsunuz?

Bearer token (API anahtarı) Authorization başlığında. Anahtarlar anında iptal edilebilen, panodan döndürülebilir. OAuth (çok taraflı platform) entegrasyonları için, Kurumsal planda bir OAuth 2.0 Müşteri Kimlik bilgisi sunuyoruz.

Bir webhook'un HMAC imzalarını nasıl doğrulayabilirim?

Her webhook, gizli webhook ile imzalanan, payload'un SHA-256 HMAC'ını içeren bir X-Certyneo-Signature başlığı içerir. Sunucu tarafında, HMAC'ı yeniden hesaplayın ve sürekli olarak karşılaştırın (zaman güvenli karşılaştırma). Resmi SDK bunu webhook.verify(payload, imza, gizli üzerinden otomatik olarak yapar.

SDK'lar açık kaynak mı?

Evet. Node, Python ve Ruby SDK'ları GitHub'da MIT lisanslı. Onları forker, katkıda bulunabilir veya sadece denetleyebilirsiniz. İkili dosyalar npm, PyPI ve RubyGems'de @certyneo / certyneo isim alanı altında yayınlanır.

Kayıt olmadan test edebilir miyim?

Evet, API belgelerindeki etkileşimli örnekler üzerinden: /developers/playground. Burada sorular, anahtar gereksiz paylaşılan bir kum sandığı örneğine yönlendirilir. Ciddi kullanım için ücretsiz bir geliştirme hesabı oluşturun (sınırsız kum sandığı).

Geliştirici için elektronik imza API'si

REST + OpenAPI 3.1

Güvenilir Webhooklar

Yerel eIDAS uyumluluğu

Gecikme < 200 ms

5 dakika içinde kalkışa başlıyor.