Chaindoc logoChaindoc

Установка

Добавьте SDK Chaindoc в свой проект. Есть два пакета: Server SDK для бэкенда (документы, подписи, верификация) и Embed SDK для встраивания интерфейса подписания в ваш фронтенд.

Перед началом

Если у вас еще нет аккаунта, начните с руководства по быстрому старту, чтобы его создать.

Server SDK

Server SDK обрабатывает все на бэкенде: создание документов, отправка запросов на подпись, управление командами и запуск верификации на блокчейне. Это тонкая обертка вокруг REST API, поэтому если вы читали документацию API, названия методов покажутся знакомыми.

Установка пакета

npm install @chaindoc_io/server-sdk

Настройка переменных окружения

Создайте файл `.env` в корне проекта. Здесь вам понадобится ваш секретный ключ.

.env
# Production keys
CHAINDOC_SECRET_KEY=sk_live_xxxxxxxxxxxxx

# Staging/Testing keys
# CHAINDOC_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Optional: Custom API endpoint
# CHAINDOC_API_URL=https://api.chaindoc.io

Инициализация SDK

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

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

// Advanced configuration
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  baseUrl: process.env.CHAINDOC_API_URL, // Optional
  timeout: 60000, // 60 seconds
  retry: {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

Базовой конфигурации достаточно для большинства проектов. Настройки повторных попыток стоит подкрутить, если вы обрабатываете много документов пакетно, так как у API есть ограничения на частоту запросов.

Проверка подключения

terminal
// Test API connection
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('Connected to Chaindoc API');
  console.log('User ID:', health.userId);
} else {
  console.error('Connection failed');
}

Если это не сработает, проверьте, что ваш секретный ключ начинается с `sk_live_` (продакшен) или `sk_test_` (песочница). Самая распространенная проблема — случайное использование публичного ключа.

Embed SDK

Embed SDK позволяет показывать интерфейс подписания Chaindoc внутри вашего веб-приложения. Пользователи подписывают документы, не покидая ваш сайт. Работает с React, Vue, Angular или чистым JavaScript.

Установка пакета

npm install @chaindoc_io/embed-sdk

Вариант с CDN удобен для быстрых прототипов или сайтов без сборки. Для продакшена используйте npm-пакет, чтобы получить tree-shaking и правильное управление версиями.

Настройка переменных окружения

Embed SDK использует ваш публичный ключ (`pk_`), который безопасно включать в клиентский код.

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx
# or for Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx

Инициализация в приложении

// hooks/useChaindoc.ts
import { useRef, useEffect } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export function useChaindoc() {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

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

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

  return sdkRef.current;
}

Настройка для фреймворков

Эти примеры показывают, как подключить Embed SDK как провайдер или сервис в каждом фреймворке. Если вы используете Server SDK на бэкенде, провайдер не нужен; просто импортируйте его там, где нужно.

Next.js (App Router)

app/providers.tsx
'use client';

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

const ChaindocContext = createContext<ChaindocEmbed | null>(null);

export function ChaindocProvider({ children }: { children: React.ReactNode }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

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

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

  return (
    <ChaindocContext.Provider value={sdkRef.current}>
      {children}
    </ChaindocContext.Provider>
  );
}

export const useChaindoc = () => useContext(ChaindocContext);

Next.js (Pages Router)

pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default function App({ Component, pageProps }: AppProps) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

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

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

  return <Component {...pageProps} />;
}

Nuxt 3

plugins/chaindoc.client.ts
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const chaindoc = new ChaindocEmbed({
    publicKey: config.public.chaindocPublicKey,
  });

  return {
    provide: {
      chaindoc,
    },
  };
});

Angular

services/chaindoc.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';
import { environment } from '../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class ChaindocService implements OnDestroy {
  private sdk: ChaindocEmbed;

  constructor() {
    this.sdk = new ChaindocEmbed({
      publicKey: environment.chaindocPublicKey,
    });
  }

  getSdk(): ChaindocEmbed {
    return this.sdk;
  }

  ngOnDestroy(): void {
    this.sdk.destroy();
  }
}

Конфигурация TypeScript

Оба SDK поставляются с полными определениями TypeScript. Вам не нужны дополнительные пакеты `@types`.

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Если вы используете старую версию TypeScript (< 5.0), используйте `"moduleResolution": "node"` вместо `"bundler"`.

Разработка vs продакшен

Используйте тестовые ключи во время разработки, чтобы случайно не создать реальные документы или не отправить письма о подписи реальным получателям.

Настройка для разработки

terminal
// Use test keys for development
const chaindoc = new Chaindoc({
  secretKey: 'sk_test_xxxxx',
  baseUrl: 'https://api.chaindoc.io',
});

const embed = new ChaindocEmbed({
  publicKey: 'pk_test_xxxxx',
  environment: 'staging',
  debug: true, // Enable detailed logs
});

Флаг `debug: true` выводит детали запросов/ответов в консоль. Это шумно, но полезно, когда вы выясняете, почему что-то не работает.

Настройка для продакшена

terminal
// Use live keys for production
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!, // sk_live_xxxxx
});

const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!, // pk_live_xxxxx
  environment: 'production',
});

Проверка установки

Пройдите эти проверки, чтобы убедиться, что все правильно настроено:

1Проверьте версию SDKЗапустите `console.log(ChaindocEmbed.version)` в вашем приложении. Если выводится номер версии, пакет установлен правильно.

2Проверьте подключение к APIВызовите `chaindoc.healthCheck()` с вашего бэкенда. Успешный ответ означает, что ваш секретный ключ валиден и API доступен.

3Попробуйте загрузить файлЗагрузите небольшой тестовый PDF через `chaindoc.media.upload()`. Это подтвердит, что аутентификация, сеть и обработка файлов работают.

4Откройте UI подписанияИнициализируйте Embed SDK и вызовите `openSignatureFlow()` с тестовой сессией. Если появляется модальное окно, все готово.

Устранение неполадок

Ошибка «Module not found»

Обычно это означает, что пакет не установился должным образом или есть конфликт кэшированных версий. Очистите все и переустановите:

terminal
# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

Ошибки типов TypeScript

Убедитесь, что у вас установлены типы Node.js и ваш `tsconfig.json` использует правильное разрешение модулей. Большинство проблем возникает из-за несоответствия настроек `moduleResolution`.

terminal
npm install --save-dev @types/node

Ошибки ключа API

Если вы получаете ответы 401 или 403, вот что проверить:

  • 401 Unauthorized означает, что ключ невалиден или истек. Перегенерируйте его в панели управления.
  • 403 Forbidden означает, что ваш тариф не включает доступ к API. Вам нужен тариф Business.
  • Убедитесь, что вы используете правильный тип ключа: ключи `pk_` для Embed SDK (фронтенд), ключи `sk_` для Server SDK (бэкенд). Их перепутка — самая распространенная ошибка.
  • Тестовые ключи (`_test_`) работают только с песочницей. Live-ключи (`_live_`) обращаются к продакшену.

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

Теперь, когда SDK установлены, выберите следующий шаг: