Справочник по REST API Chaindoc

Полное руководство по интеграции REST API Chaindoc в твои приложения. Управляй документами, подписями, проверкой блокчейна и встроенными рабочими процессами подписания.

Обзор

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

Основные особенности

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

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

Chaindoc API использует ключи API для аутентификации. Есть два типа ключей с разными уровнями доступа.

Типы ключей API

• Открытый ключ (pk_) — доступ только для чтения для фронтенд-приложений и проверки
• Секретный ключ (sk_) — полный доступ на чтение и запись для бэкэнд-серверов

Как получить ключи API

Использование ключей API

Включи свой ключ API в заголовок Authorization с аутентификацией Bearer:

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 запросов в минуту
• Создание подписи: 20 запросов за 3 секунды

Если превысишь лимит запросов, получишь ответ 429 Too Many Requests. Заголовки лимита запросов есть в ответах:

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

Обработка ошибок

Коды статуса HTTP

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

Формат ответа на ошибку

{
  "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

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

Проверяйте подлинность документов с помощью блокчейна. Получите статус проверки с хэшем транзакции и ID цепочки.

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