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-sdkThiế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.
# 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.ioKhởi tạo SDK
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
// 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-sdkTù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_xxxxxKhở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)
'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)
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
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
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.
{
"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
// 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
// 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:
# npm
rm -rf node_modules package-lock.json
npm install
# yarn
rm -rf node_modules yarn.lock
yarn installLỗ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.
npm install --save-dev @types/nodeLỗ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