Chaindoc logoChaindoc

Довідник REST API Chaindoc

Повна довідка щодо інтеграції REST API Chaindoc у ваші додатки. Керуйте документами, підписами, верифікацією блокчейну та вбудованими робочими процесами підписання.

Огляд

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

Основні функції

  • Управління документами — створюйте, оновлюйте та керуйте документами з перевіркою блокчейну
  • Цифрові підписи — запитуйте та збирайте цифрові підписи від декількох сторін
  • Перевірка блокчейну — перевірка автентичності документів у мережах блокчейну
  • Вбудовані сесії — створюйте безпечні сесії для робочих процесів підписання на стороні клієнта
  • Завантаження медіафайлів — завантажуйте файли (PDF, зображення, відео) для створення документів
  • Інтеграція KYC — обмін та перевірка ідентифікаційних даних за допомогою Sumsub

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

Chaindoc API використовує API-ключі для аутентифікації. Існує два типи ключів з різними рівнями доступу.

Типи ключів API

  • Відкритий ключ (pk_) — доступ тільки для читання для фронтенд-додатків та верифікації
  • Секретний ключ (sk_) — повний доступ для читання та запису для серверів бекенду

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

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

2Перейдіть до розділу «Доступ до API»Перейдіть до Налаштування → Доступ до API у вашій панелі управління

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

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

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

Включіть свій ключ API в заголовок авторизації з аутентифікацією Bearer:

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

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

Кінцеві точки API мають обмеження швидкості, щоб запобігти зловживанням. Обмеження швидкості варіюються залежно від типу кінцевої точки.

  • Загальні кінцеві точки: 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 та дійсність ключа.

GET /health

Authorization: Bearer sk_live_xxxxx

API документів

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

Створіть новий документ із верифікацією блокчейну. Коли статус встановлено на «опубліковано», документ автоматично верифікується в блокчейні.

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

Перевірте документ

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

POST /documents/verify

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

Отримати статус перевірки

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

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API підписів

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

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

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