Chaindoc logoChaindoc

Довідник Chaindoc REST API

Повний перелік ендпоінтів Chaindoc REST API. Описано автентифікацію, роботу з документами, підписами, завантаженням медіа, вбудованими сесіями та верифікацію на блокчейні.

Огляд

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

  • Документи — створення, оновлення та верифікація документів на блокчейні
  • Підписи — надсилання запитів на підпис та відстеження статусу
  • Медіа — завантаження PDF, зображень та відео (макс. 10 файлів за запит)
  • Вбудовані сесії — створення сесій підписання для вашого фронтенду (використовує Embed SDK)
  • KYC — обмін та верифікація персональних даних через інтеграцію з Sumsub

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

Кожен запит потребує API ключа в заголовку Authorization. Є два типи ключів:

Типи ключів

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

Отримання ключів

1Підпишіться на Business планAPI ключі доступні лише користувачам Business плану

2Перейдіть до API AccessУ дашборді відкрийте Settings → API Access

3Створіть API ключНатисніть кнопку Create API Key

4Збережіть у надійному місціСекретний ключ показується лише один раз

Використання API ключів

Додайте API ключ у заголовок Authorization з Bearer автентифікацією:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Rate limiting

На всі ендпоінти накладаються ліміти запитів для захисту від зловживань. Ліміти залежать від типу операції.

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

При перевищенні ліміту отримаєте відповідь 429 Too Many Requests. У відповідях передаються заголовки з інформацією про ліміти:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

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

HTTP статус-коди

  • 200 — Успіх
  • 201 — Ресурс успішно створено
  • 400 — Некоректний запит (помилка валідації)
  • 401 — Неавторизовано (невірний або відсутній API ключ)
  • 403 — Заборонено (недостатньо прав)
  • 404 — Ресурс не знайдено
  • 429 — Забагато запитів (перевищено ліміт)
  • 500 — Внутрішня помилка сервера

Формат відповіді про помилку

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

Загальні методи API

Отримати інформацію про API ключ

Отримує інформацію про поточний API ключ.

GET /me

Authorization: Bearer sk_live_xxxxx

Перевірка здоров'я API

Перевіряє доступність API та валідність ключа.

GET /health

Authorization: Bearer sk_live_xxxxx

API документів

Створити документ

Створює новий документ з верифікацією на блокчейні. При статусі 'published' документ автоматично верифікується на блокчейні.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Оновити документ

Оновлює документ шляхом створення нової версії. Попередні версії зберігаються для аудиту.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Оновити права доступу до документа

Оновлює налаштування контролю доступу до документа.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Верифікувати документ

Перевіряє автентичність документа через блокчейн. Повертає статус верифікації з хешем транзакції та ID мережі.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Отримати статус верифікації

Отримує статус блокчейн-верифікації для версії документа.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API підписів

Створити запит на підпис

Створює запит на підпис для одного чи кількох отримувачів. Увімкніть embedded flow для інтеграції у фронтенд.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Отримати статус запиту на підпис

Перевіряє статус запиту на підпис та бачить, які підписанти вже завершили процес.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Підписати документ

Підписує документ (якщо власник API ключа є підписантом).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Отримати підписи користувача

Отримує всі підписи автентифікованого користувача.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Отримати запити на підпис

Отримує всі запити на підпис автентифікованого користувача з підтримкою пагінації.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

API завантаження медіа

Завантажує файли для використання при створенні документів. Підтримує PDF, зображення та відео. Максимум 10 файлів за запит.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

KYC API

Поділитися KYC даними

Ділиться KYC (Know Your Customer) даними з отримувачами для верифікації особи.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API вбудованих сесій

Створює вбудовані сесії для підписання документів у вашому фронтенд-застосунку. Сесії дійсні протягом 10 хвилин.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

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

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