Chaindoc logoChaindoc

Tham chiếu API REST Chaindoc

Hướng dẫn chi tiết để tích hợp API REST của Chaindoc vào ứng dụng của cậu. Quản lý tài liệu, chữ ký, xác minh blockchain và quy trình ký điện tử nhúng.

Tổng quan

Chaindoc REST API cung cấp quyền truy cập lập trình vào quản lý tài liệu, xác minh blockchain và chức năng chữ ký số. API được thiết kế cho tích hợp máy chủ với máy chủ và hỗ trợ cả khóa API công khai và bí mật.

Tính năng chính

  • Quản lý tài liệu - Tạo, cập nhật và quản lý tài liệu với xác minh blockchain
  • Chữ ký số - Yêu cầu và thu thập chữ ký số từ nhiều bên
  • Xác minh Blockchain - Xác minh tính xác thực của tài liệu trên các mạng blockchain
  • Phiên làm việc nhúng - Tạo các phiên làm việc an toàn cho quy trình ký kết phía client
  • Tải lên phương tiện - Tải lên các tệp (PDF, hình ảnh, video) để tạo tài liệu
  • Tích hợp KYC - Chia sẻ và xác minh dữ liệu nhận dạng với Sumsub

Xác thực

Chaindoc API sử dụng khóa API để xác thực. Có hai loại khóa với các mức truy cập khác nhau.

Các loại khóa API

  • Khóa công khai (pk_) - Quyền truy cập chỉ đọc cho các ứng dụng frontend và xác minh
  • Khóa bí mật (sk_) - Quyền truy cập đọc và ghi đầy đủ cho các máy chủ phía sau

Lấy khóa API

1Đăng ký Kế hoạch Kinh doanhChỉ người dùng gói Business plan mới có thể tạo khóa API.

2Truy cập vào API AccessĐi đến Cài đặt → Truy cập API trong bảng điều khiển của cậu

3Tạo khóa APINhấp vào nút Tạo khóa API

4Lưu trữ an toànLưu trữ khóa bí mật một cách an toàn (chỉ hiển thị một lần)

Sử dụng API Keys

Thêm khóa API của cậu vào tiêu đề Authorization với xác thực Bearer:

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

Giới hạn tốc độ

Các điểm cuối API bị giới hạn tốc độ để ngăn chặn việc lạm dụng. Giới hạn tốc độ thay đổi tùy theo loại điểm cuối.

  • Điểm cuối chung: 3 yêu cầu mỗi 10 giây
  • Tải lên phương tiện: 3 yêu cầu mỗi 10 giây
  • Xác minh OTP: 5 yêu cầu mỗi 60 giây
  • Hoạt động đọc: 10 yêu cầu mỗi 60 giây
  • Tạo chữ ký: 20 yêu cầu mỗi 3 giây

Khi vượt quá giới hạn yêu cầu, cậu sẽ nhận được phản hồi 429 Too Many Requests. Các tiêu đề giới hạn yêu cầu được bao gồm trong phản hồi:

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

Xử lý lỗi

Mã trạng thái HTTP

  • 200 - Thành công
  • 201 - Tài nguyên đã được tạo thành công
  • 400 - Yêu cầu không hợp lệ (lỗi xác thực)
  • 401 - Không được phép (khóa API không hợp lệ hoặc thiếu)
  • 403 - Cấm (quyền truy cập không đủ)
  • 404 - Tài nguyên không tìm thấy
  • 429 - Quá nhiều yêu cầu (vượt quá giới hạn tốc độ)
  • 500 - Lỗi máy chủ nội bộ

Định dạng phản hồi lỗi

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

API chung

Nhận thông tin khóa API

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

GET /me

Authorization: Bearer sk_live_xxxxx

Kiểm tra sức khỏe

Kiểm tra kết nối API và tính hợp lệ của khóa.

GET /health

Authorization: Bearer sk_live_xxxxx

API Tài liệu

Tạo tài liệu

Tạo một tài liệu mới với xác minh blockchain. Khi trạng thái được đặt thành 'đã xuất bản', tài liệu sẽ được xác minh tự động 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 lưu trữ để theo dõi lịch sử thay đổi.

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ề trạng thái xác minh kèm theo băm giao dịch và ID chuỗi.

POST /documents/verify

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

Kiểm tra trạng thái xác minh

Kiểm tra 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

API Chữ ký

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

Tạo yêu cầu chữ ký cho một hoặc nhiều người nhận. Kích hoạt chế độ nhúng để tích hợp với giao diện người dùng.

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
  }'

Kiểm tra trạng thái yêu cầu chữ ký

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

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Ký tài liệu

Ký vào tài liệu (nếu chủ sở hữu khóa API là người ký).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Lấy chữ ký của người dùng

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

GET /signatures

Authorization: Bearer sk_live_xxxxx

Nhận yêu cầu ký tên

Lấy tất cả yêu cầu chữ ký cho người dùng đã xác thực với hỗ trợ phân trang.

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

Authorization: Bearer sk_live_xxxxx

API Tải lên Phương tiện

Tải lên các tệp để sử dụng trong quá trình tạo tài liệu. Hỗ trợ các định dạng PDF, hình ảnh và video. Tối đa 10 tệp cho mỗi yêu cầu.

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

API KYC

Chia sẻ dữ liệu KYC

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

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API Phiên làm việc nhúng

Tạo các phiên làm việc nhúng cho việc ký tài liệu trong ứng dụng frontend của cậu. Các phiên này có hiệu lực trong 10 phút.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json