Chaindoc logoChaindoc

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

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

Обзор

API дает программный доступ ко всему функционалу Chaindoc: документы, подписи, верификация в блокчейне и управление командой. Работает по принципу server-to-server, поддерживает публичные и секретные ключи.

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

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

Каждый запрос требует API key в заголовке Authorization. Есть два типа ключей:

Типы ключей

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

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

1Оформите Business-тарифAPI-ключи доступны только на Business-тарифе

2Перейдите в раздел API AccessВ дашборде: Settings → API Access

3Создайте API keyНажмите кнопку Create API Key

4Сохраните надежноСекретный ключ показывается один раз — не потеряйте

Использование API keys

Добавьте API key в заголовок Authorization с Bearer-аутентификацией:

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

Rate limiting

На API действуют лимиты запросов для защиты от злоупотреблений. Зависят от типа endpoint.

  • Общие endpoints: 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 key)
  • 403 — Запрещено (недостаточно прав)
  • 404 — Ресурс не найден
  • 429 — Слишком много запросов (превышен лимит)
  • 500 — Внутренняя ошибка сервера

Формат ответа с ошибкой

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

Общие методы API

Информация об API key

Получить информацию о текущем API key.

GET /me

Authorization: Bearer sk_live_xxxxx

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

Проверить подключение к API и валидность ключа.

GET /health

Authorization: Bearer sk_live_xxxxx

Documents 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

Верификация документа

Проверить подлинность документа через блокчейн. Возвращает статус верификации с tx hash и chain ID.

POST /documents/verify

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

Статус верификации

Получить статус блокчейн-верификации для конкретной версии документа.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Signatures 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 key — один из подписантов).

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

Media upload 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

Embedded sessions API

Создавайте embedded-сессии для подписания документов прямо в вашем фронтенде. Сессии валидны 10 минут.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Что дальше

  • API integration — типовые паттерны, лучшие практики и примеры рабочих сценариев
  • SDKs — Server SDK и Embed SDK с гайдами под фреймворки
  • Webhooks — настройте реалтайм-уведомления о событиях
  • Installation — npm-установка под все поддерживаемые фреймворки
  • Security — управление API-ключами и compliance