Chaindoc logoChaindoc

Chaindoc SDK

Chaindoc екі TypeScript SDK ұсынады: Server SDK backend операциялары үшін (Node.js) және Embed SDK қол қою интерфейсін веб-қосымшаңызға енгізу үшін. Екеуінде толық тип анықтамалары бар, runtime тәуелділіктері жоқ, кез келген фреймворкпен жұмыс істейді.

Қолжетімді SDK

npm орнату және фреймворкке арналған конфигурация (env айнымалылары, провайдерлер т.б.) туралы орнату нұсқаулығына қараңыз.

  • Server SDK (@chaindoc_io/server-sdk) - Backend интеграциясы Node.js 18+ үшін
  • Embed SDK (@chaindoc_io/embed-sdk) - Frontend қол қою интерфейсі веб-қосымшалар үшін
  • Python SDK - Жақында шығады
  • PHP SDK - Жақында шығады

Server SDK

Server SDK REST API типтік қауіпсіз Node.js интерфейсіне орайды. Құжаттарды басқаруға, қол қою сұраныстарын жасауға, файл жүктеуді және blockchain растауын іске қосуға қолданасыз.

Орнату

npm install @chaindoc_io/server-sdk

Жылдам старт

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

// 1. SDK-ны инициализациялау
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 2. Құжат файлын жүктеу
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 3. Құжат жасау
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Contract for consulting services',
  media: media[0],
  status: 'published', // Blockchain растауын іске қосады
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

// 4. Қол қою сұранысын жасау
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. 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 интеграциясы

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!,
});

// Жүктеу және құжат жасау
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' });
    }
  }
});

// Қол қоюшы үшін embedded сессия жасау
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 Routes

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 }
    );
  }
}

Қателерді өңдеу

API шақыруларын әрқашан try-catch блоктарына салыңыз және ChaindocError ерекше түрлігін бөлек өңдеңіз:

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 - параметрлерді тексеріңіз
        break;
      case 401:
        // Unauthorized - API key тексеріңіз
        break;
      case 404:
        // Not found
        break;
      case 429:
        // Rate limited - SDK автоматты түрде қайта қолданады
        break;
    }
  }
}

Embed SDK

Embed SDK Chaindoc қол қою интерфейсін веб-қосымшаңызда көрсетуге мүмкіндік береді. Iframe, OTP растауы және қосымшаңыз бен Chaindoc арасындағы байланысты басқарады. Пайдаланушылар сайтыңыздан шықпай құжаттарға қол қояды.

Орнату

npm install @chaindoc_io/embed-sdk

Негізгі қолдану

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

// 1. SDK-ны инициализациялау (бетке бір рет)
const chaindoc = new ChaindocEmbed({
  publicKey: 'pk_live_xxxxxxxxxxxxx',
  environment: 'production',
});

// 2. Backend-тен сессия алу
const response = await fetch('/api/signing/create-session', {
  method: 'POST',
  body: JSON.stringify({ documentId, signerEmail }),
});
const { sessionId } = await response.json();

// 3. Қол қою процесін ашу
const instance = chaindoc.openSignatureFlow({
  sessionId,
  
  onReady: () => {
    console.log('Қол қою интерфейсі жүктелді');
  },
  
  onSuccess: (data) => {
    console.log('Құжатқа қол қойылды:', data.signatureId);
    instance.close();
  },
  
  onError: (error) => {
    console.error('Қол қою сәтсіз:', error.code, error.message);
  },
  
  onCancel: () => {
    console.log('Пайдаланушы бас тартты');
    instance.close();
  },
});

React интеграциясы

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}>Құжатқа қол қою</button>;
}

Vue 3 интеграциясы

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">Құжатқа қол қою</button>
</template>

Inline режимі

Модалдық терезе орнына қол қою интерфейсін бетке тікелей енгізіңіз:

terminal
const instance = chaindoc.openSignatureFlow({
  sessionId,
  mode: 'inline',
  container: document.getElementById('signature-container'),
  
  onSuccess: (data) => {
    console.log('Қол қойылды!');
  },
});

Темалар

Сыртқы түрін light немесе dark темалармен реттеңіз:

terminal
const instance = chaindoc.openSignatureFlow({
  sessionId,
  theme: 'dark',
  // ... басқа параметрлер
});

// Теманы динамикалық өзгерту
instance.changeTheme('light');

Толық workflow мысалы

Міне екі SDK-ны біріктіру: Backend-те құжаттар мен сессиялар жасау үшін Server SDK, Frontend-те қол қою интерфейсін көрсету үшін Embed SDK.

1Backend: Құжатты жүктеуФайлды жүктеу және құжат жасау үшін Server SDK қолданыңыз

2Backend: Қол қою сұранысын жасауEmbedded flow қосылған қол қою сұранысын жасаңыз

3Backend: Сессия жасауӘр қол қоюшы үшін embedded сессия жасаңыз

4Frontend: Embed SDK инициализациясыPublic key-мен SDK-ны инициализациялаңыз

5Frontend: Қол қою процесін ашуSession ID-мен қол қою интерфейсін ашыңыз

6Frontend: Сәттілікті өңдеуҚол қойылған құжатты өңдеңіз және UI жаңартыңыз

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

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

// Жүктеу және құжат жасау
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: [],
});

// Қол қою сұранысын жасау
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,
});

// Сессия жасау
const session = await chaindoc.embedded.createSession({
  email: 'signer@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Frontend-ке sessionId қайтару
res.json({ sessionId: session.sessionId });

Үздік тәжірибелер

  • SDK-ны бетке/компоненттің өмірлік цикліне бір рет инициализациялаңыз
  • Компонент жойылғанда әрқашан SDK инстансын жойыңыз
  • Барлық callback оқиғаларын өңдеңіз (onSuccess, onError, onCancel)
  • API кілттерін environment айнымалыларына сақтаңыз
  • Жақсырақ типтік қауіпсіздік үшін TypeScript қолданыңыз
  • ChaindocError-пен дұрыс қате өңдеуін іске асырыңыз
  • Өндіріске шығармас бұрын sandbox кілттерімен тексеріңіз

Қоршаған орта конфигурациясы

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

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

Келесі не істеу керек

  • Орнату — npm орнату, env конфигурациясы және фреймворкке арналған провайдерлер
  • API құжаттамасы — толық REST endpoint анықтамасы
  • Webhooks — Backend үшін нақты уақыттағы оқиға хабарламалары
  • Жылдам старт — 10 минутта алғашқы қол қоюды жіберу
  • Қауіпсіздік — API кілтін басқару және өндірісті нығайту