Tài liệu Open API tích hợp Chữ ký số MISA eSign

x-clientKey: {clientKey}

AuthorizationRM: {access token}

{

“error“: “thông tin lỗi“,

“errorCode“: “mã lỗi“,

“devMsg“: “mô tả thông tin lỗi cho người phát triển“,

“userMsg“: “mô tả thông tin lỗi cho người dùng“

}

Nhận về clientId và clientKey (dùng cho cả sandbox và product). Nếu đối tác chưa có CTS thì có thể đăng ký CTS test và nhận về

• Tài khoản eSgin
• Mật khẩu eSgin

Khi thực hiện golive, lấy các thông tin từ đơn vị

Tích hợp ký số chỉ sử dụng được với các CTS từ xa của MISA eSign (không hỗ trợ CTS dạng USB token)

(nếu ở site test,  giữ logo eSign khoảng 5s để đổi môi trường)

Lưu ý:

– Token có hạn được trả về qua thông tin data.expiresIn (dữ liệu trả về kiểu long)

    “userName“: “userName“,

    “password“: “password“

}

“status“: {

“type“: “type“,

“code“: 200,

“message“: “message“,

“error“: response_error,

“errorCode“: error_status_code,

“devMsg“: “dev_msg“,

“userMsg“: “user_msg“

},

“data“: {

“accessToken“: “access_token“,

“remoteSigningAccessToken“: “eSign_access_token“,

“tokenType“: “Bearer“,

“expiresIn“: 3600,

“refreshToken“: “refresh_token“,

“user“: {

“id“: “user_id“,

“email“: “user_email“,

“phoneNumber“: “user_phone_number“,

“firstName“: “user_first_name“,

“lastName“: “user_last_name“,

“username“: “user_username“

},

“default“: {

“email“: false,

“phoneNumber“: false,

“appAuthenticator“: true

},

“verifyUser“: {

            “emailsVerify“: false,

            “phoneNumberIsVerify“: true,

            “isChangePassword“: true

 },

}

}

Token_eSign = {tokenType} {eSign_access_token} (có khoảng trắng giữa 2 key). 

Ví dụ: Bearer eyJhbGciOiJSUzI1NiItpZCI6…

Token_eSign_refresh = refresh_token

RefreshToken = refresh_token

UserID = user_id

    “refreshToken“: “RefreshToken“,

}

RefreshToken được lấy ở bước 4.3. Đăng nhập tài khoản

“remoteSigningAccessToken“: “eSign_access_token“,

“accessToken“: “access_token“,

“refreshToken“: “refresh_token“,

“expiresIn“: 3600

}

clientKey: ClientKey

    “userName“: “userName“,

    “code“: “otp_code“, //mã otp

    “otpType“: 1, //1: nhận từ SDT/Email; 2: nhận từ ứng dụng

    “remember“: true/false, //ghi nhớ thiết bị

}

“status“: {

“type“: “response_type“,

“code“: 200,

“message“: “message“,

“error“: response_error,

“errorCode“: error_status_code,

“devMsg“: “dev_msg“,

“userMsg“: “user_msg“

},

“data“: {

“accessToken“: “access_token“,

“remoteSigningAccessToken“: “eSign_access_token“,

“tokenType“: “Bearer“,

“expiresIn“: 3600,

“refreshToken“: “refresh_token“,

“user“: {

“id“: “user_id“,

“email“: “user_email“,

“phoneNumber“: “user_phone_number“,

“firstName“: “user_first_name“,

“lastName“: “user_last_name“,

“username“: “user_username“

},

“default“: {

“email“: false,

“phoneNumber“: false,

“appAuthenticator“: true

}

}

}

    “userName“: “userName“,

    “language“: “language” //ngôn ngữ gửi thông báo: en-US

}

“status“: {

“type“: “response_type“,

“code“: 200,

“message“: “message“,

“error“: response_error,

“errorCode“: error_status_code

},

“data“: {

“user“: {

“username“: “user_username“

}

}

}

x-clientKey: ClientKey

AuthorizationRM: Token_eSign

“userId“: “user_id“,

“keyAlias“: “cert_id“,

“appName“: “app_name“,

“keyStatus“: “key_status“,

“certificate“: “cert_data“,

“certiticateChain“: [

                     “chain_data_1“,

                     “chain_data_2“,

                     “chain_data_3“,

}]

chain_data_1: là chứng thư ký

chain_data_2: là intermediate cert của MISA CA,

chain_data_3: là cert root do NEAC cấp.

x-clientKey: ClientKey

AuthorizationRM: Token_eSign

keyAlias lấy ở bước 4.7. Lấy danh sách chứng thư của người dùng

“userId“: “user_id“,

“keyAlias“: “cert_id“,

“appName“: “app_name“,

“keyStatus“: “key_status“,

“certificate“: “cert_data“,

“certiticateChain“: [

                     “chain_data_1“,

                     “chain_data_2“,

                     “chain_data_3“,

}

chain_data_1: là chứng thư ký

chain_data_2: là intermediate cert của MISA CA,

chain_data_3: là cert root do NEAC cấp.

x-clientKey: ClientKey

“certificate“: “{certificate}“,

“certificateChain“: “{certiticateChain}“,

“pdfDocs“: [PDF hash file],

“xmlDocs“: [XML hash file],

“wordDocs“: [Docs hash file],

“excelDocs“: [Excel hash file]

}

“pdfDocs“: [pdfDocs],

“xmlDocs“: [xmlDocs],

“wordDocs“: [wordDocs],

“excelDocs“: [excelDocs]

}

Xem tại Sheet: Tham số đầu ra của từng đối tượng

• Dùng trường digest trả ra bởi api để gọi lên api ký hash.
• Lưu lưu lại response để gọi lên api gắn chữ ký vào file khi có chữ ký

x-clientKey: ClientKey

AuthorizationRM: Token_eSign

“DataToBeDisplayed“: “Lời nhắn ký số“,

“UserId“: “UserID“, //thông tin lấy ở api access_token

“CertAlias“: “cert_id“,

“Documents“: [

                     “DocumentId“: “document_id“,

                     “FileToSign“: “digest”, //thông tin lấy ở bước Hash file

                     “DocumentName“: “document_name“,

}

   “transactionId“: “transaction_id” //id của lượt ký

}

• Để gọi được api ký hash này, người dùng cần phải được thiết lập kết nối tài khoản CKS từ xa MISA eSign trước. 
• Nếu người dùng chưa thực hiện kết nối, ứng dụng tích hợp cần phải có thông báo và hướng dẫn để người dùng thực hiện. Thiết lập tại đây

Lưu lại Response để thực hiện việc lấy trạng thái ký

transaction_id: id lượt ký ở bước Ký hash

x-clientKey: ClientKey

AuthorizationRM: Token_eSign

“status“: “status_sign“,

“errorCode“: “error_code“,

“errorDescription“: “error_description“,

“signatures“: [

                   {

                     “signature“: “signature_data“

                   }

                ]

}

• Danh sách dữ liệu chữ ký signature_data sẽ trả về theo đúng thứ tự mà danh sách file ký truyền lên tại API ký hash
• Chỉ trả về dữ liệu chữ ký khi tài liệu được ký thành công (status = SUCCESS)
• Ứng dụng tích hợp sẽ sử dụng dữ liệu chữ ký (signatures.signature) và gắn vào file để trả về cho người dùng cuối 

x-clientKey: ClientKey

AuthorizationRM: Token_eSign

“certificate“: “{certificate}”,

“certificateChain“: “{certiticateChain}”,

“pdfDocs“: [Attachment],

“xmlDocs“: [Attachment],

“wordDocs“: [Attachment],

“excelDocs“: [Attachment]

}

“pdfDocs“: [Attachmented],

“xmlDocs“: [Attachmented],

“wordDocs“: [Attachmented],

“excelDocs“: [Attachmented]

}

Xem tại Sheet: Tham số đầu ra (Attachmented)

• Request body là những gì api 4.10. Lấy hash của file trả về đi kèm với trường signature chính là chữ ký lấy được từ API 4.8. Lấy trạng thái ký tài liệu (signature_data). Hoặc có thể lấy từ kết quả của Webhook 4.9. Webhook nhận trạng thái ký số

    “messageId“: “message_id”,

    “clientId“: “client_id”,

    “extraData“: {},

    “status“: “status”,

    “errorCode“: “error_code”,

    “transactionId“: “transaction_id”,

    “signatures“: 

    [

         {

             “documentId“: “document_id”,

             “signature“: “signature”,

         }

    ]

}

    “errorCode“: “status_sign”,

    “devMsg“: “error_code”,

    “userMsg“: “error_description”

}

• Danh sách dữ liệu chữ ký signature sẽ trả về theo đúng thứ tự mà danh sách file ký truyền lên tại API ký hash.
• Chỉ trả về dữ liệu chữ ký signatures khi tất cả tài liệu được ký thành công.
• Ứng dụng tích hợp sẽ sử dụng dữ liệu chữ ký này và gắn vào file để trả về cho người dùng cuối

0: Chỉ hiện thị diễn giải

1: Hiển thị cả diễn giải và ảnh

2: Chỉ hiển thị ảnh

chain_data_1: là chứng thư ký

chain_data_2: là intermediate cert của MISA CA,

chain_data_3: là cert root do NEAC cấp.

– Trong trường hợp ký bó, ký lô. Trạng thái SUCCESS sẽ được trả về khi tất cả các file đã được ký thành công.