Panduan ini akan menunjukkan cara mendaftarkan pesanan sertifikat penandatanganan dokumen dengan SSL.com penandatangan elektronik layanan dan menggunakan Cloud Signature Consortium (CSC) API untuk menandatangani hash dokumen dan file PDF secara digital. Anda dapat menggunakan panduan ini dengan baik keriting or Tukang pos. Kami menyarankan agar pengguna Postman menginstal aplikasi desktop untuk bekerja melalui contoh-contoh. Contoh dalam panduan ini berlaku untuk produksi SSL.com dan menguji lingkungan eSigner dan eSealing. Perbedaan perintah antara mode produksi dan pengujian dijelaskan di bagian berikut.
Untuk mengikuti instruksi ini, Anda perlu:
- Perintah sertifikat penandatanganan dokumen yang divalidasi. Mohon dibaca ini bagaimana caranya untuk instruksi lengkap tentang pemesanan dan validasi.
- A ID pelanggan (juga dikenal sebagai ID Aplikasi. Silakan merujuk ke ini bagaimana caranya untuk petunjuk tentang membuat kredensial ini).
Pesan Sertifikat Penandatanganan Dokumen SSL.com Anda
Cara Memesan Sertifikat di Lingkungan Produksi
Silakan merujuk ke artikel panduan ini untuk petunjuk tentang cara memesan sertifikat penandatanganan dokumen produksi: Proses Pemesanan Sertifikat Penandatanganan Kode dan Dokumen
Cara Memesan Sertifikat Tes di Kotak Pasir SSL.com
SSL.com menawarkan lingkungan Sandbox khusus, yang mencerminkan portal SSL.com langsung dan API SWS kami, untuk ruang eksperimen bebas risiko. Pengaturan “laboratorium” ini memungkinkan pengguna menjelajahi dan menguji layanan SSL.com tanpa khawatir menyebabkan gangguan atau menimbulkan biaya sebenarnya.
Artikel, Menggunakan Kotak Pasir SSL.com untuk Pengujian dan Integrasi, akan membantu Anda menavigasi proses pembuatan akun Sandbox, memulai perintah pengujian, dan mengintegrasikan Sandbox dengan API SWS.
Setelah Anda membuat sertifikat pengujian, harap hubungi tim dukungan SSL.com untuk memvalidasinya. Anda dapat melakukannya dengan mengeklik tombol obrolan online di pojok kanan bawah SSL.com situs web atau mengirim email ke dukungan@ssl.com.
Daftar di eSigner dan Siapkan Autentikasi Dua Faktor
Sebelum Anda dapat mulai menggunakan CSC API, Anda harus mendaftar di layanan penandatanganan cloud eSigner SSL.com. Pesanan yang divalidasi dapat didaftarkan di eSigner dengan mengikuti petunjuk di bawah ini:
- . Arahkan ke Pesanan tab di akun SSL.com Anda dan temukan pesanan Anda.
- Klik pesanannya rincian link.
- Buat dan konfirmasikan PIN 4 digit, lalu klik buat PIN .
Jika Anda perlu menyetel ulang PIN eSigner Anda, harap baca ini bagaimana caranya. - Kode QR akan muncul.
Lain kali Anda memuat ulang halaman, kode QR tidak akan terlihat. Jika Anda perlu melihat atau mengatur ulang kode QR eSigner Anda, silakan baca ini bagaimana caranya. - Pindai kode tersebut ke dalam aplikasi otentikasi 2 faktor pada perangkat seluler Anda, seperti Google Authenticator or Authy. Aplikasi ini akan memberi Anda kata sandi satu kali (OTP) untuk digunakan saat menandatangani. Setiap OTP berlaku selama 30 detik.
Opsional: Konversikan sertifikat penandatanganan dokumen OV Anda menjadi sertifikat penyegelan
Catatan: Bagian ini hanya diperuntukkan bagi pengguna yang ingin melakukan esealing. Untuk mengotomatiskan penandatanganan dokumen dan tidak diminta oleh One Time Passwords (OTP), pengguna mengonversi sendiri sertifikat penandatanganan dokumen Validasi Organisasi (OV) mereka menjadi sertifikat penyegelan di akun SSL.com mereka. Perhatikan bahwa sertifikat penandatanganan dokumen Validasi Individu (IV) tidak dapat dikonversi untuk disegel. Petunjuk untuk konversi esealing dirinci di bawah ini:
- Klik Pesanan di menu atas akun SSL.com Anda.
- Temukan sertifikat Anda dan klik unduh / detail link.
- klik HAPUS 2FA .
Instal Koleksi Postman dan Impor API
Petunjuk di bagian ini hanya untuk pengguna Postman. Jika Anda menggunakan cURL dengan CSC API, Anda dapat melanjutkan ke bagian berikutnya.
- Unduh dan unzip file Koleksi CSC API Postman dan Koleksi Document Signing API Postman (Lihat https://www.postman.com/sslcom untuk koleksi API SSL.com online).
- Men-download dan menginstal Klien REST Postman.
- Luncurkan Postman, lalu buat akun Postman baru atau masuk ke akun yang sudah ada.
- klik impor .
- klik Unggah berkas tombol, arahkan ke file koleksi API yang telah dibuka zipnya (
csc-api-prod.postman_collection.json
dandocument-signing-api-prod.postman_collection.json
), dan membukanya.
- klik impor .
- Permintaan API yang akan Anda tangani sekarang tersedia di koleksi tab di sisi kiri jendela Postman.
Ambil Token Akses
Langkah selanjutnya adalah mengambil token akses dari SSL.com. Anda akan membutuhkan Anda ID pelanggan tersedia, serta nama pengguna dan kata sandi untuk akun SSL.com Anda. Token akses berlaku selama satu jam setelah diterbitkan.
Gunakan tab yang dapat diklik di bawah ini untuk memilih instruksi untuk Postman atau cURL:
- Pilih permintaan API dari koleksi CSC API.
- Pilih Otorisasi Tab dan pilih OAuth 2.0 dari Tipe menu.
- Masukkan informasi berikut ke dalam formulir:
- Awalan Header:
Bearer
- Nama Token:
SSLCOM CSC
(atau nama lain yang mudah diingat yang Anda sukai) - Jenis Hibah:
Authorization Code
- URL Panggilan Balik:
https://upload.esigner.com
- Otorisasi menggunakan browser: dicentang
- URL Otorisasi:
https://login.ssl.com/oauth2/authorize
untuk lingkungan Produksi;https://oauth-sandbox.ssl.com/oauth2/authorize
untuk lingkungan Sandbox. - Akses URL Token:
https://login.ssl.com/oauth2/token
untuk lingkungan Produksi;https://oauth-sandbox.ssl.com/oauth2/token
untuk lingkungan Sandbox. - ID Klien: [ID Klien Anda]
- Rahasia Klien: [Rahasia Klien Anda]
- Cakupan:
service
- Negara: [biarkan kosong]
- Otentikasi Klien:
Send as Basic Auth header
- Awalan Header:
- Formulir login akan muncul. Masukkan nama pengguna dan kata sandi SSL.com Anda, lalu klik Login anggota .
- Token akses baru Anda akan muncul di Postman. Pilih teks token akses dan salin ke clipboard, lalu tutup Kelola Token Akses kotak dialog. Tempel token akses Anda ke editor teks di mana Anda dapat mengaksesnya dengan mudah. Setiap token akses akan kedaluwarsa setelah satu jam.
Anda juga dapat menyimpan token Anda untuk digunakan kembali dalam permintaan Postman, tetapi kami menemukan bahwa paling dapat diandalkan untuk menyalin dan menempelkan token langsung ke setiap permintaan.
- Gunakan perintah berikut untuk meminta token akses. Ganti nilai yang ditampilkan di ALL-CAPS dengan nilai Anda yang sebenarnya:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "YOUR -CLIENT-ID", "client_secret" : "YOUR-CLIENT-SECRET", "grant_type" : "password", "username" : "YOUR-USERNAME", "password" : "YOUR-PASSSWORD" }'
- Anda harus menerima objek JSON yang berisi token akses dan token penyegaran. Salin nilai token akses untuk ditempelkan ke permintaan API Anda. Anda tidak memerlukan token penyegaran untuk contoh ini.
Tandatangani Hash
Sekarang setelah Anda memiliki token akses, Anda dapat mulai membuat permintaan API dan membuat tanda tangan. Bagian ini akan memandu Anda melalui lima permintaan yang tersedia di koleksi Postman CSC, yang menghasilkan pembuatan tanda tangan digital dari hash dokumen.
- Pustaka PDF diperlukan untuk memanipulasi PDF untuk input hash dan kemudian menyematkan PKCS#7 dalam dokumen PDF. (mis. ApachePDFBox di Java).
- Pustaka Kripto untuk membuat PKCS#7 dari tanda tangan mentah yang diterima dari eSigner API (mis. BouncyCastle di Java).
Dapatkan Info CSC (Opsional)
- Anda dapat menggunakan Info CSC meminta untuk mendapatkan informasi tentang layanan tanda tangan cloud SSL.com. Perhatikan bahwa, tidak seperti yang lain dalam koleksi, permintaan ini tidak memerlukan token akses Anda. Untuk mengirim permintaan, pilih Info CSC dari API CSC koleksi, lalu klik Kirim .
- Informasi tentang layanan tanda tangan cloud akan muncul di objek JSON di Postman Tanggapan lapangan.
- Gunakan perintah berikut untuk mendapatkan info tentang layanan CSC API SSL.com. Jika Anda berada di lingkungan kotak pasir, gunakan
https://cs-try.ssl.com/csc/v0/info
sebagai gantinya.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Jenis Konten: application / json" \ --data-raw "{}"
- Anda akan menerima objek JSON dengan detail tentang layanan:
Daftar Kredensial CSC
Daftar Kredensial CSC request akan mengambil kredensial yang akan Anda gunakan di permintaan API nanti.
- Pilih Daftar Kredensial CSC Dan klik Otorisasi Tab.
- Pilih Token Pembawa dari Tipe menu, tempel token akses Anda ke Token bidang, lalu klik Kirim .
- Objek JSON dengan daftar ID kredensial yang terkait dengan pengguna akan muncul di Tanggapan bidang. Daftar Anda mungkin berisi satu nilai. Salin dan tempel ID kredensial Anda ke editor teks untuk digunakan dalam permintaan nanti.
- Masukkan perintah berikut. (Ganti MY-ACCESS-TOKEN dengan token akses Anda yang sebenarnya). Jika Anda berada di lingkungan kotak pasir, gunakan
https://cs-try.ssl.com/csc/v0/credentials/list
sebagai gantinya:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Jenis Konten: application / json" \ --header "Otorisasi: Bearer MY- AKSES-TOKEN "\ --data-raw" {} "
Jika menggunakan sertifikat eseal (sertifikat penandatanganan dokumen dengan hanya informasi organisasi; disertakan dengan akun esigner.com gratis Anda), maka sertakan "clientData": "DS_ESEAL" (catatan: eseals tidak memerlukan otentikasi OTP). Pilihan lain untuk “clientData” adalah “EVCS” untuk EV Code Signing dan “DS” (default) untuk IV atau IV+OV Document Signing :
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}'
- Anda harus menerima objek JSON dengan daftar ID kredensial yang terkait dengan pengguna. Daftar Anda mungkin berisi satu nilai. Salin dan tempel ID kredensial Anda ke editor teks untuk digunakan dalam permintaan nanti.
Info Kredensial CSC (Opsional)
Info Kredensial CSC request akan mengembalikan sertifikat dan informasi lain yang terkait dengan ID kredensial, dan tidak diperlukan untuk penandatanganan.
- Untuk menggunakan permintaan ini, pilih Info Kredensial CSC dari koleksi dan klik Otorisasi Tab.
- Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
- Pilih Tubuh tab, lalu tempel ID kredensial Anda sebagai nilainya
credentialID
.
- klik Kirim .
- Objek JSON dengan rantai sertifikat penandatanganan Anda dan informasi lainnya akan muncul di Tanggapan lapangan.
- Masukkan perintah berikut. Jika Anda berada di lingkungan kotak pasir, gunakan
https://cs-try.ssl.com/csc/v0/credentials/info
menggantikanMY-ACCESS-TOKEN
danMY-CREDENTIAL-ID
dengan informasi Anda yang sebenarnya:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }'
- Anda harus menerima objek JSON dengan rantai sertifikat penandatanganan Anda dan informasi lainnya:
Otorisasi Kredensial
Otorisasi Kredensial permintaan akan mengambil otorisasi untuk menandatangani hash.
- Mulailah dengan memilih Otorisasi Kredensial dari koleksi dan mengklik Otorisasi Tab.
- Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
- Pilih Tubuh tab. Tempel ID kredensial Anda sebagai
credentialID
nilai dan hash dokumen yang ingin Anda tanda tangani sebagaihash
nilai. Ambil dan masukkan OTP dari aplikasi otentikasi Anda dan masukkan sebagai nilainyaOTP
, Lalu klik Kirim tombol. Catatan: OTP tidak diperlukan untuk mendapatkan sertifikat.
- Objek JSON dengan Signature Activation Data (SAD) Anda akan muncul di Tanggapan bidang. Salin dan tempel nilai ini ke editor teks untuk digunakan dalam permintaan penandatanganan hash.
- Gunakan perintah berikut. Menggantikan
MY-ACCESS-TOKEN
,MY-CREDENTIAL-ID
, danMY-HASH
dengan informasi Anda yang sebenarnya. Dapatkan kata sandi satu kali dari aplikasi 2FA Anda dan gunakan sebagai nilainyaMY-OTP
. Catatan: OTP tidak diperlukan untuk mendapatkan sertifikat.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }'
- Anda harus menerima objek JSON dengan Data Aktivasi Tanda Tangan (SAD) Anda. Salin dan tempel nilai ini ke editor teks untuk digunakan dalam permintaan penandatanganan hash.
Masuk Hash
Sekarang Anda siap untuk menandatangani hash dokumen.
- Pilih Masuk Hash dari koleksi, lalu pilih Otorisasi Tab.
- Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
- Pilih Tubuh tab. Tempel ID kredensial Anda sebagai
credentialID
nilai, Data Aktivasi Tanda Tangan Anda sebagaiSAD
nilai, dan hash dokumen yang ingin Anda tanda tangani sebagaihash
nilai, lalu klik Kirim .
- Objek JSON dengan tanda tangan Anda akan muncul di Tanggapan lapangan.
- Masukkan perintah berikut. Menggantikan
MY-ACCESS-TOKEN
,MY-CREDENTIAL-ID
,MY-SAD
, danMY-HASH
dengan informasi Anda yang sebenarnya:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }'
- Anda harus menerima objek JSON yang berisi tanda tangan Anda.
Tandatangani PDF
Selain menandatangani hash dokumen, Anda juga dapat mengunggah dan menandatangani file PDF.
Saat menandatangani PDF Anda akan bekerja dengan dua permintaan POST:
- Unggah Dokumen PDF
- Tanda tangani Dokumen PDF
Anda dapat menggunakan kembali kredensial yang Anda ambil di atas dengan Daftar Kredensial CSC permintaan. Anda mungkin juga perlu mengambil file token akses.
Unggah Dokumen PDF
- Pilih Unggah Dokumen PDF meminta dan klik Otorisasi Tab.
- Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
- Pilih Header tab dan tempel ID kredensial Anda di Nilai kolom.
- Pilih Tubuh Tab dan klik × sebelah
hello.pdf
untuk menghapus nama file placeholder ini.
- klik Pilih file tombol, lalu navigasikan ke file yang ingin Anda unggah.
- klik Kirim .
- Pilih dan salin file
id
nilai dalam respons untuk digunakan dalam permintaan berikutnya.
- Gunakan perintah berikut. Menggantikan
MY-CREDENTIAL-ID
,MY-ACCESS-TOKEN
, dan/PATH/TO/FILE.pdf
dengan informasi Anda yang sebenarnya:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Otorisasi: Bearer MY- AKSES-TOKEN "\ --header" Jenis Konten: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Anda akan menerima objek JSON dengan nilai untuk
id
. Salin nilai ini untuk digunakan di permintaan berikutnya.
Catatan: Untuk tanda tangan yang terlihat, silakan lihat Header Permintaan HTTP berikut (/v1/pdf/upload):
Judul Permintaan |
Deskripsi Produk |
---|---|
Kredensial-Id |
ID Kredensial Unik yang ditetapkan ke kunci – Wajib |
Penandatanganan-Alasan |
Tambahkan alasan penandatanganan untuk menambahkan tampilan tanda tangan dan juga dalam kamus tanda tangan – Opsional misalnya saya menyetujui dokumen ini |
Penandatanganan-Lokasi |
Tambahkan lokasi penandatanganan di kamus tanda tangan – Opsional misalnya Houston, Texas |
Info kontak |
Tambahkan informasi kontak dalam kamus tanda tangan – Opsional misalnya Nomor telepon |
Signature-Field-Posisi |
Posisi bidang tanda tangan tempat tanda tangan visual ditampilkan. Formatnya adalah "x,y,lebar,tinggi" - Opsional |
Nomor halaman |
Nomor halaman tempat menggambar tanda tangan – Opsional |
Tanda Tangan |
Gambar PNG yang disandikan Base64 dari tanda tangan – Opsional |
Tanda tangani Dokumen PDF
Sekarang Anda dapat menandatangani PDF.
- Pilih Unggah Dokumen PDF meminta dan klik Otorisasi Tab.
- Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
- Pilih tab Body, tempel di
id
nilai dari langkah sebelumnya dan OTP dari aplikasi otentikasi Anda, lalu klik Kirim .
- Data PDF akan muncul di bawah ini di Tanggapan bidang. Memilih Simpan ke File dari Simpan Tanggapan menu, lalu beri nama file.
- Buka file di Acrobat untuk mengonfirmasi bahwa file telah ditandatangani.
- Masukkan perintah berikut. Menggantikan
MY-CREDENTIAL-ID
,MY-FILE-ID
, danOUTPUT-FILENAME
dengan informasi Anda yang sebenarnya. Dapatkan kata sandi satu kali (OTP) dari aplikasi 2FA Anda dan masukkan sebagaiMY-OTP
. Catatan: OTP tidak diperlukan untuk mendapatkan sertifikat:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Otorisasi: Bearer MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -output OUTPUT-FILENAME
- cURL akan mengunduh file yang ditandatangani dan menyimpannya ke nama file yang Anda tentukan:
- Buka PDF di Acrobat atau Acrobat Reader untuk memeriksa apakah tanda tangan tersebut valid.