Руководство по быстрому старту

Начните работу с Chaindoc менее чем за 10 минут. Это руководство проведёт вас через веб-интерфейс и API, чтобы вы могли выбрать подходящий путь.

Подписание через веб-интерфейс

Вам не нужен код для отправки первого запроса на подпись. Веб-приложение обрабатывает всё: загрузку, получателей, процесс подписания и верификацию blockchain.

Пошаговая инструкция: ваша первая подпись

Хотите разобраться в различных типах подписей (простая, усиленная, квалифицированная)? Это важно для соблюдения норм. Для большинства деловых контрактов подходит простая электронная подпись, но регулируемым отраслям часто требуется усиленная или квалифицированная.

Интеграция через API

Если вы встраиваете подписание в своё приложение, используйте REST API и TypeScript SDK. Процесс такой же, как в веб-интерфейсе, только автоматизированный.

1. Получите API ключи

Доступ к API требует Business плана. Перейдите в Настройки > Доступ к API в панели управления и создайте два ключа:

• Публичный ключ (`pk_`) для frontend с Embed SDK
• Секретный ключ (`sk_`) для backend с Server SDK. Держите его вне клиентского кода.

2. Установите SDK

Выберите SDK под ваш случай. Большинству приложений нужны оба: Server SDK для создания документов и Embed SDK для UI подписания.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

Для детальной настройки фреймворков (React, Vue, Angular, Next.js) смотрите руководство по установке.

3. Загрузите и создайте документ

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

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

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

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

console.log('Document created:', doc.documentId);

Установка `status: 'published'` автоматически запускает верификацию blockchain. Если хотите отложить, используйте `'draft'` и опубликуйте позже.

4. Создайте запрос на подпись

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Установите `embeddedFlow: true`, если будете показывать UI подписания внутри своего приложения. Без этого подписанты получат ссылку на хостинговую страницу подписания Chaindoc.

5. Покажите интерфейс подписания (frontend)

Это необязательно. Если вы установили `embeddedFlow: true`, можете открыть UI подписания прямо в приложении. Сначала создайте сессию на backend, затем передайте session ID в frontend.

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

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

6. Проверьте статус и слушайте события

Можно опрашивать статус, но webhooks лучше для production. Они уведомят ваш сервер сразу, когда что-то произойдёт.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Настройте webhooks (рекомендуется)

Webhooks отправляют события на ваш сервер в реальном времени, чтобы не приходилось постоянно проверять. Вот базовый Express handler:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

В production следует верифицировать подписи webhook с помощью HMAC, чтобы убедиться, что payload действительно от Chaindoc. Руководство по webhooks подробно описывает это.

Пример полного workflow

Здесь всё вместе: загрузка, создание, подпись, верификация. Скопируйте, подставьте свои API ключи, и у вас будет рабочий прототип.

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

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: 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,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

Куда двигаться дальше

Теперь, когда вы освоили основы, вот что изучить в зависимости от того, что вы строите:

• Установка — настройка для React, Vue, Angular и Next.js
• API документация — полный справочник endpoint с примерами запросов/ответов
• SDK — Server SDK и Embed SDK с руководствами по интеграции для каждого фреймворка
• Webhooks — уведомления о событиях в реальном времени для production приложений
• Лучшие практики безопасности — что нужно защитить перед запуском

Частые вопросы

Сколько занимает верификация blockchain?

Обычно 1-5 минут, в зависимости от сети. Ваш документ доступен сразу. Верификация работает в фоне, и вы получите webhook событие, когда завершится.

Могу ли я тестировать API бесплатно?

Бесплатный план даёт доступ к веб-интерфейсу. Доступ к API требует Business плана, но sandbox окружение позволяет тестировать всё без влияния на реальные данные или использования квоты.

Обладают ли эти подписи юридической силой?

Да. Подписи Chaindoc соответствуют eIDAS в Европе, ESIGN Act и UETA в США, аналогичным регламентам в большинстве других юрисдикций. Верификация blockchain добавляет дополнительный уровень доказательств, что может иметь значение в спорах. Смотрите документацию по подписям для деталей о том, какой тип подписи подходит под ваши требования compliance.

Какие форматы файлов можно загружать?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV и WMV. Максимальный размер файла — 50МБ.