Интеграция API

Включи Chaindoc в свои приложения с помощью нашего крутого REST API и SDK. Автоматизируй документооборот, собирай подписи и синхронизируй события в реальном времени.

Обзор

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

Начало работы

1. Получите доступ к API

2. Выбери способ интеграции

Chaindoc предлагает три способа интеграции:

• REST API — прямые HTTP-запросы для максимальной гибкости
• Server SDK — безопасный по типу Node.js SDK с автоматическими повторными попытками (@chaindoc_io/server-sdk)
• Embed SDK — интерфейс для веб-приложений (@chaindoc_io/embed-sdk)

3. Быстрый пример

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

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

Все запросы API должны проходить аутентификацию с помощью ключей API в заголовке Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Открытые ключи (pk_) — доступ только для чтения для приложений интерфейса
• Секретные ключи (sk_) — полный доступ на чтение/запись для бэкэнд-серверов
• Ключи тестирования (pk_test_, sk_test_) — для стадии подготовки/разработки
• Live Keys (pk_live_, sk_live_) — для производства

Ограничения скорости

Конечные точки API имеют ограничения скорости, чтобы обеспечить справедливое использование:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Общие ограничения: 3 запроса за 10 секунд
• Загрузка медиафайлов: 3 запроса за 10 секунд
• Операции чтения: 10 запросов за 60 секунд
• Создание подписи: 20 запросов за 3 секунды

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

API возвращает стандартные коды статуса HTTP с подробными сообщениями об ошибках:

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

Общие шаблоны интеграции

Процесс загрузки и подписания документов

Рабочий процесс только для бэкэнда

Если подписавшие не используют твой интерфейс:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

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

// Process multiple documents in batch
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' }],
  });
}

Дополнительные функции

Веб-хуки

Получайте уведомления о событиях в документах в реальном времени:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

Интеграция KYC

Включи проверку личности для более безопасных рабочих процессов:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Контроль доступа

Управляйте правами доступа к документам с помощью детального контроля доступа:

// Update document access rights
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' }, // Team role
  ],
});

Лучшие практики

• Храните API-ключи в переменных среды, а не в коде
• Используйте тестовые ключи для разработки, а рабочие ключи для производства
• Используйте экспоненциальный откат для управления ограничением скорости
• Проверяйте подписи веб-хуков, чтобы избежать атак повторного воспроизведения
• Кэшируйте ответы API, когда это нужно
• Загружайте файлы перед созданием документов, чтобы все работало лучше
• Используйте разбивку на страницы для больших наборов данных
• Следи за ограничениями скорости и настрой частоту запросов

Примеры интеграций

Платформа электронной коммерции

Автоматически создавайте и подписывайте договоры купли-продажи для крупных заказов.

Система HR

Свяжитесь с HRIS, чтобы автоматически подписывать трудовые договоры при приеме на работу.

Интеграция с CRM

Создавайте запросы на подпись прямо из записей клиентов в Salesforce, HubSpot или в своей CRM.

Система управления документами

Добавьте проверку блокчейна в существующие системы управления документами, чтобы сделать аудиторские следы защищенными от подделки.

Ресурсы

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