Chaindoc logoChaindoc

API інтеграція

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

Що можна робити через API

API дає програмний доступ до всього функціоналу Chaindoc: завантажувати документи, створювати запити на підпис, керувати командами та отримувати події через вебхуки. Це той самий API, який працює у веб-застосунку.

Три способи інтеграції

Ось у чому справа — обирайте те, що підходить вашому стеку. У продакшені зазвичай використовують Server SDK на бекенді та Embed SDK на фронтенді.

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

Якщо ще не встановили SDK, у гайді з встановлення розказано про налаштування npm для React, Vue, Angular та Next.js.

Швидкий приклад

Чесно кажучи, ось той самий запит «створити документ» у трьох варіантах. Версія з SDK найкоротша, а сирий REST-запит показує, що насправді відбувається по дроту.

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-ключа у заголовку Authorization:

terminal
Authorization: Bearer sk_live_xxxxxxxxxxxxx

Є два типи ключів, і їх плутаниця — найпоширеніша помилка при інтеграції:

  • Публічні ключі (`pk_`) — лише для читання, безпечні для фронтенд-коду
  • Секретні ключі (`sk_`) — повний доступ, тільки для бекенду. Ніколи не викладайте їх у клієнтському коді.
  • Обидва мають тестові (`_test_`) та продакшен (`_live_`) варіанти. Тестові ключі працюють із пісочницею.

Ліміти запитів

API повертає інформацію про ліміти у заголовках відповіді. Якщо перевищите ліміт — отримаєте 429. Зробіть паузу та повторіть запит.

terminal
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000
  • Загальні ендпоінти: 3 запити за 10 секунд
  • Завантаження медіа: 3 запити за 10 секунд
  • Операції читання: 10 запитів за 60 секунд
  • Створення підписів: 20 запитів за 3 секунди

На практиці Server SDK обробляє ретраї автоматично з експоненційним відкладенням. Якщо використовуєте сирий HTTP — реалізуйте логіку ретраїв самостійно.

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

Помилки повертаються у форматі JSON з кодом статусу, повідомленням та (для помилок валідації) списком конкретних проблем:

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

Поширені коди: 400 (поганий запит), 401 (неправильний ключ), 403 (тариф не включає API), 404 (не знайдено), 429 (перевищено ліміт), 500 (помилка сервера). Для 5xx помилок — повторіть із затримкою.

Типові сценарії інтеграції

Повний процес підписання (вбудований)

Головне — це найпоширеніший сценарій: завантажуєте документ, надсилаєте на підписи та показуєте UI підписання всередині вашого застосунку.

1Завантажте файлPOST /media/upload — надішліть PDF, Office-документ або зображення.

2Створіть документPOST /documents — встановіть status='published', щоб запустити блокчейн-верифікацію.

3Створіть запит на підписPOST /signatures/requests — додайте отримувачів, встановіть порядок підписання та дедлайн.

4Створіть вбудовану сесіюPOST /embedded/sessions — отримаєте sessionId для кожного підписанта.

5Відкрийте UI підписанняПередайте sessionId у метод openSignatureFlow() Embed SDK.

6Слідкуйте за завершеннямНалаштуйте вебхук для події signature.request.completed або опитуйте GET /signatures/requests/:id/status.

У гайді швидкий старт є повний код для цього процесу.

Підписання через email (без вбудовування)

Якщо підписанти не користуються вашим застосунком, встановіть `embeddedFlow: false`. Chaindoc надішле їм email із посиланням для підписання. Ви все одно отримаєте вебхук-сповіщення, коли вони підпишуть.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Підписанти отримують email-посилання
  message: 'Please review and sign this document',
});

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

Для batch-імпорту пройдіться циклом по ваших файлах та завантажте кожен. Але слідкуйте за лімітами. Якщо обробляєте сотні документів — додайте невелику паузу між запитами або використовуйте вбудовану логіку ретраїв SDK.

terminal
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' }],
  });
}

KYC інтеграція

Для робочих процесів із підвищеною безпекою можна вимагати верифікацію особи перед підписанням. Chaindoc інтегрується з Sumsub для KYC. Встановіть `isKycRequired: true` у запиті на підпис, і підписанти пройдуть верифікацію особи перед тим, як зможуть підписати.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Опціонально: попередньо верифікований
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Керування доступом через API

Можна програмно встановлювати права доступу до документів. Обмежте доступ конкретними email або ролями команди:

terminal
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' },
  ],
});

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

  • Тримайте API-ключі у змінних середовища. Ніколи не комітьте їх у систему контролю версій.
  • Використовуйте тестові ключі (`sk_test_`) для розробки. Live ключі (`sk_live_`) працюють із продакшеном.
  • Реалізуйте експоненційне відкладення для 429 відповідей. SDK робить це автоматично.
  • Перевіряйте підписи вебхуків за допомогою HMAC, щоб запобігти атакам повторення.
  • Завантажуйте файли перед створенням документів. API потребує media ID з кроку завантаження.
  • Використовуйте пагінацію для ендпоінтів, що повертають списки. Не забирайте все одразу.
  • Перед запуском у продакшен перевірте гайд з безпеки.

Приклади використання

Кілька реальних сценаріїв, які команди реалізують через API:

  • E-commerce — автоматично генеруйте договори купівлі для замовлень із високою вартістю та надсилайте на підписання при оформленні
  • HR онбординг — створюйте трудові договори з шаблонів та надсилайте новим співробітникам у їхній перший день
  • CRM інтеграція — запускайте запити на підписання з записів угод Salesforce або HubSpot
  • Архівація документів — додавайте блокчейн-верифікацію до документів у вашій існуючій системі зберігання

Що робити далі

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