Chaindoc logoChaindoc

Cài đặt

Tích hợp SDK Chaindoc vào dự án của bạn. Có hai gói: Server SDK cho công việc backend (tài liệu, chữ ký, xác minh) và Embed SDK để nhúng giao diện ký vào frontend.

Trước khi bắt đầu

Nếu bạn chưa có tài khoản, hãy bắt đầu với hướng dẫn bắt đầu nhanh để thiết lập tài khoản.

Server SDK

Server SDK xử lý mọi thứ trên backend: tạo tài liệu, gửi yêu cầu chữ ký, quản lý nhóm, và kích hoạt xác minh blockchain. Đây là một lớp wrapper mỏng quanh REST API, nên nếu bạn đã đọc tài liệu API, tên các phương thức sẽ rất quen thuộc.

Cài đặt gói

npm install @chaindoc_io/server-sdk

Thiết lập biến môi trường

Tạo file `.env` trong thư mục gốc dự án. Bạn cần nhập secret key ở đây.

.env
# Production keys
CHAINDOC_SECRET_KEY=sk_live_xxxxxxxxxxxxx

# Staging/Testing keys
# CHAINDOC_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Optional: Custom API endpoint
# CHAINDOC_API_URL=https://api.chaindoc.io

Khởi tạo SDK

lib/chaindoc.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';

// Basic initialization
export const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Advanced configuration
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  baseUrl: process.env.CHAINDOC_API_URL, // Optional
  timeout: 60000, // 60 seconds
  retry: {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

Cấu hình cơ bản là đủ cho hầu hết các dự án. Cài đặt thử lại đáng để điều chỉnh nếu bạn đang xử lý nhiều tài liệu hàng loạt, vì API có giới hạn tốc độ.

Xác minh kết nối

terminal
// Test API connection
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('Connected to Chaindoc API');
  console.log('User ID:', health.userId);
} else {
  console.error('Connection failed');
}

Nếu điều này thất bại, hãy kiểm tra lại xem secret key của bạn có bắt đầu bằng `sk_live_` (production) hoặc `sk_test_` (sandbox) không. Vấn đề phổ biến nhất là vô tình sử dụng public key.

Embed SDK

Embed SDK cho phép bạn hiển thị giao diện ký Chaindoc bên trong ứng dụng web. Người dùng ký tài liệu mà không cần rời khỏi trang web của bạn. Nó hoạt động với React, Vue, Angular hoặc JavaScript thuần.

Cài đặt gói

npm install @chaindoc_io/embed-sdk

Tùy chọn CDN rất tiện cho prototype nhanh hoặc các trang không có bước build. Đối với production, hãy sử dụng gói npm để có tree-shaking và kiểm soát phiên bản phù hợp.

Thiết lập biến môi trường

Embed SDK sử dụng public key (`pk_`), có thể an toàn đưa vào code phía client.

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx
# or for Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx

Khởi tạo trong ứng dụng

// hooks/useChaindoc.ts
import { useRef, useEffect } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export function useChaindoc() {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.REACT_APP_CHAINDOC_PUBLIC_KEY!,
      environment: 'production',
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return sdkRef.current;
}

Thiết lập theo framework

Các ví dụ sau cho thấy cách kết nối Embed SDK như một provider hoặc service trong từng framework. Nếu bạn đang sử dụng Server SDK trên backend, bạn không cần provider; chỉ cần import nó khi cần.

Next.js (App Router)

app/providers.tsx
'use client';

import { createContext, useContext, useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

const ChaindocContext = createContext<ChaindocEmbed | null>(null);

export function ChaindocProvider({ children }: { children: React.ReactNode }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    if (!sdkRef.current) {
      sdkRef.current = new ChaindocEmbed({
        publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
      });
    }

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return (
    <ChaindocContext.Provider value={sdkRef.current}>
      {children}
    </ChaindocContext.Provider>
  );
}

export const useChaindoc = () => useContext(ChaindocContext);

Next.js (Pages Router)

pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default function App({ Component, pageProps }: AppProps) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return <Component {...pageProps} />;
}

Nuxt 3

plugins/chaindoc.client.ts
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const chaindoc = new ChaindocEmbed({
    publicKey: config.public.chaindocPublicKey,
  });

  return {
    provide: {
      chaindoc,
    },
  };
});

Angular

services/chaindoc.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';
import { environment } from '../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class ChaindocService implements OnDestroy {
  private sdk: ChaindocEmbed;

  constructor() {
    this.sdk = new ChaindocEmbed({
      publicKey: environment.chaindocPublicKey,
    });
  }

  getSdk(): ChaindocEmbed {
    return this.sdk;
  }

  ngOnDestroy(): void {
    this.sdk.destroy();
  }
}

Cấu hình TypeScript

Cả hai SDK đều đi kèm với định nghĩa TypeScript đầy đủ. Bạn không cần cài thêm gói `@types` nào.

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Nếu bạn đang sử dụng TypeScript cũ (< 5.0), hãy dùng `"moduleResolution": "node"` thay vì `"bundler"`.

Phát triển và sản xuất

Sử dụng test keys trong quá trình phát triển để không vô tình tạo tài liệu thực hoặc gửi email chữ ký đến người nhận thực.

Thiết lập môi trường phát triển

terminal
// Use test keys for development
const chaindoc = new Chaindoc({
  secretKey: 'sk_test_xxxxx',
  baseUrl: 'https://api.chaindoc.io',
});

const embed = new ChaindocEmbed({
  publicKey: 'pk_test_xxxxx',
  environment: 'staging',
  debug: true, // Enable detailed logs
});

Cờ `debug: true` in chi tiết request/response ra console. Nó nhiều log, nhưng hữu ích khi bạn đang tìm hiểu lý do điều gì đó không hoạt động.

Thiết lập môi trường sản xuất

terminal
// Use live keys for production
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!, // sk_live_xxxxx
});

const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!, // pk_live_xxxxx
  environment: 'production',
});

Xác minh cài đặt

Thực hiện các kiểm tra sau để đảm bảo mọi thứ được kết nối đúng:

1Kiểm tra phiên bản SDKChạy `console.log(ChaindocEmbed.version)` trong ứng dụng. Nếu in ra số phiên bản, gói đã cài đặt đúng.

2Kiểm tra kết nối APIGọi `chaindoc.healthCheck()` từ backend. Phản hồi thành công có nghĩa là secret key hợp lệ và API có thể truy cập.

3Thử upload fileUpload một file PDF test nhỏ bằng `chaindoc.media.upload()`. Điều này xác nhận auth, networking và xử lý file đều hoạt động.

4Mở giao diện kýKhởi tạo Embed SDK và gọi `openSignatureFlow()` với session test. Nếu modal hiện ra, bạn đã sẵn sàng.

Xử lý sự cố

Lỗi "Không tìm thấy module"

Điều này thường có nghĩa là gói chưa cài đúng hoặc có xung đột phiên bản cache. Xóa mọi thứ và cài lại:

terminal
# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

Lỗi kiểu TypeScript

Đảm bảo bạn đã cài types của Node.js và `tsconfig.json` sử dụng đúng module resolution. Hầu hết các vấn đề đến từ cài đặt `moduleResolution` không khớp.

terminal
npm install --save-dev @types/node

Lỗi khóa API

Nếu bạn nhận được phản hồi 401 hoặc 403, đây là những điều cần kiểm tra:

  • 401 Unauthorized nghĩa là khóa không hợp lệ hoặc đã hết hạn. Tạo lại trong bảng điều khiển.
  • 403 Forbidden nghĩa là gói của bạn không bao gồm quyền truy cập API. Bạn cần gói Business.
  • Đảm bảo bạn đang sử dụng đúng loại khóa: khóa `pk_` dành cho Embed SDK (frontend), khóa `sk_` dành cho Server SDK (backend). Nhầm lẫn đây là lỗi phổ biến nhất.
  • Test keys (`_test_`) chỉ hoạt động với sandbox. Live keys (`_live_`) truy cập production.

Tiếp theo làm gì

Bây giờ SDK đã được cài đặt, hãy chọn bước tiếp theo:

  • Bắt đầu nhanh — gửi yêu cầu chữ ký đầu tiên trong 10 phút
  • Tài liệu API — tài liệu tham khảo endpoint đầy đủ với ví dụ
  • SDK — tính năng SDK nâng cao và hướng dẫn theo từng framework
  • Webhooks — thiết lập thông báo sự kiện theo thời gian thực
  • Thực hành bảo mật tốt nhất — những gì cần cấu hình trước khi đưa lên production