API entegrasyonu

Chaindoc'un REST API'si sayesinde belge iş akışlarını otomatikleştirebilir, imzalar toplayabilir ve olayları gerçek zamanlı senkronize edebilirsiniz. Dürüst olmak gerekirse, burada nasıl başlayacağınızı, temel kavramları ve yaygın entegrasyon desenlerini bulacaksınız.

API ile neler yapabilirsiniz

API, Chaindoc'un yaptığı her şeye programatik erişim sunar: belge yükleyin, imza istekleri oluşturun, ekipleri yönetin ve webhook'lar aracılığıyla olayları dinleyin. Bu, web uygulamasını çalıştıran API'nin aynısıdır.

Üç farklı entegrasyon yolu

Stack'inize uyanı seçin. Pratikte, çoğu üretim uygulaması backend'de Server SDK ve frontend'de Embed SDK kullanır.

• REST API — doğrudan HTTP istekleri, herhangi bir dilde çalışır. Maksimum esneklik.
• Server SDK — otomatik yeniden deneme ve hata işleme ile type-safe Node.js wrapper (`@chaindoc_io/server-sdk`)
• Embed SDK — kullanıcıların sitenizden ayrılmadan imza arayüzüne erişmesini sağlar (`@chaindoc_io/embed-sdk`)

SDK'ları henüz kurmadıysanız, kurulum kılavuzu React, Vue, Angular ve Next.js için npm kurulumunu kapsar.

Hızlı örnek

İşte aynı "belge oluştur" çağrısının üç farklı versiyonu. SDK versiyonu en özlü olsa da, ham REST çağrısı tam olarak tel üzerinde ne olduğunu gösterir.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Kimlik doğrulama

Her istek, Authorization header'ında bir API anahtarı gerektirir:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

İki anahtar türü vardır ve bunları karıştırmak en yaygın entegrasyon hatasıdır:

• Public keys (`pk_`) — salt okunur, frontend kodu için güvenli
• Secret keys (`sk_`) — tam okuma/yazma, sadece backend. Bunları asla istemci tarafı kodunda açığa çıkarmayın.
• Her ikisi de test (`_test_`) ve canlı (`_live_`) varyantlarında gelir. Test anahtarları sandbox'a erişir.

Hız limitleri

API, hız limiti bilgisini yanıt header'larında döndürür. Sınırı aştığınızda 429 yanıtı alırsınız. Geri çekilin ve yeniden deneyin.

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Genel endpoint'ler: 10 saniyede 3 istek
• Medya yükleme: 10 saniyede 3 istek
• Okuma işlemleri: 60 saniyede 10 istek
• İmza oluşturma: 3 saniyede 20 istek

Server SDK, üstel geri çekilme ile otomatik olarak yeniden dener. Ham HTTP kullanıyorsanız, kendi yeniden deneme mantığınızı uygulayın.

Hata işleme

Hatalar, durum kodu, mesaj ve (doğrulama hataları için) özel alan sorunlarının bir listesiyle JSON olarak geri döner:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Yaygın durum kodları: 400 (kötü istek), 401 (geçersiz anahtar), 403 (plan API içermiyor), 404 (bulunamadı), 429 (hız limiti), 500 (sunucu hatası). 5xx hataları için geri çekilme ile yeniden deneyin.

Yaygın entegrasyon desenleri

Tam imza akışı (gömülü)

En yaygın desen: bir belge yükleyin, imzalar için gönderin ve imza UI'sini uygulamanızın içinde gösterin.

Hızlı başlangıç kılavuzu bu akışın tam kodunu içerir.

E-posta tabanlı imza (gömme yok)

İşin aslı, imzacılar uygulamanızı kullanmıyorsa `embeddedFlow: false` ayarlayın. Chaindoc onlara imza linki içeren bir e-posta gönderir. İmzaladıklarında hâlâ webhook bildirimleri alırsınız.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // İmzacılar e-posta linkleri alır
  message: 'Please review and sign this document',
});

Toplu belge işleme

Toplu içe aktarımlar için dosyalarınız arasında dolaşın ve her birini yükleyin. Yine de hız limitlerine dikkat edin. Yüzlerce belge işliyorsanız, istekler arasında küçük bir gecikme ekleyin veya SDK'nın yerleşik yeniden deneme mantığını kullanın.

const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

KYC entegrasyonu

Yüksek güvenlikli iş akışları için, imzalamadan önce kimlik doğrulaması talep edin. Chaindoc, KYC için Sumsub ile entegre olur. İmza isteğinde `isKycRequired: true` ayarlayın ve imzacılar imza atmadan önce kimlik doğrulamasından geçecektir.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // İsteğe bağlı: önceden doğrulanmış
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

API ile erişim kontrolü

Belge izinlerini programatik olarak ayarlayabilirsiniz. Belirli e-posta adreslerine veya ekip rollerine erişimi kısıtlayın:

await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

En iyi uygulamalar

• API anahtarlarını ortam değişkenlerinde saklayın. Asla versiyon kontrolüne commit etmeyin.
• Geliştirme için test anahtarlarını (`sk_test_`) kullanın. Canlı anahtarlar (`sk_live_`) üretime erişir.
• 429 yanıtları için üstel geri çekilme uygulayın. SDK bunu otomatik olarak yapar.
• Tekrar saldırılarını önlemek için webhook imzalarını HMAC ile doğrulayın.
• Belgeleri oluşturmadan önce dosyaları yükleyin. API, yükleme adımından medya ID'sine ihtiyaç duyar.
• Liste döndüren endpoint'ler için pagination kullanın. Her şeyi bir kerede çekmeyin.
• Canlıya geçmeden önce güvenlik kılavuzunu kontrol edin.

Örnek kullanım senaryoları

Ekiplerin API ile oluşturduğu birkaç gerçek dünya deseni:

• E-ticaret — yüksek değerli siparişler için satın alma anlaşmalarını otomatik oluşturun ve checkout'ta imza için gönderin
• İK onboarding — şablonlardan istihdam sözleşmeleri oluşturun ve başlangıç tarihlerinde yeni çalışanlara gönderin
• CRM entegrasyonu — Salesforce veya HubSpot anlaşma kayıtlarından imza isteklerini tetikleyin
• Belge arşivleme — mevcut depolama sisteminizdeki belgelere blockchain doğrulaması ekleyin

Sıradaki adımlar

• API dokümantasyonu — istek/yanıt örnekleriyle tam endpoint referansı
• SDK'lar — framework'e özgü kılavuzlarla Server SDK ve Embed SDK
• Webhook'lar — gerçek zamanlı olay bildirimlerini ayarlayın
• Hızlı başlangıç — 10 dakika içinde ilk entegrasyonunuzu çalıştırın
• Kurulum — desteklenen tüm framework'ler için npm kurulumu