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-вызов показывает, что происходит на уровне HTTP.

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 — повторяйте с бэкоффом.

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

Полный поток подписания (встроенный)

Самый популярный сценарий: загрузить документ, отправить на подпись, показать интерфейс подписания внутри вашего приложения.

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

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

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

4Создайте встроенную сессиюPOST /embedded/sessions — получите sessionId для каждого подписанта.

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

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

Пакетная обработка документов

Для массовых импортов — пройдитесь по файлам в цикле и загружайте каждый. Но следите за лимитами. Если обрабатываете сотни документов, добавьте небольшую паузу между запросами или используйте встроенную логику ретраев 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_`) для разработки. Боевые (`sk_live_`) — для продакшена.
  • Реализуйте экспоненциальный бэкофф для ответов 429. SDK делает это автоматически.
  • Проверяйте подписи вебхуков через HMAC, чтобы предотвратить replay-атаки.
  • Загружайте файлы перед созданием документов. API нужен media ID из шага загрузки.
  • Используйте пагинацию для эндпоинтов со списками. Не выгружайте все сразу.
  • Прочитайте гайд по безопасности перед запуском в прод.

Примеры использования

Несколько реальных сценариев, которые команды реализуют через API:

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

Что делать дальше

  • Документация API — полный справочник эндпоинтов с примерами запросов и ответов
  • SDK — Server SDK и Embed SDK с гайдами под конкретные фреймворки
  • Вебхуки — настройка уведомлений о событиях в реальном времени
  • Быстрый старт — запустите первую интеграцию за 10 минут
  • Установка — настройка npm для всех поддерживаемых фреймворков