Chaindoc logoChaindoc

SDK Chaindoc

У Chaindoc два TypeScript SDK: Server SDK для backend (Node.js) и Embed SDK для встраивания UI подписи в веб-приложение. Полные type definitions, ноль runtime зависимостей, работают с любым фреймворком.

Доступные SDK

Настройка npm и конфигурация под конкретные фреймворки (env переменные, providers) — вот что важно, и все это есть в гайде по установке.

  • 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 в type-safe 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 ключ
        break;
      case 404:
        // Not found
        break;
      case 429:
        // Rate limited — SDK автоматически повторит
        break;
    }
  }
}

Embed SDK

Embed SDK позволяет показать интерфейс подписи Chaindoc прямо внутри вашего приложения. SDK управляет 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. Открытие flow подписи
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('Подписано!', 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('Подписано!', 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('Подписано!');
  },
});

Темы

Кастомизируйте внешний вид светлой или темной темой:

terminal
const instance = chaindoc.openSignatureFlow({
  sessionId,
  theme: 'dark',
  // ... другие опции
});

// Динамическое переключение темы
instance.changeTheme('light');

Полный пример workflow

На практике оба SDK работают вместе: Server SDK на backend для создания документов и сессий, Embed SDK на frontend для показа UI подписи.

1Backend: Загрузка документаИспользуйте Server SDK для загрузки файла и создания документа

2Backend: Создание запроса подписиСоздайте запрос подписи с включенным embedded flow

3Backend: Генерация сессииСоздайте embedded сессию для каждого подписанта

4Frontend: Инициализация Embed SDKИнициализируйте SDK с public ключом

5Frontend: Открытие flow подписиОткройте интерфейс подписи с 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,
  },
});

// Возврат sessionId на frontend
res.json({ sessionId: session.sessionId });

Лучшие практики

  • Инициализируйте SDK один раз за жизненный цикл страницы/компонента
  • Всегда вызывайте destroy при размонтировании компонента
  • Обрабатывайте все callback события (onSuccess, onError, onCancel)
  • Храните API ключи в environment переменных
  • Используйте TypeScript для лучшей type safety
  • Внедряйте правильную обработку ошибок через ChaindocError
  • Тестируйте с sandbox ключами перед production деплоем

Конфигурация окружений

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

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

Что делать дальше