Tích hợp API

REST API của Chaindoc cho phép bạn tự động hóa quy trình tài liệu, thu thập chữ ký và đồng bộ sự kiện theo thức gian. Trang này hướng dẫn cách bắt đầu, các khái niệm chính và mẫu tích hợp phổ biến.

Bạn có thể làm gì với API

API cung cấp quyền truy cập lập trình vào mọi tính năng của Chaindoc: tải lên tài liệu, tạo yêu cầu chữ ký, quản lý nhóm và lắng nghe sự kiện qua webhooks. Đây chính là API vận hành ứng dụng web.

Ba cách tích hợp

Chọn phương án phù hợp với stack của bạn. Hầu hết ứng dụng production dùng Server SDK ở backend và Embed SDK ở frontend.

• REST API — gửi HTTP request trực tiếp, hoạt động với mọi ngôn ngữ. Linh hoạt tối đa.
• Server SDK — wrapper Node.js có type-safe, tự động retry và xử lý lỗi (`@chaindoc_io/server-sdk`)
• Embed SDK — nhúng giao diện ký vào ứng dụng web, ngườii dùng không cần rồi khỏi trang (`@chaindoc_io/embed-sdk`)

Nếu chưa cài SDK, hướng dẫn cài đặt có hướng dẫn npm cho React, Vue, Angular và Next.js.

Ví dụ nhanh

Dưới đây là cùng một lệnh "tạo tài liệu" theo ba cách. Phiên bản SDK ngắn gọn nhất, nhưng REST thuần cho thấy chính xác điều gì đang xảy ra.

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

Xác thực

Mọi request cần API key trong header Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Có hai loại khóa, và nhầm lẫn chúng là lỗi tích hợp phổ biến nhất:

• Public keys (`pk_`) — chỉ đọc, an toàn cho frontend
• Secret keys (`sk_`) — đọc/ghi đầy đủ, chỉ dùng ở backend. Không bao giờ để lộ trong code client-side.
• Cả hai đều có bản test (`_test_`) và live (`_live_`). Khóa test trỏ đến sandbox.

Giới hạn tần suất

API trả về thông tin giới hạn trong response header. Khi vượt quá, bạn nhận được 429. Hãy backoff và thử lại.

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

• Endpoint chung: 3 request mỗi 10 giây
• Tải media: 3 request mỗi 10 giây
• Thao tác đọc: 10 request mỗi 60 giây
• Tạo chữ ký: 20 request mỗi 3 giây

Server SDK tự động xử lý retry với exponential backoff. Nếu dùng HTTP thuần, bạn cần tự triển khai logic retry.

Xử lý lỗi

Lỗi trả về dạng JSON kèm status code, message và (với lỗi validation) danh sách chi tiết từng trường:

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

Các status code phổ biến: 400 (request sai), 401 (khóa không hợp lệ), 403 (gói không có API), 404 (không tìm thấy), 429 (bị giới hạn), 500 (lỗi server). Với lỗi 5xx, hãy retry với backoff.

Mẫu tích hợp phổ biến

Quy trình ký đầy đủ (nhúng)

Mẫu phổ biến nhất: tải tài liệu, gửi ký, hiển thị giao diện ký trong ứng dụng của bạn.

Hướng dẫn bắt đầu nhanh có đầy đủ code cho flow này.

Ký qua email (không nhúng)

Nếu ngườii ký không dùng ứng dụng của bạn, đặt `embeddedFlow: false`. Chaindoc gửi email với link ký. Bạn vẫn nhận webhook khi họ ký.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Ngườii ký nhận link email
  message: 'Please review and sign this document',
});

Xử lý hàng loạt

Với batch import, lặp qua file và tải từng cái. Đây là vấn đề: phải chú ý rate limit. Khi xử lý hàng trăm tài liệu, thêm delay nhỏ giữa các request hoặc dùng retry logic của SDK.

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ích hợp KYC

Thành thật mà nói, với workflow bảo mật cao, bạn nên yêu cầu xác minh danh tính trước khi ký. Chaindoc tích hợp với Sumsub cho KYC. Đặt `isKycRequired: true` trên yêu cầu chữ ký, ngườii ký sẽ qua xác minh danh tính trước khi ký được.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Tùy chọn: đã xác minh trước
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Quyền truy cập qua API

Bạn có thể đặt quyền tài liệu bằng code. Hạn chế truy cập cho email cụ thể hoặc vai trò nhóm:

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

Thực tiễn tốt nhất

• Giữ API key trong biến môi trường. Không bao giờ commit vào version control.
• Dùng khóa test (`sk_test_`) cho development. Khóa live (`sk_live_`) trỏ đến production.
• Triển khai exponential backoff cho response 429. SDK tự động làm điều này.
• Xác minh chữ ký webhook bằng HMAC để ngăn replay attacks.
• Tải file trước khi tạo tài liệu. API cần media ID từ bước upload.
• Dùng pagination cho endpoint trả về danh sách. Đừng fetch tất cả cùng lúc.
• Kiểm tra hướng dẫn bảo mật trước khi go live.

Ví dụ use case

Trong thực tế, các team xây dựng những pattern này với API:

• Thương mại điện tử — tự động tạo hợp đồng mua bán cho đơn hàng giá trị cao và gửi ký khi thanh toán
• HR onboarding — tạo hợp đồng lao động từ template và gửi nhân viên mới vào ngày đầu
• Tích hợp CRM — kích hoạt yêu cầu chữ ký từ deal records Salesforce hoặc HubSpot
• Lưu trữ tài liệu — thêm xác minh blockchain cho tài liệu trong hệ thống storage hiện có

Bước tiếp theo

• Tài liệu API — tài liệu endpoint đầy đủ với ví dụ request/response
• SDK — Server SDK và Embed SDK với hướng dẫn theo framework
• Webhooks — thiết lập thông báo sự kiện thức gian
• Bắt đầu nhanh — chạy tích hợp đầu tiên trong 10 phút
• Cài đặt — thiết lập npm cho mọi framework được hỗ trợ