Інтеграція API

Інтегруйте Chaindoc у свої додатки за допомогою нашого потужного REST API та SDK. Автоматизуйте робочі процеси з документами, збирайте підписи та синхронізуйте події в режимі реального часу.

Огляд

Chaindoc надає комплексний REST API, який дозволяє створювати власні робочі процеси підписання документів, автоматизувати процеси та інтегрувати їх з існуючими системами. API розроблений для розробників з повною підтримкою TypeScript та автоматичними повторними спробами.

Початок роботи

1. Отримайте доступ до API

2. Виберіть метод інтеграції

Chaindoc пропонує три підходи до інтеграції:

• REST API — прямі HTTP-запити для максимальної гнучкості
• Server SDK — безпечний для типів SDK Node.js з автоматичними повторними спробами (@chaindoc_io/server-sdk)
• Embed SDK — інтерфейс для підпису веб-додатків (@chaindoc_io/embed-sdk)

3. Короткий приклад

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Основні поняття API

Аутентифікація

Усі запити API вимагають автентифікації за допомогою ключів API в заголовку Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Відкриті ключі (pk_) — доступ тільки для читання для інтерфейсних додатків
• Секретні ключі (sk_) — повний доступ для читання/запису для серверів бекенду
• Ключі тестування (pk_test_, sk_test_) — для стадіювання/розробки
• Live Keys (pk_live_, sk_live_) — для виробництва

Обмеження швидкості

Кінцеві точки API мають обмеження швидкості для забезпечення справедливого використання:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Загальні кінцеві точки: 3 запити на 10 секунд
• Завантаження медіафайлів: 3 запити на 10 секунд
• Операції читання: 10 запитів за 60 секунд
• Створення підпису: 20 запитів за 3 секунди

Обробка помилок

API повертає стандартні коди статусу HTTP з докладними повідомленнями про помилки:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Загальні шаблони інтеграції

Процес завантаження та підписання документів

Робочий процес тільки для бекенду

Для випадків, коли підписанти не використовують ваш інтерфейс:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Масова обробка документів

// Process multiple documents in batch
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Розширені функції

Веб-хуки

Отримуйте сповіщення про події, пов'язані з документами, у режимі реального часу:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

Інтеграція KYC

Інтегруйте перевірку ідентичності для робочих процесів з високим рівнем безпеки:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Контроль доступу

Керуйте дозволами на доступ до документів за допомогою детального контролю доступу:

// Update document access rights
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' }, // Team role
  ],
});

Кращі практики

• Зберігайте API-ключі в змінних середовища, ніколи в коді
• Використовуйте тестові ключі для розробки, а робочі ключі для виробництва
• Впровадьте експоненціальне відступання для обробки обмеження швидкості
• Перевіряйте підписи веб-хуків, щоб запобігти атакам типу «replay».
• За необхідності кешуйте відповіді API
• Завантажуйте файли перед створенням документів для кращої продуктивності
• Використовуйте нумерацію сторінок для великих наборів даних
• Стежте за заголовками обмеження швидкості та регулюйте частоту запитів

Приклад інтеграції

Платформа електронної комерції

Автоматично генеруйте та підписуйте договори купівлі-продажу для замовлень на велику суму.

Система HR

Інтегруйте з HRIS для автоматизованого підписання трудових договорів під час адаптації нових співробітників.

Інтеграція CRM

Створюйте запити на підпис безпосередньо з записів клієнтів у Salesforce, HubSpot або власній CRM.

Система управління документами

Додайте перевірку блокчейну до існуючої системи управління документами (DMS) для створення захищених від фальсифікації аудиторських слідів.

Ресурси

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