SSL.com

Penandatanganan Dokumen Jarak Jauh dengan eSigner CSC API

Tim Dukungan SSL.com

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:

Pesan Sertifikat Penandatanganan Dokumen SSL.com Anda

Anda dapat melewati bagian ini jika Anda sudah memiliki sertifikat penandatanganan dokumen yang dikeluarkan. Jika demikian, lanjutkan ke bagian selanjutnya yang membahas cara mendaftarkan sertifikat Anda di eSigner.

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 support@ssl.com.

Pergi ke atas

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: 

  1. . Arahkan ke Pesanan tab di akun SSL.com Anda dan temukan pesanan Anda.
    Temukan pesanan
  2. Klik pesanannya rincian link.
  3. Buat dan konfirmasikan PIN 4 digit, lalu klik buat PIN .
    Jika Anda perlu menyetel ulang PIN eSigner Anda, harap baca ini bagaimana caranya.
  4. 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.
  5. 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.
olymp trade indonesiaTip: Anda dapat menggunakan eSigner untuk berbagi sertifikat penandatanganan yang divalidasi organisasi (OV) di antara rekan satu tim. Mohon dibaca Berbagi Tim untuk Dokumen eSigner dan Sertifikat Penandatanganan Kode EV untuk instruksi.
Pergi ke atas

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:

  1. Klik Pesanan di menu atas akun SSL.com Anda. 
  2. Temukan sertifikat Anda dan klik unduh / detail link.
  3. klik HAPUS 2FA .
Pergi ke atas

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.

  1. 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).
  2. Men-download dan menginstal Klien REST Postman.
  3. Luncurkan Postman, lalu buat akun Postman baru atau masuk ke akun yang sudah ada.
  4. klik impor .
  5. klik Unggah berkas tombol, arahkan ke file koleksi API yang telah dibuka zipnya (csc-api-prod.postman_collection.json dan document-signing-api-prod.postman_collection.json), dan membukanya.
  6. klik impor .
  7. Permintaan API yang akan Anda tangani sekarang tersedia di koleksi tab di sisi kiri jendela Postman.
Pergi ke atas

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:

Instruksi Tukang PoscURL Instruksi
  1. Pilih permintaan API dari koleksi CSC API.
  2. Pilih Otorisasi Tab dan pilih OAuth 2.0 dari Tipe menu.
  3. 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

    Setelah Anda selesai, klik Dapatkan Token Akses Baru .

  4. Formulir login akan muncul. Masukkan nama pengguna dan kata sandi SSL.com Anda, lalu klik Login anggota .
  5. 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.
  1. 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" }'
  2. 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.
Pergi ke atas

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.

Algoritma SHA 256 harus digunakan untuk menghitung hash dokumen PDF. 
  1. Pustaka PDF diperlukan untuk memanipulasi PDF untuk input hash dan kemudian menyematkan PKCS#7 dalam dokumen PDF. (mis. ApachePDFBox di Java). 
  2. Pustaka Kripto untuk membuat PKCS#7 dari tanda tangan mentah yang diterima dari eSigner API (mis. BouncyCastle di Java).

Dapatkan Info CSC (Opsional)

Instruksi Tukang PoscURL Instruksi
  1. 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 .
  2. Informasi tentang layanan tanda tangan cloud akan muncul di objek JSON di Postman Tanggapan lapangan.
  1. 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 "{}"
  2. Anda akan menerima objek JSON dengan detail tentang layanan:

Daftar Kredensial CSC

Grafik Daftar Kredensial CSC request akan mengambil kredensial yang akan Anda gunakan di permintaan API nanti.

Instruksi Tukang PoscURL Instruksi
  1. Pilih Daftar Kredensial CSC Dan klik Otorisasi Tab.
  2. Pilih Token Pembawa dari Tipe menu, tempel token akses Anda ke Token bidang, lalu klik Kirim .
  3. 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.
  1. 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"}'
  2. 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)

Grafik Info Kredensial CSC request akan mengembalikan sertifikat dan informasi lain yang terkait dengan ID kredensial, dan tidak diperlukan untuk penandatanganan.

Instruksi Tukang PoscURL Instruksi
  1. Untuk menggunakan permintaan ini, pilih Info Kredensial CSC dari koleksi dan klik Otorisasi Tab.
  2. Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
  3. Pilih Tubuh tab, lalu tempel ID kredensial Anda sebagai nilainya credentialID.
  4. klik Kirim .
  5. Objek JSON dengan rantai sertifikat penandatanganan Anda dan informasi lainnya akan muncul di Tanggapan lapangan.
  1. Masukkan perintah berikut. Jika Anda berada di lingkungan kotak pasir, gunakan https://cs-try.ssl.com/csc/v0/credentials/info  menggantikan MY-ACCESS-TOKEN dan MY-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 }'
  2. Anda harus menerima objek JSON dengan rantai sertifikat penandatanganan Anda dan informasi lainnya:

Otorisasi Kredensial

Grafik Otorisasi Kredensial permintaan akan mengambil otorisasi untuk menandatangani hash.

Instruksi Tukang PoscURL Instruksi
  1. Mulailah dengan memilih Otorisasi Kredensial dari koleksi dan mengklik Otorisasi Tab.
  2. Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
  3. Pilih Tubuh tab. Tempel ID kredensial Anda sebagai credentialID nilai dan hash dokumen yang ingin Anda tanda tangani sebagai hash nilai. Ambil dan masukkan OTP dari aplikasi otentikasi Anda dan masukkan sebagai nilainya OTP, Lalu klik Kirim tombol. Catatan: OTP tidak diperlukan untuk mendapatkan sertifikat.
  4. 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.
  1. Gunakan perintah berikut. Menggantikan MY-ACCESS-TOKEN, MY-CREDENTIAL-ID, dan MY-HASH dengan informasi Anda yang sebenarnya. Dapatkan kata sandi satu kali dari aplikasi 2FA Anda dan gunakan sebagai nilainya MY-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 " }'
  2. 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.

Instruksi Tukang PoscURL Instruksi
  1. Pilih Masuk Hash dari koleksi, lalu pilih Otorisasi Tab.
  2. Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
  3. Pilih Tubuh tab. Tempel ID kredensial Anda sebagai credentialID nilai, Data Aktivasi Tanda Tangan Anda sebagai SAD nilai, dan hash dokumen yang ingin Anda tanda tangani sebagai hash nilai, lalu klik Kirim .
  4. Objek JSON dengan tanda tangan Anda akan muncul di Tanggapan lapangan.
  1. Masukkan perintah berikut. Menggantikan MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SAD, dan MY-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" }'
  2. Anda harus menerima objek JSON yang berisi tanda tangan Anda.
Pergi ke atas

Tandatangani PDF

Selain menandatangani hash dokumen, Anda juga dapat mengunggah dan menandatangani file PDF.

Saat menandatangani PDF Anda akan bekerja dengan dua permintaan POST:

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

Instruksi Tukang PoscURL Instruksi
  1. Pilih Unggah Dokumen PDF meminta dan klik Otorisasi Tab.
  2. Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
  3. Pilih Header tab dan tempel ID kredensial Anda di Nilai kolom.
  4. Pilih Tubuh Tab dan klik × sebelah hello.pdf untuk menghapus nama file placeholder ini.
  5. klik Pilih file tombol, lalu navigasikan ke file yang ingin Anda unggah.
  6. klik Kirim .
  7. Pilih dan salin file id nilai dalam respons untuk digunakan dalam permintaan berikutnya.
  1. 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 "
  2. 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.

Otorisasi OTP tidak diperlukan saat menandatangani menggunakan sertifikat penandatanganan dokumen esealing. Abaikan semua parameter OTP dalam panduan berikut jika menggunakan sertifikat penandatanganan dokumen tambahan.
Instruksi Tukang PoscURL Instruksi
  1. Pilih Unggah Dokumen PDF meminta dan klik Otorisasi Tab.
      
  2. Pilih Token Pembawa dari Tipe menu, lalu tempel token akses Anda ke Token lapangan.
  3. Pilih tab Body, tempel di id nilai dari langkah sebelumnya dan OTP dari aplikasi otentikasi Anda, lalu klik Kirim .
  4. Data PDF akan muncul di bawah ini di Tanggapan bidang. Memilih Simpan ke File dari Simpan Tanggapan menu, lalu beri nama file.
  5. Buka file di Acrobat untuk mengonfirmasi bahwa file telah ditandatangani.
  1. Masukkan perintah berikut. Menggantikan MY-CREDENTIAL-ID, MY-FILE-ID, dan OUTPUT-FILENAME dengan informasi Anda yang sebenarnya. Dapatkan kata sandi satu kali (OTP) dari aplikasi 2FA Anda dan masukkan sebagai MY-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
  2. cURL akan mengunduh file yang ditandatangani dan menyimpannya ke nama file yang Anda tentukan:
  3. Buka PDF di Acrobat atau Acrobat Reader untuk memeriksa apakah tanda tangan tersebut valid.

Keluar dari versi seluler