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'.

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

Використовуйте тестові ключі під час розробки, щоб випадково не створювати реальні документи або не надсилати листи з підписами реальним отримувачам.

Налаштування для розробки

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Відкрийте інтерфейс підписанняІніціалізуйте 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 встановлено, оберіть свій наступний крок:

  • Швидкий старт — надішліть свій перший запит на підпис за 10 хвилин
  • Документація API — повна довідка з endpoint з прикладами
  • SDK — розширені можливості SDK та посібники для кожного фреймворку
  • Вебхуки — налаштуйте сповіщення про події в реальному часі
  • Кращі практики безпеки — що налаштувати перед запуском у продакшен