Hướng dẫn bắt đầu nhanh

Bắt đầu sử dụng Chaindoc trong vòng 10 phút. Hướng dẫn này sẽ đi qua cả giao diện web và API, để bạn có thể chọn con đường phù hợp.

Ký qua giao diện web

Bạn không cần viết code để gửi yêu cầu chữ ký đầu tiên. Ứng dụng web xử lý mọi thứ: tải lên, ngườ nhận, quy trình ký và xác minh blockchain.

Từng bước: chữ ký đầu tiên của bạn

Muốn hiểu các loại chữ ký khác nhau (đơn giản, nâng cao, đủ tiêu chuẩn)? Điều đó quan trọng cho việc tuân thủ. Hầu hết hợp đồng kinh doanh hoạt động tốt với chữ ký điện tử đơn giản, nhưng các ngành được quản lý thường cần nâng cao hoặc đủ tiêu chuẩn.

Tích hợp qua API

Nếu bạn đang xây dựng tính năng ký vào ứng dụng của mình, bạn sẽ sử dụng REST API và TypeScript SDK. Quy trình giống như giao diện web, chỉ là tự động hóa.

1. Lấy API keys

Truy cập API cần gói Business. Vào Settings > API Access trong bảng điều khiển và tạo hai key:

• Public key (`pk_`) để sử dụng frontend với Embed SDK
• Secret key (`sk_`) để sử dụng backend với Server SDK. Giữ key này khỏi code client-side.

2. Cài đặt SDK

Chọn SDK phù hợp với use case của bạn. Hầu hết ứng dụng cần cả hai: Server SDK để tạo tài liệu và Embed SDK cho giao diện ký.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

Để biết chi tiết thiết lập framework (React, Vue, Angular, Next.js), xem hướng dẫn cài đặt.

3. Tải lên và tạo tài liệu

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

Đặt `status: 'published'` sẽ kích hoạt xác minh blockchain tự động. Nếu muốn chờ, dùng `'draft'` và xuất bản sau.

4. Tạo yêu cầu chữ ký

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Đặt `embeddedFlow: true` nếu bạn sẽ hiển thị giao diện ký trong ứng dụng của mình. Nếu không, ngườ ký sẽ nhận link đến trang ký được lưu trữ của Chaindoc.

5. Hiển thị giao diện ký (frontend)

Đây là tùy chọn. Nếu bạn đặt `embeddedFlow: true`, bạn có thể mở giao diện ký ngay trong ứng dụng. Trước tiên, tạo session trên backend, sau đó truyền session ID sang frontend.

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. Kiểm tra trạng thái và lắng nghe sự kiện

Bạn có thể poll trạng thái, nhưng webhooks là lựa chọn tốt hơn cho production. Chúng sẽ thông báo cho server của bạn ngay khi có điều gì đó xảy ra.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Thiết lập webhooks (khuyến nghị)

Webhooks đẩy sự kiện đến server của bạn theo thờ gian thực, để bạn không phải liên tục kiểm tra. Đây là một handler Express cơ bản:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

Trong production, bạn nên xác minh chữ ký webhook với HMAC để đảm bảo payload thực sự đến từ Chaindoc. Hướng dẫn webhooks sẽ trình bày chi tiết về điều này.

Ví dụ quy trình đầy đủ

Đây là tổng hợp tất cả: tải lên, tạo, ký, xác minh. Sao chép, thay API keys của bạn, và bạn đã có một prototype hoạt động.

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

Tiếp theo đi đâu

Bây giờ bạn đã nắm được những điều cơ bản, đây là những gì cần tìm hiểu tùy theo những gì bạn đang xây dựng:

• Cài đặt — thiết lập cụ thể cho React, Vue, Angular và Next.js
• Tài liệu API — tài liệu endpoint đầy đủ với ví dụ request/response
• SDKs — Server SDK và Embed SDK, với hướng dẫn tích hợp cho từng framework
• Webhooks — thông báo sự kiện theo thờ gian thực cho ứng dụng production
• Best practice bảo mật — những gì cần khóa trước khi đưa lên production

Câu hỏi thường gặp

Xác minh blockchain mất bao lâu?

Thường 1-5 phút, tùy thuộc vào mạng. Tài liệu của bạn có sẵn ngay lập tức. Xác minh chạy trong nền và bạn sẽ nhận được sự kiện webhook khi hoàn thành.

Tôi có thể test API mà không cần trả phí không?

Gói miễn phí cho bạn truy cập giao diện web. Truy cập API cần gói Business, nhưng môi trường sandbox cho phép bạn test mọi thứ mà không ảnh hưởng đến dữ liệu thực hoặc sử dụng quota.

Những chữ ký này có ràng buộc pháp lý không?

Có. Chữ ký Chaindoc tuân thủ eIDAS ở châu Âu, ESIGN Act và UETA ở Mỹ, và các quy định tương đương ở hầu hết các quốc gia khác. Xác minh blockchain thêm một lớp bằng chứng ngoài đó, điều này có thể quan trọng trong các tranh chấp. Xem tài liệu chữ ký để biết chi tiết loại chữ ký nào phù hợp với nhu cầu tuân thủ của bạn.

Tôi có thể tải lên định dạng file nào?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV và WMV. Kích thước file tối đa là 50MB.