Hướng dẫn này sẽ chỉ cho bạn cách đăng ký một đơn đặt hàng chứng chỉ ký tài liệu với SSL.com's người ký điện tử dịch vụ và sử dụng API Cloud Signature Consortium (CSC) để ký kỹ thuật số băm tài liệu và tệp PDF. Bạn có thể sử dụng hướng dẫn này với cURL or Người phát thơ. Chúng tôi khuyên người dùng Postman nên cài đặt ứng dụng máy tính để bàn để làm việc thông qua các ví dụ. Các ví dụ trong hướng dẫn này đều có thể áp dụng cho môi trường eSigner và eSealing sản xuất và thử nghiệm của SSL.com. Sự khác biệt trong lệnh giữa chế độ sản xuất và thử nghiệm được giải thích trong các phần sau.
Để làm theo các hướng dẫn này, bạn sẽ cần:
- Một thứ tự chứng chỉ ký tài liệu đã được xác thực. Xin vui lòng đọc cách làm này để được hướng dẫn đầy đủ về cách đặt hàng và xác nhận.
- A ID khách hàng (còn được gọi là một ID ứng dụng. Vui lòng tham khảo trước cách làm này để biết hướng dẫn về cách tạo thông tin đăng nhập này).
Đặt hàng Chứng chỉ ký tài liệu SSL.com của bạn
Cách đặt hàng chứng chỉ trong môi trường sản xuất
Vui lòng tham khảo bài viết hướng dẫn này để được hướng dẫn cách đặt hàng chứng nhận ký tài liệu sản xuất: Quy trình đặt hàng chứng chỉ ký mã và tài liệu
Cách đặt Chứng chỉ Kiểm tra trên Sandbox của SSL.com
SSL.com cung cấp môi trường Sandbox chuyên dụng, phản ánh cổng SSL.com trực tiếp và API SWS của chúng tôi, để có không gian thử nghiệm không có rủi ro. Cài đặt “phòng thí nghiệm” này cho phép người dùng khám phá và thử nghiệm các dịch vụ của SSL.com mà không lo gây ra sự gián đoạn hoặc phát sinh chi phí thực tế.
Bài viết, Sử dụng Hộp cát SSL.com để Kiểm tra và Tích hợp, sẽ giúp bạn điều hướng quá trình thiết lập tài khoản Sandbox, bắt đầu đơn hàng thử nghiệm và tích hợp Sandbox với API SWS.
Sau khi bạn đã tạo chứng chỉ kiểm tra của mình, vui lòng liên hệ với nhóm hỗ trợ SSL.com để xác thực chứng chỉ đó. Bạn có thể thực hiện việc này bằng cách nhấp vào nút trò chuyện trực tuyến ở góc dưới bên phải của SSL.com trang web hoặc gửi email đến hỗ trợ@ssl.com.
Đăng ký eSigner và thiết lập xác thực hai yếu tố
Trước khi có thể bắt đầu sử dụng API CSC, bạn cần đăng ký dịch vụ ký điện toán đám mây eSigner của SSL.com. Các đơn đặt hàng đã được xác thực có thể được đăng ký vào eSigner theo hướng dẫn bên dưới:
- . Điều hướng đến Đơn Đặt Hàng trong tài khoản SSL.com của bạn và tìm đơn đặt hàng của bạn.
- Nhấp vào đơn đặt hàng chi tiết liên kết.
- Tạo và xác nhận mã PIN 4 chữ số, sau đó nhấp vào tạo mã PIN .
Nếu bạn cần đặt lại mã PIN eSigner của mình, vui lòng đọc cách làm này.
- Mã QR sẽ xuất hiện.
Lần sau khi bạn tải lại trang, mã QR sẽ không hiển thị. Nếu bạn cần xem hoặc đặt lại mã QR eSigner của mình, vui lòng đọc cách làm này.
- Quét mã vào ứng dụng xác thực 2 yếu tố trên thiết bị di động của bạn, chẳng hạn như Google Authenticator or Tự động. Ứng dụng sẽ cung cấp cho bạn mật khẩu dùng một lần (OTP) để sử dụng khi ký. Mỗi OTP có giá trị trong 30 giây.
Tùy chọn: Chuyển đổi chứng chỉ ký tài liệu OV của bạn thành chứng chỉ niêm phong
Lưu ý: Phần này chỉ dành cho người dùng muốn thực hiện eealing. Để tự động ký tài liệu và không bị nhắc nhở bởi Mật khẩu một lần (OTP), người dùng tự chuyển đổi chứng chỉ ký tài liệu Xác thực Tổ chức (OV) của họ thành chứng chỉ niêm phong trên tài khoản SSL.com của họ. Xin lưu ý rằng không thể chuyển đổi chứng chỉ ký tài liệu Xác thực Cá nhân (IV) để niêm phong. Hướng dẫn chuyển đổi eealing được trình bày chi tiết dưới đây:
- Nhấp chuột Đơn Đặt Hàng trên menu trên cùng của tài khoản SSL.com của bạn.
- Xác định vị trí chứng chỉ của bạn và nhấp vào tải về / chi tiết liên kết.
- Nhấn vào XÓA 2FA .
Cài đặt Postman và Nhập Bộ sưu tập API
Các hướng dẫn trong phần này chỉ dành cho người dùng Postman. Nếu bạn đang sử dụng cURL với CSC API, bạn có thể chuyển sang phần tiếp theo.
- Tải xuống và giải nén Bộ sưu tập CSC API Postman và Bộ sưu tập Người đưa thư API ký tài liệu (xem https://www.postman.com/sslcom cho các bộ sưu tập API SSL.com trực tuyến).
- Tải về và cài đặt Khách hàng Postman REST.
- Khởi chạy Postman, sau đó tạo tài khoản Postman mới hoặc đăng nhập vào một tài khoản hiện có.
- Nhấn vào Nhập khẩu .
- Nhấn vào Tải lên tập tin , điều hướng đến các tệp thu thập API đã giải nén (
csc-api-prod.postman_collection.jsonvàdocument-signing-api-prod.postman_collection.json), và mở chúng.
- Nhấn vào Nhập khẩu .
- Các yêu cầu API bạn sẽ làm việc hiện có sẵn trong Các hạng mục ở bên trái cửa sổ Người đưa thư.
Lấy mã thông báo truy cập
Bước tiếp theo là lấy mã thông báo truy cập từ SSL.com. Bạn sẽ cần ID khách hàng có sẵn, cũng như tên người dùng và mật khẩu cho tài khoản SSL.com của bạn. Mã thông báo truy cập có giá trị trong một giờ sau khi chúng được phát hành.
Sử dụng các tab có thể nhấp bên dưới để chọn hướng dẫn cho Người đưa thư hoặc cURL:
- Chọn một yêu cầu API từ bộ sưu tập API CSC.
- Chọn hình ba gạch cho phép Tab và chọn OAuth 2.0 từ Kiểu đơn.
- Nhập thông tin sau vào biểu mẫu:
- Tiền tố Header:
Bearer - Tên Mã thông báo:
SSLCOM CSC(hoặc bất kỳ tên dễ nhớ nào khác mà bạn thích) - Loại tài trợ:
Authorization Code - Gọi lại URL:
https://upload.esigner.com - Ủy quyền bằng trình duyệt: không được kiểm soát
- URL xác thực:
https://login.ssl.com/oauth2/authorizecho môi trường Sản xuất;https://oauth-sandbox.ssl.com/oauth2/authorizecho môi trường Sandbox. - URL mã thông báo truy cập:
https://login.ssl.com/oauth2/tokencho môi trường Sản xuất;https://oauth-sandbox.ssl.com/oauth2/tokencho môi trường Sandbox. - ID khách hàng: [ID khách hàng của bạn]
- Bí mật khách hàng: [Bí mật khách hàng của bạn]
- Phạm vi:
service - Nhà nước: [để trống]
- Xác thực Khách hàng:
Send as Basic Auth header
Khi bạn hoàn thành, hãy nhấp vào Nhận mã thông báo truy cập mới .
- Tiền tố Header:
- Một biểu mẫu đăng nhập sẽ xuất hiện. Nhập tên người dùng và mật khẩu SSL.com của bạn, sau đó nhấp vào Thành viên đăng nhập .
- Mã thông báo truy cập mới của bạn sẽ xuất hiện trong Postman. Chọn văn bản mã thông báo truy cập và sao chép nó vào khay nhớ tạm, sau đó đóng Quản lý mã thông báo truy cập hộp thoại. Dán mã thông báo truy cập của bạn vào trình soạn thảo văn bản để bạn có thể truy cập dễ dàng. Mỗi mã thông báo truy cập sẽ hết hạn sau một giờ.
Bạn cũng có thể lưu mã thông báo của mình để sử dụng lại trong các yêu cầu Người đưa thư, nhưng chúng tôi nhận thấy rằng cách sao chép và dán mã thông báo trực tiếp vào mỗi yêu cầu là đáng tin cậy nhất.
- Sử dụng lệnh sau để yêu cầu mã thông báo truy cập. Thay thế các giá trị được hiển thị trong CHỮ HOA bằng các giá trị thực của bạn:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "Của BẠN -CLIENT-ID", "client_secret" : "BÍ MẬT KHÁCH HÀNG CỦA BẠN", "grant_type" : "mật khẩu", "tên người dùng" : "TÊN NGƯỜI DÙNG CỦA BẠN", "mật khẩu" : "MẬT KHẨU CỦA BẠN" }' - Bạn sẽ nhận được một đối tượng JSON chứa mã thông báo truy cập và mã thông báo làm mới. Sao chép giá trị mã thông báo truy cập để dán vào các yêu cầu API của bạn. Bạn sẽ không cần mã làm mới cho những ví dụ này.
Ký một Hash
Bây giờ bạn đã có mã thông báo truy cập, bạn có thể bắt đầu thực hiện các yêu cầu API và tạo chữ ký. Phần này sẽ dẫn bạn qua năm yêu cầu có sẵn trong bộ sưu tập CSC của Postman, dẫn đến việc tạo chữ ký điện tử từ băm tài liệu.
- Cần có thư viện PDF để thao tác với tệp PDF cho đầu vào băm và sau đó nhúng PKCS#7 vào tài liệu PDF. (ví dụ: ApachePDFBox trong Java).
- Thư viện tiền điện tử để tạo PKCS#7 từ chữ ký thô nhận được từ API eSigner (ví dụ: BouncyCastle trong Java).
Nhận thông tin CSC (Tùy chọn)
- Bạn có thể sử dụng Thông tin CSC yêu cầu nhận thông tin về dịch vụ chữ ký đám mây của SSL.com. Lưu ý rằng, không giống như các yêu cầu khác trong bộ sưu tập, yêu cầu này không yêu cầu mã thông báo truy cập của bạn. Để gửi yêu cầu, hãy chọn Thông tin CSC từ API CSC bộ sưu tập, sau đó nhấp vào Gửi .
- Thông tin về dịch vụ chữ ký đám mây sẽ xuất hiện trong một đối tượng JSON trong Postman's Phản ứng trường.
- Sử dụng lệnh sau để nhận thông tin về dịch vụ API CSC của SSL.com. Nếu bạn ở trong môi trường hộp cát, hãy sử dụng
https://cs-try.ssl.com/csc/v0/infothay thế.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Bạn sẽ nhận được một đối tượng JSON với thông tin chi tiết về dịch vụ:
Danh sách thông tin đăng nhập CSC
Sản phẩm Danh sách thông tin đăng nhập CSC yêu cầu sẽ truy xuất thông tin xác thực bạn sẽ sử dụng trong các yêu cầu API sau này.
- Chọn Danh sách thông tin đăng nhập CSC Và nhấp vào cho phép tab.
- Chọn Mã thông báo mang từ Kiểu menu, dán mã thông báo truy cập của bạn vào Mã thông báo sau đó nhấp vào trường Gửi .
- Đối tượng JSON có danh sách ID thông tin xác thực được liên kết với người dùng sẽ xuất hiện trong Phản ứng cánh đồng. Danh sách của bạn có thể sẽ chứa một giá trị. Sao chép và dán ID thông tin xác thực của bạn vào trình soạn thảo văn bản để sử dụng cho các yêu cầu sau này.
- Nhập lệnh sau. (Thay thế MY-ACCESS-TOKEN bằng mã thông báo truy cập thực tế của bạn). Nếu bạn đang ở trong môi trường hộp cát, hãy sử dụng
https://cs-try.ssl.com/csc/v0/credentials/listthay thế:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Ủy quyền: Bearer MY- TRUY CẬP TOKEN "\ --data-raw" {} "Nếu sử dụng chứng chỉ eseal (chứng chỉ ký tài liệu chỉ có thông tin tổ chức; đi kèm với tài khoản esigner.com miễn phí của bạn), thì hãy bao gồm “clientData”: “DS_ESEAL” (lưu ý: eseals không yêu cầu xác thực OTP). Các tùy chọn khác cho “Dữ liệu khách hàng” là “EVCS” cho Ký mã EV và “DS” (mặc định) cho IV hoặc IV + OV Ký tài liệu:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Ủy quyền: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" clientData ":" DS_ESEAL "}' - Bạn sẽ nhận được một đối tượng JSON với một danh sách các ID thông tin xác thực được liên kết với người dùng. Danh sách của bạn có thể sẽ chứa một giá trị. Sao chép và dán ID thông tin xác thực của bạn vào trình soạn thảo văn bản để sử dụng cho các yêu cầu sau này.
Thông tin thông tin xác thực CSC (Tùy chọn)
Sản phẩm Thông tin thông tin xác thực CSC yêu cầu sẽ trả về chứng chỉ và thông tin khác được liên kết với ID thông tin xác thực và không bắt buộc phải ký.
- Để sử dụng yêu cầu này, hãy chọn Thông tin thông tin xác thực CSC từ bộ sưu tập và nhấp vào cho phép tab.
- Chọn Mã thông báo mang từ Kiểu trình đơn, sau đó dán mã thông báo truy cập của bạn vào Mã thông báo trường.
- Chọn hình ba gạch Cơ thể , sau đó dán ID thông tin xác thực của bạn làm giá trị cho
credentialID.
- Nhấn vào Gửi .
- Một đối tượng JSON với chuỗi chứng chỉ ký của bạn và thông tin khác sẽ xuất hiện trong Phản ứng trường.
- Nhập lệnh sau. Nếu bạn đang ở trong môi trường hộp cát, hãy sử dụng
https://cs-try.ssl.com/csc/v0/credentials/infoThay thếMY-ACCESS-TOKENvàMY-CREDENTIAL-IDvới thông tin thực tế của bạn:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "Ủy quyền: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID ":" MY-CREDENTIAL-ID "," certificate ":" chain "," certInfo ": true," authInfo ": true}' - Bạn sẽ nhận được một đối tượng JSON cùng với chuỗi chứng chỉ ký của mình và các thông tin khác:
Ủy quyền thông tin xác thực
Sản phẩm Ủy quyền thông tin xác thực yêu cầu sẽ truy xuất ủy quyền để ký một băm.
- Bắt đầu bằng cách chọn Ủy quyền thông tin xác thực từ bộ sưu tập và nhấp vào cho phép tab.
- Chọn Mã thông báo mang từ Kiểu trình đơn, sau đó dán mã thông báo truy cập của bạn vào Mã thông báo trường.
- Chọn hình ba gạch Cơ thể chuyển hướng. Dán ID thông tin đăng nhập của bạn làm
credentialIDgiá trị và một hàm băm của tài liệu bạn muốn ký làmhashgiá trị. Lấy và nhập OTP từ ứng dụng xác thực của bạn và nhập nó làm giá trị choOTP, Sau đó nhấp vào Gửi cái nút. Lưu ý: OTP không bắt buộc đối với chứng chỉ hàn gắn.
- Một đối tượng JSON với Dữ liệu Kích hoạt Chữ ký (SAD) của bạn sẽ xuất hiện trong Phản ứng cánh đồng. Sao chép và dán giá trị này vào trình soạn thảo văn bản để sử dụng trong yêu cầu ký hàm băm.
- Sử dụng lệnh sau. Thay thế
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDvàMY-HASHvới thông tin thực tế của bạn. Nhận mật khẩu một lần từ ứng dụng 2FA của bạn và việc sử dụng giống như giá trị củaMY-OTP. Lưu ý: OTP không bắt buộc đối với chứng chỉ hàn gắn.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application / json" \ --header "Ủy quyền: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID ":" MY-CREDENTIAL-ID "," numSignatures ": 1," hash ": [" MY-HASH "]," OTP ":" MY-OTP "} ' - Bạn sẽ nhận được một đối tượng JSON cùng với Dữ liệu kích hoạt chữ ký (SAD) của bạn. Sao chép và dán giá trị này vào trình soạn thảo văn bản để sử dụng trong yêu cầu ký hàm băm.
Dấu băm
Bây giờ bạn đã sẵn sàng để ký băm tài liệu.
- Chọn Dấu băm từ bộ sưu tập, sau đó chọn cho phép tab.
- Chọn Mã thông báo mang từ Kiểu trình đơn, sau đó dán mã thông báo truy cập của bạn vào Mã thông báo trường.
- Chọn hình ba gạch Cơ thể chuyển hướng. Dán ID thông tin đăng nhập của bạn làm
credentialIDgiá trị, Dữ liệu kích hoạt Chữ ký của bạn dưới dạngSADgiá trị và một hàm băm của tài liệu bạn muốn ký làmhashgiá trị, sau đó nhấp vào Gửi .
- Một đối tượng JSON có chữ ký của bạn sẽ xuất hiện trong Phản ứng trường.
- Nhập lệnh sau. Thay thế
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADvàMY-HASHvới thông tin thực tế của bạn:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application / json" \ --header "Ủy quyền: Bearer MY- ACCESS-TOKEN "\ --data-raw '{" credentialID ":" MY-CREDENTIAL-ID "," SAD ":" MY-SAD "," hash ": [" MY-HASH "]," signAlgo ": "1.2.840.113549.1.1.11"} ' - Bạn sẽ nhận được một đối tượng JSON chứa chữ ký của bạn.
Ký một bản PDF
Ngoài việc ký các băm tài liệu, bạn cũng có thể tải lên và ký một tệp PDF.
Khi ký một tệp PDF, bạn sẽ làm việc với hai yêu cầu ĐĂNG:
- Tải lên tài liệu PDF
- Ký tài liệu PDF
Bạn có thể sử dụng lại thông tin đăng nhập bạn đã lấy ở trên với Danh sách thông tin đăng nhập CSC yêu cầu. Bạn có thể cũng sẽ cần lấy một mã thông báo truy cập.
Tải lên tài liệu PDF
- Chọn hình ba gạch Tải lên tài liệu PDF yêu cầu và nhấp vào cho phép tab.
- Chọn Mã thông báo mang từ Kiểu trình đơn, sau đó dán mã thông báo truy cập của bạn vào Mã thông báo trường.
- Chọn hình ba gạch Headers và dán ID thông tin xác thực của bạn vào Giá trị cột.
- Chọn hình ba gạch Cơ thể tab và nhấp vào × bên cạnh
hello.pdfđể xóa tên tệp trình giữ chỗ này.
- Nhấn vào Chọn tập tin , sau đó điều hướng đến tệp bạn muốn tải lên.
- Nhấn vào Gửi .
- Chọn và sao chép
idgiá trị trong phản hồi để sử dụng trong yêu cầu tiếp theo.
- Sử dụng lệnh sau. Thay thế
MY-CREDENTIAL-ID,MY-ACCESS-TOKENvà/PATH/TO/FILE.pdfvới thông tin thực tế của bạn:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Authorization: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Bạn sẽ nhận được một đối tượng JSON có giá trị cho
id. Sao chép giá trị này để sử dụng trong lần yêu cầu tiếp theo.
Lưu ý: Để có chữ ký hiển thị, vui lòng tham khảo Tiêu đề yêu cầu HTTP sau (/ v1 / pdf / upload):
|
Chứng chỉ-Id |
ID thông tin xác thực duy nhất được chỉ định cho khóa - Bắt buộc |
|
Ký-Lý do |
Thêm lý do ký để thêm vào hình thức chữ ký và cả trong từ điển chữ ký - Tùy chọn, ví dụ: tôi phê duyệt tài liệu này |
|
Ký tên-Vị trí |
Thêm vị trí ký trong từ điển chữ ký - Tùy chọn, ví dụ: Houston, Texas |
|
Thông tin liên lạc |
Thêm thông tin liên hệ trong từ điển chữ ký - Tùy chọn, ví dụ: Số điện thoại |
|
Chữ ký-Trường-Vị trí |
Vị trí trường chữ ký nơi chữ ký trực quan hiển thị. Định dạng là "X, y, rộng, cao" - Không bắt buộc |
|
Số trang |
Số trang nơi vẽ chữ ký - Tùy chọn |
|
Chữ ký tay |
Hình ảnh PNG được mã hóa Base64 của chữ ký tay - Tùy chọn |
Ký tài liệu PDF
Bây giờ bạn có thể ký PDF.
- Chọn hình ba gạch Tải lên tài liệu PDF yêu cầu và nhấp vào cho phép tab.
- Chọn Mã thông báo mang từ Kiểu trình đơn, sau đó dán mã thông báo truy cập của bạn vào Mã thông báo trường.
- Chọn tab Nội dung, dán vào
idgiá trị từ bước trước và một OTP từ ứng dụng xác thực của bạn, sau đó nhấp vào Gửi .
- Dữ liệu PDF sẽ xuất hiện bên dưới trong Phản ứng cánh đồng. Chọn Lưu vào tệp từ Lưu phản hồi sau đó đặt tên cho tệp.
- Mở tệp trong Acrobat để xác nhận rằng tệp đã được ký.
- Nhập lệnh sau. Thay thế
MY-CREDENTIAL-ID,MY-FILE-IDvàOUTPUT-FILENAMEvới thông tin thực tế của bạn. Nhận mật khẩu một lần (OTP) từ ứng dụng 2FA của bạn và nhập mật khẩu đó làMY-OTP. Lưu ý: OTP không bắt buộc đối với chứng chỉ hàn gắn:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Ủy quyền: Bearer MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -output OUTPUT-FILENAME - cURL sẽ tải xuống tệp đã ký và lưu vào tên tệp bạn đã chỉ định:
- Mở tệp PDF trong Acrobat hoặc Acrobat Reader để kiểm tra xem chữ ký có hợp lệ không.
