Chaindoc logoChaindoc

Tài liệu API REST của Chaindoc

Đây là vấn đề với các nhà phát triển: cần một tài liệu tham khảo đầy đủ. Trong thực tế, bạn sẽ tìm thấy mọi endpoint của Chaindoc REST API. Bao gồm xác thực, tài liệu, chữ ký, tải media, phiên embedded và xác minh blockchain.

Tổng quan

API cho phép bạn truy cập lập trình vào mọi thứ trong Chaindoc: tài liệu, chữ ký, xác minh blockchain và quản lý team. Thiết kế này dành cho server-to-server, hỗ trợ cả public và secret API key.

  • Tài liệu — tạo, cập nhật và xác minh tài liệu trên blockchain
  • Chữ ký — gửi yêu cầu ký và theo dõi tiến độ
  • Media — tải lên PDF, hình ảnh và video (tối đa 10 mỗi request)
  • Phiên embedded — tạo phiên ký cho frontend (dùng Embed SDK)
  • KYC — chia sẻ và xác minh dữ liệu danh tính qua tích hợp Sumsub

Xác thực

Mọi request cần API key trong header Authorization. Có hai loại:

Loại key

  • Public key (`pk_`) — chỉ đọc, an toàn cho frontend code
  • Secret key (`sk_`) — đọc/ghi đầy đủ, chỉ dùng backend. Đừng bao giờ expose trong client-side code.

Lấy key của bạn

1Đăng ký gói BusinessChỉ ngườí dùng gói Business mới tạo được API key

2Vào API AccessVào Settings → API Access trong dashboard

3Tạo API keyClick nút Create API Key

4Lưu trữ an toànLưu secret key an toàn (chỉ hiển thị một lần)

Sử dụng API key

Thêm API key vào header Authorization với Bearer authentication:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Giới hạn rate

API endpoints bị giới hạn rate để ngăn lạm dụng. Giới hạn khác nhau tùy loại endpoint.

  • General endpoints: 3 requests mỗi 10 giây
  • Media upload: 3 requests mỗi 10 giây
  • OTP verification: 5 requests mỗi 60 giây
  • Read operations: 10 requests mỗi 60 giây
  • Signature creation: 20 requests mỗi 3 giây

Khi vượt quá giới hạn rate, bạn sẽ nhận được response 429 Too Many Requests. Headers giới hạn rate được bao gồm:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Xử lý lỗi

HTTP status codes

  • 200 - Thành công
  • 201 - Tạo resource thành công
  • 400 - Bad request (lỗi validation)
  • 401 - Unauthorized (API key không hợp lệ hoặc thiếu)
  • 403 - Forbidden (không đủ quyền)
  • 404 - Không tìm thấy resource
  • 429 - Quá nhiều requests (vượt giới hạn rate)
  • 500 - Lỗi server nội bộ

Định dạng response lỗi

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

API chung

Lấy thông tin API key

Lấy thông tin về API key hiện tại.

GET /me

Authorization: Bearer sk_live_xxxxx

Kiểm tra kết nối

Xác minh kết nối API và tính hợp lệ của key.

GET /health

Authorization: Bearer sk_live_xxxxx

Documents API

Tạo tài liệu

Tạo tài liệu mới với xác minh blockchain. Khi status đặt là 'published', tài liệu tự động được xác minh trên blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Cập nhật tài liệu

Cập nhật tài liệu bằng cách tạo phiên bản mới. Các phiên bản trước được giữ lại cho audit trail.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Cập nhật quyền truy cập tài liệu

Cập nhật cài đặt kiểm soát truy cập tài liệu.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Xác minh tài liệu

Xác minh tính xác thực của tài liệu bằng blockchain. Trả về status xác minh với transaction hash và chain ID.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Lấy trạng thái xác minh

Lấy trạng thái xác minh blockchain cho phiên bản tài liệu.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Signatures API

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

Tạo yêu cầu chữ ký cho một hoặc nhiều ngườí nhận. Bật embedded flow để tích hợp frontend.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Lấy trạng thái yêu cầu chữ ký

Kiểm tra trạng thái yêu cầu chữ ký và xem ai đã hoàn thành việc ký.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Ký tài liệu

Ký tài liệu (nếu chủ API key là ngườí ký).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Lấy chữ ký ngườí dùng

Lấy tất cả chữ ký của ngườí dùng đã xác thực.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Lấy các yêu cầu chữ ký

Lấy tất cả yêu cầu chữ ký cho ngườí dùng đã xác thực, hỗ trợ pagination.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

Media upload API

Tải lên file để dùng khi tạo tài liệu. Hỗ trợ PDF, hình ảnh và video. Tối đa 10 file mỗi request.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

KYC API

Chia sẻ dữ liệu KYC

Chia sẻ dữ liệu KYC (Know Your Customer) với ngườí nhận để xác minh danh tính.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Embedded sessions API

Tạo phiên embedded để ký tài liệu trong ứng dụng frontend. Phiên có hiệu lực 10 phút.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Tiếp theo làm gì?

  • Tích hợp API — pattern phổ biến, best practice và ví dụ workflow đầy đủ
  • SDKs — 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 real-time
  • Cài đặt — npm setup cho mọi framework được hỗ trợ
  • Bảo mật — quản lý API key và compliance