Mobile-ID Sign · TÍCH HỢP & THỰC HÀNH

Trusted SIC 1.7.260928 — Tài liệu phiên bản trước

Nội dung 1.7.260928 được giữ để đối chiếu. Không suy các operation ở đây tồn tại trong bản Compact 1.7.261001 hoặc đang hoạt động ở production.

Trung tâm Nhà phát triển Xem demo Agent

TRONG TRANG NÀY

Mức bao phủ và điều kiện tích hợp

Tài liệu có dẫn nguồn; mức xác nhận đặc tả, thử nghiệm sandbox và nghiệm thu production là các bước độc lập. Việc đổi phiên bản website không thay thế xác nhận tích hợp.

Xem mức bao phủ của từng operation

Trạng thái theo operation
Operation	Mức tài liệu	Đặc tả	Sandbox
`POST /v2/credentials/authorize`	Trường chọn lọc	Chưa có xác nhận triển khai	Chưa kiểm thử
`POST /v2/credentials/authorizeCheck`	Trường chọn lọc	Chưa có xác nhận triển khai	Chưa kiểm thử
`POST /v2/signatures/signHash`	Trường chọn lọc	Chưa có xác nhận triển khai	Chưa kiểm thử
`POST /v2/signatures/signPolling`	Trường chọn lọc	Chưa có xác nhận triển khai	Chưa kiểm thử
`POST /v2/credentials/info`	Trường chọn lọc	Chưa có xác nhận triển khai	Chưa kiểm thử

Tải OpenAPI đúng phạm vi · Tải Postman đọc đặc tả

Đối chiếu phiên bản mới

SIC Compact và migration

Phạm vi và tài sản

Nguồn: Trusted SIC 1.7.260928. Phần OpenAPI trong trang này gồm 5 operation được biên tập; danh mục bên dưới giữ các chức năng khác của nguồn. Đây chưa phải hợp đồng API vận hành thực tế đã nghiệm thu.

OpenAPI JSON · 1.7.260928 OpenAPI YAML · 1.7.260928 Postman · 1.7.260928 Environment · 1.7.260928

Thao tác API và cấu trúc dữ liệu

POST/v2/credentials/authorize

Cấp quyền cho digest

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

OperationId: SicAuthorize · Trusted SIC 1.7.260928 · Trang PDF: 30, 31

Trích từ nguồn; môi trường triển khai chưa xác nhận. Ví dụ đầu vào dùng để đọc và đối chiếu, chưa cấu hình gọi dịch vụ thật.

Điều kiện và xác thực

Chọn credential; cố định digest và số chữ ký cần cấp quyền. Giao diện người dùng phải liên kết với đúng nội dung yêu cầu. Token Bearer giữ phía máy chủ; không đưa token/SAD vào frontend hoặc log công khai.

Yêu cầu · application/json

Cấu trúc yêu cầu
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`credentialID`	string	Bắt buộc	Identifier credential dùng cho operation.
`numSignatures`	integer	Bắt buộc	Số chữ ký yêu cầu cấp quyền.
`documentDigests`	object	Bắt buộc
`documentDigests.hashes`	string[]	Bắt buộc	Digest Base64 của nội dung được cấp quyền.
`documentDigests.hashAlgorithmOID`	string	Bắt buộc	OID thuật toán băm; chọn theo cấu hình được xác nhận.
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả yêu cầu cho người dùng.
`agreementUUID`	string	Tùy chọn / theo điều kiện nguồn	Mã liên kết clientData theo nguồn.
`username`	string	Tùy chọn / theo điều kiện nguồn	Tên người dùng theo ngữ cảnh cấp quyền.
`clientInfo`	object	Tùy chọn / theo điều kiện nguồn
`clientInfo.application`	string	Tùy chọn / theo điều kiện nguồn	Tên ứng dụng khởi tạo.
`view`	object	Tùy chọn / theo điều kiện nguồn
`view.lang`	string	Tùy chọn / theo điều kiện nguồn	Ngôn ngữ giao diện. enum: VI, EN
`view.callbackUrl`	string	Tùy chọn / theo điều kiện nguồn	URL callback đã đăng ký. format: uri
`view.redirectUrl`	string	Tùy chọn / theo điều kiện nguồn	URL chuyển hướng đã đăng ký. format: uri
`view.fontSize`	string	Tùy chọn / theo điều kiện nguồn	Cấu hình cỡ chữ giao diện.
`view.templateUiId`	string	Tùy chọn / theo điều kiện nguồn	Mã mẫu giao diện.
`view.expiresIn`	integer	Tùy chọn / theo điều kiện nguồn	Đơn vị/ý nghĩa cần xác nhận; không cung cấp mặc định.

Payload minh họa — Chưa chạy với dịch vụ

{
  "credentialID": "DEMO_SIC_CREDENTIAL",
  "numSignatures": 1,
  "documentDigests": {
    "hashes": [
      "ypeBEsobvcr6wjGzmiPcTaeG7/gUfE5yuYB3ha/uSLs="
    ],
    "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
  }
}

Phản hồi · 202

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi 202
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`token`	string	Bắt buộc	Token của bước trước; không ghi vào log công khai.

Phản hồi · Mặc định

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi mặc định
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`code`	string	Tùy chọn / theo điều kiện nguồn	Mã lỗi theo dịch vụ; không phải HTTP status.
`message`	string	Tùy chọn / theo điều kiện nguồn	Thông báo lỗi ngắn.
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả chi tiết nếu có.

Hành động tiếp theo

Lưu token; mở giao diện cấp quyền được xác nhận, sau đó gọi authorizeCheck.

POST/v2/credentials/authorizeCheck

Tra cứu cấp quyền

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

OperationId: SicAuthorizeCheck · Trusted SIC 1.7.260928 · Trang PDF: 32, 33

Trích từ nguồn; môi trường triển khai chưa xác nhận. Ví dụ đầu vào dùng để đọc và đối chiếu, chưa cấu hình gọi dịch vụ thật.

Điều kiện và xác thực

Có token trả về từ authorize. Phân biệt đang xử lý và dữ liệu cấp quyền đã sẵn sàng; điều kiện xuất hiện trong nguồn cần xác nhận. Token Bearer giữ phía máy chủ; không đưa token/SAD vào frontend hoặc log công khai.

Yêu cầu · application/json

Cấu trúc yêu cầu
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`token`	string	Bắt buộc	Token của bước trước; không ghi vào log công khai.

Payload minh họa — Chưa chạy với dịch vụ

{
  "token": "DEMO_AUTHORIZATION_TOKEN"
}

Phản hồi · 200

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi 200
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`SAD`	string	Tùy chọn / theo điều kiện nguồn	Dữ liệu cấp quyền ký; gắn với nội dung đã được cấp quyền theo contract.
`credentialID`	string	Tùy chọn / theo điều kiện nguồn	Identifier credential dùng cho operation.
`expiresIn`	integer	Tùy chọn / theo điều kiện nguồn	Thời hạn SAD tính bằng giây theo bảng này.
`token`	string	Tùy chọn / theo điều kiện nguồn	Nếu có, nguồn mô tả giao dịch còn xử lý; điều kiện các trường cần xác nhận.

Phản hồi · Mặc định

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi mặc định
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`code`	string	Tùy chọn / theo điều kiện nguồn	Mã lỗi theo dịch vụ; không phải HTTP status.
`message`	string	Tùy chọn / theo điều kiện nguồn	Thông báo lỗi ngắn.
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả chi tiết nếu có.

Điểm cần xác nhận

SIC-02
SIC-06
SIC-09

Hành động tiếp theo

Chỉ chuyển sang ký khi đã nhận dữ liệu cấp quyền hợp lệ theo contract.

POST/v2/signatures/signHash

Ký hash đã cấp quyền

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

OperationId: SicSignHash · Trusted SIC 1.7.260928 · Trang PDF: 36, 37, 38

Trích từ nguồn; môi trường triển khai chưa xác nhận. Ví dụ đầu vào dùng để đọc và đối chiếu, chưa cấu hình gọi dịch vụ thật.

Điều kiện và xác thực

Có SAD hợp lệ theo contract cho credential và các digest tương ứng. Không thay nội dung sau cấp quyền; chốt signAlgo và chế độ ký trước gọi. Token Bearer giữ phía máy chủ; không đưa token/SAD vào frontend hoặc log công khai.

Yêu cầu · application/json

Cấu trúc yêu cầu
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`credentialID`	string	Bắt buộc	Identifier credential dùng cho operation.
`SAD`	string	Bắt buộc	Dữ liệu cấp quyền ký; gắn với nội dung đã được cấp quyền theo contract.
`hashes`	string[]	Bắt buộc	Digest đã được cấp quyền; giữ đúng nội dung.
`hashAlgorithmOID`	string	Bắt buộc	OID thuật toán băm; chọn theo cấu hình được xác nhận.
`signAlgo`	string	Bắt buộc	OID thuật toán ký; bắt buộc trong bảng, thiếu ở ví dụ nguồn.
`operationMode`	string	Tùy chọn / theo điều kiện nguồn	A: Bất đồng bộ; S: đồng bộ, mặc định S ở phần signHash. Không áp dụng mặc định này sang issue. enum: A, S; default: S
`clientInfo`	object	Tùy chọn / theo điều kiện nguồn
`clientInfo.application`	string	Tùy chọn / theo điều kiện nguồn	Tên ứng dụng khởi tạo.
`validityPeriod`	integer	Tùy chọn / theo điều kiện nguồn	Thời hạn lưu kết quả tính bằng mili giây theo bảng.

Payload minh họa — Chưa chạy với dịch vụ

{
  "credentialID": "DEMO_SIC_CREDENTIAL",
  "SAD": "DEMO_SAD_NOT_A_SECRET",
  "hashes": [
    "ypeBEsobvcr6wjGzmiPcTaeG7/gUfE5yuYB3ha/uSLs="
  ],
  "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1",
  "signAlgo": "1.2.840.113549.1.1.11"
}

Phản hồi · 200

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi 200
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`signatures`	string[]	Tùy chọn / theo điều kiện nguồn	Chữ ký Base64 khi hoàn tất.
`responseID`	string	Tùy chọn / theo điều kiện nguồn	Handle theo dõi kết quả ký; xem mâu thuẫn requestID trong ví dụ nguồn.

Phản hồi · Mặc định

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi mặc định
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`code`	string	Tùy chọn / theo điều kiện nguồn	Mã lỗi theo dịch vụ; không phải HTTP status.
`message`	string	Tùy chọn / theo điều kiện nguồn	Thông báo lỗi ngắn.
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả chi tiết nếu có.

Điểm cần xác nhận

SIC-02
SIC-04
SIC-10

Hành động tiếp theo

Nhận chữ ký hoặc handle theo chế độ đã xác nhận; hoàn thiện và kiểm chứng tài liệu.

POST/v2/signatures/signPolling

Tra cứu kết quả bất đồng bộ

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

OperationId: SicSignPolling · Trusted SIC 1.7.260928 · Trang PDF: 38, 39

Trích từ nguồn; môi trường triển khai chưa xác nhận. Ví dụ đầu vào dùng để đọc và đối chiếu, chưa cấu hình gọi dịch vụ thật.

Điều kiện và xác thực

Có handle của yêu cầu ký bất đồng bộ. Chốt tên trường responseID/requestID trước triển khai. Polling không khởi tạo một chữ ký mới. Token Bearer giữ phía máy chủ; không đưa token/SAD vào frontend hoặc log công khai.

Yêu cầu · application/json

Cấu trúc yêu cầu
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`responseID`	string	Bắt buộc	Handle theo dõi kết quả ký; xem mâu thuẫn requestID trong ví dụ nguồn.

Payload minh họa — Chưa chạy với dịch vụ

{
  "responseID": "DEMO_SIGN_RESPONSE"
}

Phản hồi · 200

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi 200
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`signatures`	string[]	Tùy chọn / theo điều kiện nguồn	Chữ ký khi việc tạo chữ ký hoàn tất.

Phản hồi · Mặc định

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi mặc định
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`code`	string	Tùy chọn / theo điều kiện nguồn	Mã lỗi theo dịch vụ; không phải HTTP status.
`message`	string	Tùy chọn / theo điều kiện nguồn	Thông báo lỗi ngắn.
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả chi tiết nếu có.

Điểm cần xác nhận

SIC-02
SIC-08

Hành động tiếp theo

Chốt responseID hay requestID trước tích hợp; không tạo lại để thay polling.

POST/v2/credentials/info

Đọc thông tin credential

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

OperationId: SicCredentialInfo · Trusted SIC 1.7.260928 · Trang PDF: 26, 27, 28, 29

Trích từ nguồn; môi trường triển khai chưa xác nhận. Ví dụ đầu vào dùng để đọc và đối chiếu, chưa cấu hình gọi dịch vụ thật.

Điều kiện và xác thực

Có credentialID cần kiểm tra. Chọn mức thông tin chứng thư và cơ chế cấp quyền cần đọc; không suy trạng thái chứng thư thành kết quả kiểm chứng tài liệu. Token Bearer giữ phía máy chủ; không đưa token/SAD vào frontend hoặc log công khai.

Yêu cầu · application/json

Cấu trúc yêu cầu
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`credentialID`	string	Bắt buộc	Identifier credential dùng cho operation.
`certificates`	string	Tùy chọn / theo điều kiện nguồn	Mức trả về chuỗi chứng thư. enum: none, single, chain; default: single
`certInfo`	boolean	Tùy chọn / theo điều kiện nguồn	Yêu cầu thông tin chứng thư.
`lang`	string	Tùy chọn / theo điều kiện nguồn	Ngôn ngữ theo bảng thông tin credential; enum chưa được nêu.
`authInfo`	boolean	Tùy chọn / theo điều kiện nguồn	Yêu cầu thông tin cơ chế cấp quyền.

Payload minh họa — Chưa chạy với dịch vụ

{
  "credentialID": "DEMO_SIC_CREDENTIAL",
  "certificates": "chain",
  "certInfo": true
}

Phản hồi · 200

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi 200
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả credential theo ngôn ngữ; tối đa 255 ký tự theo bảng.
`signatureQualifier`	string	Tùy chọn / theo điều kiện nguồn	Mã phân loại chữ ký theo nguồn.
`key`	object	Bắt buộc	Đối tượng theo bảng nguồn.
`key.status`	string	Bắt buộc	Trạng thái khóa ký. enum: Enabled, disabled
`key.algo`	string[]	Bắt buộc	Danh sách OID thuật toán khóa được hỗ trợ.
`key.len`	integer	Bắt buộc	Độ dài khóa tính bằng bit.
`key.curve`	string	Tùy chọn / theo điều kiện nguồn	OID đường cong; chỉ khi khóa ECDSA theo bảng.
`cert`	object	Tùy chọn / theo điều kiện nguồn	Đối tượng theo bảng nguồn.
`cert.status`	string	Tùy chọn / theo điều kiện nguồn	Trạng thái chứng thư tại thời điểm trả kết quả; không tự suy enum.
`cert.certificates`	string[]	Tùy chọn / theo điều kiện nguồn	Chuỗi chứng thư Base64; phụ thuộc certificates=none/single/chain.
`cert.issuerDN`	string	Tùy chọn / theo điều kiện nguồn	Issuer DN UTF-8 theo RFC 4514 khi yêu cầu thông tin chứng thư.
`cert.serialNumber`	string	Tùy chọn / theo điều kiện nguồn	Số sê-ri dạng hex khi certInfo=true.
`cert.subjectDN`	string	Tùy chọn / theo điều kiện nguồn	Subject DN UTF-8 theo RFC 4514 khi có thông tin chứng thư.
`cert.validFrom`	string	Tùy chọn / theo điều kiện nguồn	Ngày bắt đầu theo GeneralizedTime trong nguồn.
`cert.validTo`	string	Tùy chọn / theo điều kiện nguồn	Ngày kết thúc theo GeneralizedTime trong nguồn.
`auth`	object	Tùy chọn / theo điều kiện nguồn	Đối tượng theo bảng nguồn.
`auth.mode`	string	Tùy chọn / theo điều kiện nguồn	Cơ chế cấp quyền được trả về; không suy scope. enum: Explicit, oauth2code
`auth.expression`	string	Tùy chọn / theo điều kiện nguồn	Biểu thức kết hợp các đối tượng xác thực.
`auth.objects`	object	Tùy chọn / theo điều kiện nguồn	Đối tượng theo bảng nguồn.
`SCAL`	string	Tùy chọn / theo điều kiện nguồn	1: Nguồn mô tả không liên kết hash với SAD; 2: có liên kết. Đối chiếu cấu hình thực tế. enum: 1, 2
`multisign`	string	Bắt buộc	Bảng ghi String, ví dụ ghi số; kiểu dữ liệu cần xác nhận. Giá trị biểu diễn số chữ ký tối đa.
`lang`	string	Tùy chọn / theo điều kiện nguồn	Ngôn ngữ trong kết quả.

Phản hồi · Mặc định

HTTP status và trạng thái nghiệp vụ phải được đọc riêng.

Phản hồi mặc định
Trường	Kiểu dữ liệu	Điều kiện	Mô tả
`code`	string	Tùy chọn / theo điều kiện nguồn	Mã lỗi theo dịch vụ; không phải HTTP status.
`message`	string	Tùy chọn / theo điều kiện nguồn	Thông báo lỗi ngắn.
`description`	string	Tùy chọn / theo điều kiện nguồn	Mô tả chi tiết nếu có.

Điểm cần xác nhận

SIC-02
SIC-12

Hành động tiếp theo

Đối chiếu credential, chứng thư và cơ chế cấp quyền trước ký.

Danh mục chức năng trong nguồn

Chức năng theo Specification
Chức năng	Method / path	Trang PDF	Phạm vi trang
Đăng nhập	`POST /v2/auth/login`	7	Danh mục nguồn; schema chưa chuyển đầy đủ
Thu hồi phiên	`POST /v2/auth/revoke`	9	Danh mục nguồn; schema chưa chuyển đầy đủ
Danh sách nhà cung cấp	`POST /v2/credentials/providers`	10	Danh mục nguồn; schema chưa chuyển đầy đủ
Gói ký: PackageInfo	`POST /v2/credentials/providers`	10	Danh mục nguồn; schema chưa chuyển đầy đủ
Cấp phát	`POST /v2/credentials/issue`	15	Danh mục nguồn; schema chưa chuyển đầy đủ
Kiểm tra cấp phát	`POST /v2/credentials/issueCheck`	19	Danh mục nguồn; schema chưa chuyển đầy đủ
Danh sách	`POST /v2/credentials/list`	21	Danh mục nguồn; schema chưa chuyển đầy đủ
Thông tin	`POST /v2/credentials/info`	26	Đọc schema trong trang
Cấp quyền	`POST /v2/credentials/authorize`	30	Đọc schema trong trang
Kiểm tra cấp quyền	`POST /v2/credentials/authorizeCheck`	32	Đọc schema trong trang
Lịch sử credential	`POST /v2/credentials/history`	33	Danh mục nguồn; schema chưa chuyển đầy đủ
Ký mã băm	`POST /v2/signatures/signHash`	36	Đọc schema trong trang
Truy vấn trạng thái ký	`POST /v2/signatures/signPolling`	38	Đọc schema trong trang
Lịch sử ký	`POST /v2/signatures/history`	39	Danh mục nguồn; schema chưa chuyển đầy đủ
Quản lý chủ sở hữu	`POST /v2/owner/management`	42	Danh mục nguồn; schema chưa chuyển đầy đủ

Điểm cần chốt trước tích hợp

SIC-01 · SIC issue tr.15 / signHash tr.37

OperationMode S/A ở issue khác mô tả signHash.

Chưa cung cấp ví dụ phát hành có chế độ xử lý mặc định.

SIC-02 · SIC list tr.21, 24–26; operation

Nguồn dùng /v2 và /csc/v2.

Path hiển thị giữ theo bảng; namespace triển khai cần xác nhận.

SIC-03 · SIC providers tr.10 / package tr.12

Signing Package dùng path providers và packageInfo.

Xác nhận đây là một operation có lựa chọn dữ liệu.

SIC-04 · SIC signHash tr.37–38

SignAlgo bắt buộc trong bảng nhưng thiếu ở ví dụ.

Ví dụ biên tập có signAlgo; OID chỉ là giá trị minh họa từ nguồn.

SIC-05 · SIC issueCheck tr.19; views tr.6

Nguồn token issueCheck và các API cũ ở view cần làm rõ.

Không dựng hành trình view/issue runnable khi chưa chốt.

SIC-06 · SIC authorizeCheck tr.32 / callback tr.44–46

SAD được mở rộng thành hai thuật ngữ.

Dùng Signature Activation Data ở hướng dẫn cấp quyền; ghi nhận khác biệt nguồn.

SIC-07 · SIC authorize tr.30

View.expiresIn ghi Integer nhưng ví dụ đơn vị chưa rõ.

Không thêm default hoặc thời hạn vận hành.

SIC-08 · SIC signPolling tr.38–39

Bảng ghi responseID, ví dụ ghi requestID.

Request theo bảng chỉ để đọc; chưa bật thực thi.

SIC-09 · SIC authorizeCheck tr.32–33

Điều kiện token/SAD cùng xuất hiện và trạng thái xử lý chưa rõ.

Không suy mọi HTTP 200 đều đã cấp quyền.

SIC-10 · SIC signHash tr.37–38

Điều kiện signatures/responseID theo từng chế độ cần xác nhận.

Không tự tạo oneOf hoặc enum trạng thái production.

SIC-11 · SIC callback tr.44–54

Ví dụ callback có lỗi cú pháp/tên trường/trạng thái; phạm vi API cũ chưa rõ.

Chỉ mô tả trách nhiệm; payload runnable chờ đính chính.

SIC-12 · SIC info tr.29–30

Multisign có kiểu String trong bảng nhưng là số ở ví dụ.

Giữ kiểu bảng để đối chiếu, không gọi đây là schema đã xác nhận.