Tích hợp API

Tích hợp Chaindoc vào ứng dụng của cậu bằng API REST mạnh mẽ và SDK của chúng tớ. Tự động hóa quy trình làm việc tài liệu, thu thập chữ ký và đồng bộ hóa sự kiện theo thời gian thực.

Tổng quan

Chaindoc cung cấp một API REST toàn diện cho phép cậu xây dựng các quy trình ký tài liệu tùy chỉnh, tự động hóa quy trình và tích hợp với các hệ thống hiện có của cậu. API này được thiết kế cho các nhà phát triển với hỗ trợ đầy đủ cho TypeScript và tính năng tự động thử lại.

Bắt đầu

1. Nhận quyền truy cập API

2. Chọn phương pháp tích hợp

Chaindoc cung cấp ba phương pháp tích hợp:

• REST API - Yêu cầu HTTP trực tiếp để đạt được tính linh hoạt tối đa
• Server SDK - SDK Node.js an toàn kiểu dữ liệu với tính năng thử lại tự động (@chaindoc_io/server-sdk)
• Embed SDK - Giao diện ký kết phía client cho ứng dụng web (@chaindoc_io/embed-sdk)

3. Ví dụ nhanh

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": []
  }'

Các khái niệm cơ bản của API

Xác thực

Tất cả các yêu cầu API đều yêu cầu xác thực bằng khóa API trong tiêu đề Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Khóa công khai (pk_) - Quyền truy cập chỉ đọc cho các ứng dụng giao diện người dùng
• Khóa bí mật (sk_) - Quyền truy cập đọc/ghi đầy đủ cho máy chủ phía sau
• Khóa thử nghiệm (pk_test_, sk_test_) - Dành cho môi trường staging/phát triển
• Live Keys (pk_live_, sk_live_) - Dành cho sản xuất

Giới hạn tốc độ

Các điểm cuối API có giới hạn tốc độ để đảm bảo sử dụng công bằng:

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

• Điểm cuối chung: 3 yêu cầu mỗi 10 giây
• Tải lên phương tiện: 3 yêu cầu mỗi 10 giây
• Hoạt động đọc: 10 yêu cầu mỗi 60 giây
• Tạo chữ ký: 20 yêu cầu mỗi 3 giây

Xử lý lỗi

API trả về các mã trạng thái HTTP tiêu chuẩn kèm theo thông báo lỗi chi tiết:

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

Các mẫu tích hợp phổ biến

Quy trình tải lên tài liệu và ký tên

Quy trình làm việc chỉ dành cho backend

Đối với các trường hợp người ký không sử dụng giao diện của cậu:

// 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

Xử lý tài liệu hàng loạt

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

Tính năng nâng cao

Webhooks

Nhận thông báo thời gian thực cho các sự kiện tài liệu:

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

Tích hợp KYC

Tích hợp xác minh danh tính cho các quy trình làm việc có mức độ bảo mật cao:

// 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
});

Kiểm soát truy cập

Quản lý quyền truy cập tài liệu với kiểm soát truy cập chi tiết:

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

Thực hành tốt nhất

• Lưu trữ khóa API trong biến môi trường, không bao giờ lưu trong mã nguồn.
• Sử dụng khóa thử nghiệm cho phát triển, khóa sản xuất cho môi trường sản xuất
• Áp dụng thuật toán lùi theo cấp số nhân cho việc xử lý giới hạn tốc độ.
• Xác minh chữ ký webhook để ngăn chặn các cuộc tấn công tái phát.
• Lưu trữ phản hồi API khi thích hợp
• Tải lên tệp trước khi tạo tài liệu để cải thiện hiệu suất.
• Sử dụng phân trang cho các tập dữ liệu lớn
• Theo dõi các tiêu đề giới hạn tốc độ và điều chỉnh tần suất yêu cầu

Ví dụ về tích hợp

Nền tảng thương mại điện tử

Tự động tạo và ký kết các thỏa thuận mua bán cho các đơn hàng giá trị cao.

Hệ thống Nhân sự

Tích hợp với hệ thống quản lý nhân sự (HRIS) để ký hợp đồng lao động tự động trong quá trình onboarding.

Tích hợp CRM

Tạo yêu cầu chữ ký trực tiếp từ hồ sơ khách hàng trong Salesforce, HubSpot hoặc hệ thống CRM tùy chỉnh.

Hệ thống quản lý tài liệu

Thêm xác minh blockchain vào hệ thống quản lý tài liệu hiện có để tạo ra các bản ghi kiểm toán không thể sửa đổi.

Tài nguyên

• Tài liệu API - Tài liệu tham khảo đầy đủ về API REST với tất cả các điểm cuối
• SDKs - Tài liệu về SDK máy chủ và SDK nhúng kèm theo các ví dụ về khung làm việc
• Webhooks - Hướng dẫn thiết lập thông báo sự kiện thời gian thực
• Bắt đầu nhanh - Hoàn thành tích hợp đầu tiên của cậu trong 10 phút
• Ví dụ trên GitHub - Các tích hợp mẫu và đoạn mã mẫu