Посібник зі швидкого старту

Почніть працювати з Chaindoc за 10 хвилин. Цей посібник проведе вас через веб-інтерфейс та API, щоб ви могли обрати відповідний шлях.

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

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

Покроково: ваш перший підпис

Хочете дізнатися про різні типи підписів (простий, розширений, кваліфікований)? Це має значення для відповідності вимогам. Для більшості бізнес-контрактів підходить простий електронний підпис, але регульовані галузі часто потребують розширеного або кваліфікованого.

Інтеграція через API

Якщо ви вбудовуєте підписання у свій додаток, ви використовуватимете REST API та TypeScript SDKs. Процес такий самий, як у веб-інтерфейсі, просто автоматизований.

1. Отримайте свої API ключі

Доступ до API потребує Business тарифу. Перейдіть до Налаштування > API Access у вашій панелі управління та створіть два ключі:

• Публічний ключ (`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, потім передайте 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 обробник:

// 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 ви повинні верифікувати підписи webhooks за допомогою HMAC, щоб переконатися, що payload дійсно надійшов від Chaindoc. Посібник з webhooks детально описує це.

Приклад повного робочого процесу

Це поєднує все разом: завантаження, створення, підпис, верифікація. Скопіюйте це, замініть свої 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 });

Куди рухатися далі

Тепер, коли ви опанували основи, ось у що варто заглибитися залежно від того, що ви будуєте:

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

Поширені питання

Скільки часу займає верифікація blockchain?

Зазвичай 1-5 хвилин, залежно від мережі. Ваш документ доступний відразу. Верифікація працює у фоновому режимі, і ви отримаєте подію webhook, коли вона завершиться.

Чи можу я тестувати API без оплати?

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

Чи є ці підписи юридично обов'язковими?

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

Які формати файлів я можу завантажувати?

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