Tài liệu tích hợp Ký số Server & Hợp đồng điện tử MATBAO-CA

Môi trường Hệ thống (Base URL)

Hệ thống cung cấp hai môi trường hoạt động phục vụ quá trình phát triển tích hợp phần mềm cấu hình:

1. Lấy token xác thực (auth/token-matbaoca)

Tham số dữ liệu Request Body

{
  // Request Body
  "taxcode": "0302712571-999",
  "username": "demo@matbao.com",
  "password": "password_bi_mat"
}

// Response Body
{
  "Success": true,
  "Data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Chuỗi mã hóa Bearer Access Token dùng định danh
  "ErrorCode": null,
  "CustomData": {
    "TokenExpired": "2026-12-31 23:59:59" // Thời điểm hết hạn token xác thực
  }
}

2. Lấy thông tin chứng thư số CERT (signing-matbaoca/getcert)

Dữ liệu trả về (Data): Trả về cấu trúc đối tượng dữ liệu chứng thư số chuẩn hệ thống định dạng X509Certificate2.

3. Ký số file PDF định vị tọa độ (signing-matbaoca/signature-pdf)

Bảng đặc tả tham số Request đồ sộ

{
  "Success": true,
  "Data": "JVBERi0xLjQKJ..." // Toàn bộ nội dung file PDF sau khi đóng chữ ký số thành công ở dạng chuỗi Base64
  "ErrorCode": null,
  "CustomData": ""
}

4. Ký số dữ liệu XML (signing-matbaoca/signature-xml)

Tham số đầu vào: XmlDataBase64 (Chuỗi nội dung tệp xml thô mã hóa), SignatureLocation (ID định danh phân vùng cần thực hiện chèn thẻ ký), và NodeToBeSigned (Đường dẫn XPath của thẻ xuất hiện khối chữ ký, ví dụ cấu trúc ký hóa đơn thương mại dùng: //DSCKS/NBan).

5. Ký dữ liệu chuỗi Hash (signing-matbaoca/signature-hash)

Request truyền tham số Data dạng chuỗi chứa dữ liệu cần băm ký, trả về Data là chuỗi kết quả đã ký xác thực số hoàn tất.

6. Hàm tạo hợp đồng từ template có sẵn - File HTML cũ (signing-matbaoca/create-doc)

Request Body truyền tham số gồm khóa định danh TemplateID và khối dữ liệu đối tượng JSON động Data chứa các cặp key-value biến đổi để map đổ dữ liệu vào biểu mẫu hợp đồng tương ứng.

7. Hàm tạo hợp đồng từ template thiết kế Web mới (signing-matbaoca/create-doc-v2)

Đặc tả trường tham số nâng cao

8. Hàm tạo đồng loạt nhiều hợp đồng từ mẫu (signing-matbaoca/create-multi-doc)

URL: POST <BaseUrl>/signing-matbaoca/create-multi-doc

Cấu trúc request yêu cầu mảng thông tin tài khoản thụ hưởng nhận diện AccountsDocument chứa danh sách Email khách hàng tiếp nhận (Accounts/Email), kèm MaHopDong, TenHopDong riêng biệt của từng thành tố.

9. Hàm xem chi tiết thông tin hợp đồng (signing-matbaoca/view-doc)

URL: POST <BaseUrl>/signing-matbaoca/view-doc

Tham số truyền bao gồm mã DocumentID (UUID nhận về khi tạo thành công tài liệu), mã quản lý DocumentCode và trường phân loại Type (0: Không lấy dữ liệu Base64 file; 1: Lấy đầy đủ chuỗi ContentPDF chứa nội dung file phục vụ preview trực tiếp trên app).

10. Lưu hợp đồng kèm mẫu hình ảnh chữ ký tay (signing-matbaoca/signature-document)

11. Hàm tải lên và lưu trữ hợp đồng có sẵn tệp PDF (signing-matbaoca/upload-doc)

URL: POST <BaseUrl>/signing-matbaoca/upload-doc

Tham số: DocumentId (Khóa định danh tài liệu) và trường ContentPDF chứa dữ liệu nội dung file PDF cấu trúc của hợp đồng.

12. Hàm cập nhật trạng thái tiến trình hợp đồng (signing-matbaoca/upload-status)

URL: POST <BaseUrl>/signing-matbaoca/upload-status

Tham số điều khiển gồm DocumentId và chuỗi quy định trạng thái Status đồng bộ bắt buộc nhận một trong các giá trị chuẩn sau: DRAFT (Nháp), PROCESSING (Đang thực hiện luồng ký), DONE (Hoàn thành), CANCEL (Hủy bỏ hồ sơ), REJECT (Khách từ chối ký), ERROR (Lỗi xử lý nghiệp vụ), hoặc EXPIRE (Hết hạn thời hiệu hiệu lực).

13. Đăng ký thông tin dịch vụ cấp phát chứng thư (signing/register)

Gửi dữ liệu hồ sơ pháp lý khách hàng để phục vụ quy trình thẩm định bao gồm thông tin: HoTen, ChucVu, Khoa (Phòng ban), CMND (Số thẻ căn cước), NgayCap, LoaiGiayTo, Email, DienThoai, GhiChu và mảng tệp đính kèm hình ảnh hồ sơ gốc Files chứa cụm đối tượng con gồm file_name và base64_file.

14. Hàm tra cứu danh sách quản lý hợp đồng (signing-matbaoca/view-list-docs)

Tham số lọc Request Body (Pagination & Filter)

15. Hàm lấy danh sách các mẫu template hợp đồng (signing-matbaoca/view-list-templates)

URL: POST <BaseUrl>/signing-matbaoca/view-list-templates

Tham số Request gồm: SearchText (Tìm theo tên hoặc mã code mẫu), PageSize, và PageNumber. Trả về thông tin chi tiết định nghĩa cấu trúc mảng trường Columns cấu thành và khu vực phân vùng thiết lập chữ ký SignatureRegion của mẫu hợp đồng biểu mẫu.

16. Hàm thực hiện ký số trực tiếp lên hợp đồng tài liệu (signing-matbaoca/sign-document)

URL: POST <BaseUrl>/signing-matbaoca/sign-document

Request Payload truyền tham số định danh: DocumentId (Mã hợp đồng cần ký số) và trường dữ liệu tệp hình ảnh con dấu đại diện FileContentSignatureImage lưu dưới cấu trúc định dạng mã hóa chuỗi Base64 hoàn chỉnh.

17. Cấu hình cấu trúc JSON Payload Webhook Callback

Hệ thống hỗ trợ 2 loại sự kiện Webhook tự động kích hoạt đẩy dữ liệu trạng thái thời gian thực sang cổng đối tác: "Có người ký" (Kích hoạt ngay khi có một thực thể trong luồng ký hoàn tất) và sự kiện "Hoàn tất" (Kích hoạt khi toàn bộ các bên đã hoàn thành việc ký số).

{
  "Success": true,
  "CustomData": "200",
  "Data": {
    "DocumentStatus": "DONE", // Trạng thái tiến độ hồ sơ tổng quát: DONE (Hoàn thành) hoặc PROCESSING (Đang ký)
    "DocumentId": "b1a2c3d4-e5f6-...", // Khóa định danh hợp đồng điện tử duy nhất
    "ContentPDF": "https://api-econtract-mbc.matbao.in/storage/downloads/file.pdf", // Link tải file PDF hợp đồng trực tuyến
    "SignatoryData": [ // Mảng chi tiết thông tin tiến độ của từng người ký trong luồng biểu mẫu
      {
        "Status": "DONE", // Trạng thái người ký: DONE (Đã ký), PROCESSING (Đang ký), DRAFT (Chờ người khác ký)
        "FullName": "Nguyễn Văn A",
        "Email": "nguyenvana@gmail.com",
        "IsCurrentSigner": false // Chỉ định đây có phải là người đang giữ lượt ký hiện hành hay không
      }
    ]
  },
  "ErrorCode": null
}