Chaindoc SDK'ları

Chaindoc entegrasyonu için resmi SDK'lar. Tam TypeScript desteği, sıfır bağımlılık ve hem arka uç hem de ön uç uygulamaları için çerçeve bağımsız tasarım.

Kullanılabilir SDK'lar

Sunucu SDK (@chaindoc_io/server-sdk) - Node.js 18+ için arka uç entegrasyonu
Embed SDK (@chaindoc_io/embed-sdk) - Web uygulamaları için ön uç imza arayüzü
Python SDK - Yakında
PHP SDK - Yakında

Sunucu SDK

Sunucu SDK, Chaindoc API için tür güvenli bir Node.js arayüzü sağlar. Belgeleri yönetmek, imza istekleri oluşturmak, dosya yüklemelerini işlemek ve blok zinciri doğrulamasını arka ucunuza entegre etmek için kullanın.

Kurulum

npm install @chaindoc_io/server-sdk

Gereksinimler

Node.js 18 veya üstü (yerel fetch API kullanır) Gizli API anahtarı (sk_live_* veya sk_test_*)

Hızlı Başlangıç

server.ts

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// 1. Initialize the SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 2. Upload a document file
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 3. Create a document
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Contract for consulting services',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

// 4. Create a signature request
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: true,
});

// 5. Create session for frontend SDK
const session = await chaindoc.embedded.createSession({
  email: 'signer@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

console.log('Session ID:', session.sessionId);

Express.js Entegrasyonu

server.ts

import express from 'express';
import { Chaindoc, ChaindocError } from '@chaindoc_io/server-sdk';
import multer from 'multer';

const app = express();
const upload = multer({ storage: multer.memoryStorage() });

const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Upload and create document
app.post('/api/documents', upload.single('file'), async (req, res) => {
  try {
    const file = new Blob([req.file!.buffer], { type: req.file!.mimetype });
    const { media } = await chaindoc.media.upload([file]);

    const doc = await chaindoc.documents.create({
      name: req.body.name,
      description: req.body.description || '',
      media: media[0],
      status: 'published',
      hashtags: req.body.hashtags || [],
      meta: req.body.meta || [],
    });

    res.json({ documentId: doc.documentId });
  } catch (error) {
    if (error instanceof ChaindocError) {
      res.status(error.statusCode || 500).json({ error: error.message });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

// Create embedded session for signer
app.post('/api/signing/session', async (req, res) => {
  try {
    const { email, documentId, signatureRequestId } = req.body;

    const session = await chaindoc.embedded.createSession({
      email,
      metadata: { documentId, signatureRequestId },
    });

    res.json({ sessionId: session.sessionId });
  } catch (error) {
    if (error instanceof ChaindocError) {
      res.status(error.statusCode || 500).json({ error: error.message });
    }
  }
});

app.listen(3000);

Next.js API Rotaları

app/api/signing/create-session/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { Chaindoc, ChaindocError } from '@chaindoc_io/server-sdk';

const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

export async function POST(request: NextRequest) {
  try {
    const { email, documentId, signatureRequestId } = await request.json();

    const session = await chaindoc.embedded.createSession({
      email,
      metadata: { documentId, signatureRequestId },
    });

    return NextResponse.json({
      sessionId: session.sessionId,
      expiresAt: session.expiresAt,
    });
  } catch (error) {
    if (error instanceof ChaindocError) {
      return NextResponse.json(
        { error: error.message },
        { status: error.statusCode || 500 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Hata İşleme

API çağrılarını her zaman try-catch blokları içine alın ve ChaindocError'u özel olarak işleyin:

terminal

import { ChaindocError } from '@chaindoc_io/server-sdk';

try {
  const doc = await chaindoc.documents.create({ /* ... */ });
} catch (error) {
  if (error instanceof ChaindocError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    
    switch (error.statusCode) {
      case 400:
        // Bad request - check parameters
        break;
      case 401:
        // Unauthorized - check API key
        break;
      case 404:
        // Not found
        break;
      case 429:
        // Rate limited - SDK will auto-retry
        break;
    }
  }
}

SDK'yı gömün

Embed SDK, belge imzalama işlevinin web uygulamalarına sorunsuz bir şekilde entegre edilmesini sağlar. Uygulamanız ve Chaindoc arasında güvenli iletişim ile iframe tabanlı bir imzalama akışını yönetir.

Kurulum

npm install @chaindoc_io/embed-sdk

Temel Özellikler

Sıfır çalışma zamanı bağımlılığı Tam TypeScript desteği Çerçeve bağımsız (React, Vue, Angular, Svelte) Hafif: < 10 KB gzipli Güvenli: kaynak doğrulama ve iframe sanal alanı

Temel Kullanım

terminal

import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

// 1. Initialize SDK (once per page)
const chaindoc = new ChaindocEmbed({
  publicKey: 'pk_live_xxxxxxxxxxxxx',
  environment: 'production',
});

// 2. Get session from your backend
const response = await fetch('/api/signing/create-session', {
  method: 'POST',
  body: JSON.stringify({ documentId, signerEmail }),
});
const { sessionId } = await response.json();

// 3. Open signing flow
const instance = chaindoc.openSignatureFlow({
  sessionId,
  
  onReady: () => {
    console.log('Signing interface loaded');
  },
  
  onSuccess: (data) => {
    console.log('Document signed:', data.signatureId);
    instance.close();
  },
  
  onError: (error) => {
    console.error('Signing failed:', error.code, error.message);
  },
  
  onCancel: () => {
    console.log('User cancelled');
    instance.close();
  },
});

React Entegrasyonu

components/SignButton.tsx

import { useCallback, useRef, useEffect } from 'react';
import { ChaindocEmbed, EmbedInstance } from '@chaindoc_io/embed-sdk';

function SignButton({ sessionId }: { sessionId: string }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);
  const instanceRef = useRef<EmbedInstance | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.REACT_APP_CHAINDOC_PUBLIC_KEY!,
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  const handleSign = useCallback(() => {
    if (!sdkRef.current) return;

    instanceRef.current = sdkRef.current.openSignatureFlow({
      sessionId,
      onSuccess: (data) => {
        console.log('Signed!', data.signatureId);
        instanceRef.current?.close();
      },
      onCancel: () => {
        instanceRef.current?.close();
      },
    });
  }, [sessionId]);

  return <button onClick={handleSign}>Sign Document</button>;
}

Vue 3 Entegrasyonu

SignButton.vue

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { ChaindocEmbed, type EmbedInstance } from '@chaindoc_io/embed-sdk';

const props = defineProps<{ sessionId: string }>();

let sdk: ChaindocEmbed | null = null;
let instance: EmbedInstance | null = null;

onMounted(() => {
  sdk = new ChaindocEmbed({
    publicKey: import.meta.env.VITE_CHAINDOC_PUBLIC_KEY,
  });
});

onUnmounted(() => {
  sdk?.destroy();
});

function openSignature() {
  if (!sdk) return;
  
  instance = sdk.openSignatureFlow({
    sessionId: props.sessionId,
    onSuccess: (data) => {
      console.log('Signed!', data.signatureId);
      instance?.close();
    },
    onCancel: () => {
      instance?.close();
    },
  });
}
</script>

<template>
  <button @click="openSignature">Sign Document</button>
</template>

Satır İçi Modu

Modal yerine, imza arayüzünü doğrudan sayfanıza yerleştirin:

terminal

const instance = chaindoc.openSignatureFlow({
  sessionId,
  mode: 'inline',
  container: document.getElementById('signature-container'),
  
  onSuccess: (data) => {
    console.log('Signed!');
  },
});

Tema

Açık veya koyu temalarla görünümü özelleştirin:

terminal

const instance = chaindoc.openSignatureFlow({
  sessionId,
  theme: 'dark',
  // ... other options
});

// Change theme dynamically
instance.changeTheme('light');

Tam İş Akışı Örneği

İşte Server SDK ve Embed SDK'yı birleştiren eksiksiz bir uçtan uca örnek:

1Arka Uç: Belge YükleSunucu SDK'sını kullanarak dosyayı yükleyin ve belgeyi oluşturun

2Arka uç: İmza İsteği OluşturGömülü akış etkinleştirilmiş imza isteği oluşturun

3Arka Uç: Oturum OluşturmaHer imzalayan için gömülü oturum oluşturun

4Ön uç: Embed SDK'yı başlatınSDK'yı genel anahtarla başlatın

5Ön Uç: Açık İmza AkışıOturum kimliği ile imza arayüzünü açın

6Ön Uç: Başarıyı İşlemeİmzalanmış belgeyi işleyin ve kullanıcı arayüzünü güncelleyin

// server.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';

const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Upload & create document
const { media } = await chaindoc.media.upload([pdfFile]);
const doc = await chaindoc.documents.create({
  name: 'Contract',
  description: 'Service agreement',
  media: media[0],
  status: 'published',
  hashtags: ['#contract'],
  meta: [],
});

// Create signature request
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: true,
});

// Create session
const session = await chaindoc.embedded.createSession({
  email: 'signer@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

En İyi Uygulamalar

SDK'yı sayfa/bileşen yaşam döngüsü başına bir kez başlatın
Bileşen bağlantısı kesildiğinde SDK örneğini her zaman yok edin
Tüm geri arama olaylarını (onSuccess, onError, onCancel) işleyin.
API anahtarlarını ortam değişkenlerinde saklayın
Daha iyi tip güvenliği için TypeScript kullanın
ChaindocError ile uygun hata işlemeyi uygulayın.
Üretim ortamına dağıtmadan önce sandbox anahtarlarıyla test edin

Ortam Yapılandırması

// Backend
const chaindoc = new Chaindoc({
  secretKey: 'sk_live_xxxxx',
});

// Frontend
const embed = new ChaindocEmbed({
  publicKey: 'pk_live_xxxxx',
  environment: 'production',
});

Sonraki Adımlar

Gerçek zamanlı bildirimler için Webhooks belgelerini kontrol edin. Tam uç nokta belgeleri için REST API referansını okuyun. GitHub deposunda çerçeveye özgü örnekleri inceleyin.

Documentation