Juknis Web API Esign [PDF]

Citation preview

PETUNJUK TEKNIS



WEB API ESIGN



Balai Sertifikasi Elektronik



DAFTAR ISI 1.



PENDAHULUAN ................................................................................................. 3



2.



API Service ......................................................................................................... 3 2.1.



Authentication .............................................................................................................. 3



2.2.



User................................................................................................................................. 4



2.2.1.



Cek Status ......................................................................................................................... 4



2.2.2.



Registrasi........................................................................................................................... 5



2.3.



2.3.1.



Kirim Permohonan Tanda Tangan ................................................................................ 6



2.3.2.



Tanda Tangan Dokumen ................................................................................................. 7



2.3.3.



Download Dokumen ........................................................................................................ 8



2.4.



3.



Proses Tanda Tangan ................................................................................................. 6



Verifikasi PDF ............................................................................................................... 8



INITIAL VECTOR DENGAN POSTMAN........................................................... 10 3.1.



Proses Autentikasi..................................................................................................... 10



3.1.1.



Get Access Token .......................................................................................................... 10



3.1.2.



Set Access Token .......................................................................................................... 11



3.2.



Proses Registrasi ....................................................................................................... 13



3.2.1.



API Registrasi ................................................................................................................. 13



3.2.2.



Set Passphrase............................................................................................................... 15



3.3.



Proses Tanda Tangan ............................................................................................... 17



3.3.1.



Kirim Permohonan Tanda Tangan .............................................................................. 17



3.3.2.



Tandatangani Dokumen ................................................................................................ 18



3.3.3.



Download Dokumen ...................................................................................................... 19



3.4.



Proses Verifikasi ........................................................................................................ 21



1.



PENDAHULUAN eSign merupakan aplikasi berbasis web service milik Balai Sertifikasi Elektronik (BSrE), Badan Siber dan Sandi Negara (BSSN) yang digunakan untuk penerapan tanda tangan elektronik. Aplikasi ini dibangun untuk memenuhi kebutuhan pengguna khususnya dalam hal fleksibilitas penerapan tanda tangan elektronik dengan tetap mengedepankan faktor keamanan. Adapun gambaran umum sistem eSign adalah sebagai berikut :



AMS



TSA



CVS



e-Sign



Signer Module



Aplikasi SI



Web Service Interface



HSM



Lemsaneg Crypto Library Database Framework



Database



Aplikasi Mobile



2.



API Service API eSign menggunakan teknologi REST dengan komunikasi HTTP dan format data JSON untuk menyediakan service yang bisa diakses oleh aplikasi lain. Pada setiap penggunaan service, aplikasi client harus menyertakan access token pada header setiap request service. Token ini didapatkan dari service otentikasi menggunakan protokol OAuth 2.0.



2.1. Authentication API Authentication berfungsi untuk menjalankan otentikasi antara aplikasi client dan eSign. Hasil yang didapatkan dari API ini adalah access token yang akan digunakan oleh aplikasi client untuk mengakses API lainnya pada eSign.



Deskripsi Struktur URL Method Parameter



Response



Digunakan untuk mendapatkan access token {{domain_esign}}/oauth/token GET • client_id • client_secret • grant_type



: Client id yang telah terdaftar : Client secret yang telah terdaftar : Isi dengan “client_credentials”



Return dari service ini adalah access token dengan tipe Bearer. Adapun masa berlaku access token adalah dalam satuan detik



2.2. User 2.2.1. Cek Status API Cek Status digunakan untuk memeriksa status pengguna berdasarkan NIK. Deskripsi



Service ini digunakan untuk cek status user



Struktur URL



{{domain_esign}}/api/v2/entity/status/{nik}



Method



GET



Path Variable



Nomor Induk Kependudukan



Response



Kode status dan deskripsi HTTP 200 {



“status_code”:1111, “message”:”User telah terdaftar dan memiliki sertifikat elektronik” } Status



Code : 1111



Kode ini menunjukkan bahwa user telah terdaftar pada sistem OSD dan telah memiliki sertifikat di aplikasi eSign. User sudah dapat melakukan proses tanda tangan elektronik Status



Code : 1110



Kode ini menunjukkan bahwa user belum pernah terdaftar sama sekali pada sistem OSD. Langkah selanjutnya adalah melakukan pendaftaran user Status



Code : 1100



Kode ini menunjukkan bahwa user telah memiliki sertifikat dan terdaftar pada Bank lain. Langkah selanjutnya adalah melakukan pendaftaran user untuk proses sinkronisasi data dan pembuatan passphrase Status



Code : 1000



User telah terdaftar sebelumnya pada sistem OSD. Langkah selanjutnya adalah melakukan pendaftaran user untuk proses sinkronisasi data dan pembuatan sertifikat elektronik



2.2.2. Registrasi API Registrasi digunakan untuk pendaftaran pengguna. Data yang diperlukan untuk pendaftaran yaitu nik, nama, email, nomor_telepon, kota, provinsi, nip, jabatan, unit_kerja, image_ttd, ktp, dan surat_rekomendasi. Deskripsi



Struktur URL Method Parameter



Response



Service ini digunakan untuk pendaftaran pengguna. Jika terdapat user yang sudah terdaftar pada sistem OSD dengan NIK yang sama, maka esign akan melakukan sinkronisasi data {{domain_esign}}/api/v2/entity/registrasi POST nik nama email nomor_telepon kota provinsi



: : : : : :



nip jabatan unit_kerja image_ttd



: : : :



ktp surat_rekomendasi



: :



Nomor Induk Kependudukan Nama lengkap sesuai KTP Email aktif pengguna Nomor telepon aktif pengguna Kota tempat tinggal sesuai KTP Provinsi tempat tinggal sesuai KTP Nomor Induk Pegawai Jabatan pada instansi pengguna Unit kerja yang ditempati Spesimen tanda tangan user. Spesimen ini dapat berupa scan tanda tangan atau image lainnya yang telah ditetapkan. Image_ttd yang diupload berupa multipart file Scan KTP pengguna Surat rekomendasi dari atasan pengguna



Pesan status pendaftaran HTTP 200 { “message”:”Proses registrasi berhasil” }



Error



Setiap data yang dikirimkan bersifat mandatory sehingga ketika terdapat data yang tidak diisi maka akan return error HTTP 400 { “error”:”Data nik harus diisi” }



2.3. Proses Tanda Tangan 2.3.1. Kirim Permohonan Tanda Tangan API sign_request digunakan untuk menentukan katakteristik / properties yang akan dilampirkan pada dokumen. Karakteristik tanda tangan elektronik yang dapat ditentukan pada eSign yaitu penandatangan, tampilan, image, posisi, halman, linkQR, dan file PDF. Deskripsi



Digunakan untuk update properties signature



Struktur URL



{{domain_esign}}/api/v2/entity/sign/request



Method Parameter



POST penandatangan tampilan image posisi



yAxis xAxis width height halaman linkQR file



: Nama properties. Penggunaan properties untuk signature berdasarkan nama yang dimasukkan : Tampilan properties signature. Isi dengan visible atau invisible : Isi true jika akan menggunakan image untuk specimen tanda tangan atau isi dengan false jika tidak : Posisi spesimen tanda tangan sesuai dengan format yang telah ditentukan. Isi dengan bottomleft, bottomright, topleft atau topright. : Posisi spesifik yAxis : Posisi spesifik xAxis : Lebar spesimen tanda tangan : Tinggi spesimen tanda tangan : Halaman penempatan spesimen tanda tangan : URL untuk download dokumen yang dijadikan input untuk QR Code : Dokumen file pdf yang akan ditandatangani. File diupload berupa multipart file



Adapun ketentuannya adalah sebagai berikut : 1. Parameter yang digunakan untuk pengiriman permohonan dokumen bersifat optional dan tidak perlu dikirimkan jika tidak digunakan. 2. Parameter yang bersifat mandatory adalah penandatangan, file dan tampilan atau properties



3. Jika ingin menggunakan parameter properties, maka parameter tampilan, image, posisi, yAxis, xAxis, width, height dan halaman tidak perlu dikirimkan. Paremeter linkQR hanya digunakan jika pada pembuatan properties signature, parameter image di set false 4. Jika tidak menggunakan properties, maka parameter tampilan, image, posisi, yAxis, xAxis, width, height dan halaman perlu dikirimkan. Response



Error



HTTP 200 { “id_signed”:”acbc81c3e9d44361945e8097c97ae294”, “message”:” Permintaan tanda tangan telah disampaikan kepada user. Silahkan untuk mengecek status tanda tangan” } HTTP 404 { “error”:”Properties tidak ditemukan” } { }



“error”:”Penandatangan tidak terdaftar”



HTTP 400 { “error”:”Link QR harus diisi” }



2.3.2. Tanda Tangan Dokumen API Tanda tangan dokumen digunakan untuk menjalankan proses tanda tangan berdasarkan karakteristik yang telah diatur pada API sign_request. Proses tanda tangan dapat dilakukan dengan memasukkan passphrase dan id_signed yang didapat dari API sign_request. Deskripsi Struktur URL Method Parameter



Response



Digunakan untuk menandatangani permohonan dokumen {{domain_esign}}/api/v2/entity/sign/{id_signed} POST passphrase approved_info



: Passphrase user : Informasi persetujuan diberikan oleh user



HTTP 200 { “waktu”:”200 ms” “message”:”Proses berhasil” }



yang



Error



HTTP 400 { “error”:”Passphrase anda salah” } {



“error”:”Dokumen telah ditandatangani”



} HTTP 401 { “error”:”Sertifikat belum diterbitkan” }



2.3.3. Download Dokumen API download_dokumen digunakan untuk mengunduh dokumen yang telah ditandatangai secara elektronik. Dokumen dapat diunduh dengan memasukkan id_signed pada URL API download _dokumen. Deskripsi Struktur URL Method Response



Digunakan untuk ditandatangani



download



dokumen



yang



telah



{{domain_esign}}/api/v2/entity/sign/download/{id_signed}



GET HTTP 200 Stream file



Response



HTTP 404 { }



“error”:”Id tidak sesuai”



2.4. Verifikasi PDF API verifikasi_PDF digunakan untuk verifikasi dokumen PDF yang memiliki tanda tangan elektronik. Hasil dari proses verifikasi adalah detail keterangan tanda tangan elektronik dalam format data JSON. Deskripsi Struktur URL Method



Digunakan untuk melakukan verifikasi dokumen yang telah ditandatangani {{domain_esign}}/api/v2/entity/verify POST



Parameter



Response



signed_file



: Dokumen file pdf yang akan diverifikasi. File diupload berupa multipart file



HTTP 200 { "nama_dokumen": "signed.pdf", "jumlah_signature": 1, "notes": "Dokumen asli dan valid, tetapi sertifikat penandatangan tidak dapat diverifikasi", "details": [ { "info_tsa": { "name": "Timestamp Authority Badan Siber dan Sandi Negara", "tsa_cert_validity": "2018-02-05 14:08:11.00 to 2020-02-05 14:08:11.00" }, "signature_field": "Agung Nugraha1547537029382", "info_signer": { "issuer_dn": "CN=OSD DEMO,O=Badan Siber dan Sandi Negara,C=ID", "signer_name": "Agung Nugraha", "signer_cert_validity": "201808-01 13:39:12.00 to 2018-08-31 13:39:12.00", "signer_dn": "[email protected],CN=Agung Nugraha,OU=Seksi Pemenuhan Teknis,O=Balai Sertifikasi Elektronik,L=Jakarta,ST=DKI Jakarta,C=ID,2.5.4.13=240720181052_Tanda Tangan Digital Demo", "cert_user_certified": false }, "signature_document": { "signed_using_tsa": true, "reason": "Tanda tangan elektronik untuk menjamin keaslian dari dokumen elektronik", "document_integrity": true, "signature_value": "314b301806092a864886f70d010903310b06092a864886f 70d010701302f06092a864886f70d0109043122042073d80 285a20812ed605422e9df8245c38b02c4992cac2b8585bd0 ea4f6d38a93", "signed_in": "2019-01-15 14:24:34.00", "location": "Jakarta", "hash_value": "73d80285a20812ed605422e9df8245c38b02c4992cac2b8 585bd0ea4f6d38a93" } } ], "summary": "DOCUMENT VALID !!!" }



Error



HTTP 400 {



“error”:”Dokumen tidak memiliki tanda tangan elektronik” }



3.



INITIAL VECTOR DENGAN POSTMAN



3.1. Proses Autentikasi 3.1.1. Get Access Token Akses API get_access_token dengan parameter client_id dan client_secret untuk mendapat access token.



Jika parameter client_id dan client_secret benar, maka akan didapatkan respons yang terdiri dari token, tipe token, dan masa berlaku token. Access token yang didapat pada proses ini berlaku selama 3600 detik atau 1 jam. Salin nilai access_token untuk digunakan pada API lainnya.



3.1.2. Set Access Token Pilih API yang akan diakses setelah mendapatkan access token. Misal, pada contoh di bawah ini menggunakan API send_sign_request. Pilih menu Authorization pada API yang sedang digunakan, sehingga tampilan Postman berubah menjadi seperti tampilan di bawah ini.



Pilih “Inherit auth from parent” pada tipe authorization. Lalu klik esign_api pada untuk mengatur access token. Selanjutnya, pilih “Bareer Token” pada tipe authorization. Lalu masukkan token yang telah didapat dari API get_access_token. Klik tombol “Update” untuk menyimpan pengaturan.



3.2. Proses Registrasi 3.2.1. API Registrasi API Registrasi dapat diakses dengan terlebih dahulu melakukan Pengaturan Autentikasi. Proses registrasi dilakukan dengan masukkan beberapa parameter string pada bagian params dan parameter file pada body. Parameter string terdiri dari nik, nama, email, nomor_telepon, kota, provinsi, nip, jabatan dan unit_kerja.



Parameter file dapat dimasukkan pada body. Parameter file yang perlu dimasukkan terdiri dari image_ttd, ktp, dan surat_rekomendasi. Jika parameter string dan file telah dimasukkan, kirim parameter tersebut ke API Registrasi dengan menekan tombol send.



Jika proses registrasi berhasil maka eSign akan memberikan respon “Pendaftaran Berhasil” seperti gambar di bawah ini. Selanjutnya dapat dilakukan permohonan verifikasi akun ke Seksi Layanan BSrE.



Catatan: Untuk akun development, verifikasi akun dilakukan secara otomatis dan link untuk set passphrase akan langsung dikirim ke email terdaftar. Sehingga tidak perlu melakukan permohonan verifikasi akun.



3.2.2. Set Passphrase Jika permohonan akun telah diverifikasi, maka pengguna akan mendapat link untuk memasukkan passphrase dari sertifikat yang akan diterbitkan.



Pada halaman set passphrase, pengguna harus memasukkan passphrase dan captcha yang telah disediakan. Jika pengguna mengakses link yang dikirimkan oleh eSign, maka akan diarahkan ke halaman set passphrase.



Jika pengguna berhasil melakukan passphrase, maka akan terdapat pemberitahuan “Set Passphrase Berhasil”. Selanjutnya dapat dilakukan permohonan verifikasi penerbitan sertifikat ke Seksi Layanan BSrE. Pengguna yang telah diverifikasi akan mendapat email yang menyatakan bahwa sertifikat telah diterbitkan.



Catatan: Untuk akun development, verifikasi penerbitan dilakukan secara otomatis dan email notifikasi penerbitan sertifikat akan langsung dikirim ke email terdaftar. Sehingga tidak perlu melakukan permohonan verifikasi penerbitan.



3.3. Proses Tanda Tangan 3.3.1. Kirim Permohonan Tanda Tangan API send_sign_request dapat diakses dengan terlebih dahulu melakukan Pengaturan Autentikasi. Proses penandatangan dilakukan dengan masukkan beberapa parameter string pada bagian params dan parameter file pada body. Parameter string terdiri dari penandatangan, tampilan, image, linkQR, halaman, yAxis, xAxis, width, dan height.



Parameter file dapat dimasukkan pada body. Parameter file berisi dokumen PDF yang akan ditandatangani. Jika parameter string dan file telah dimasukkan, kirim parameter tersebut ke API send_sign_request dengan menekan tombol send.



Jika proses send_sign_request berhasil maka eSign akan memberikan respon “Permohonan tanda tangan berhasil, ….” seperti gambar di bawah ini. Selanjutnya, salin id_signed yang diberikan oleh esign untuk digunakan pada API sign_dokumen.



3.3.2. Tandatangani Dokumen Masukkan id_signed yang didapat pada proses send_sign_request pada URL seperti pada gambar di bawah ini. Selain itu, masukkan parameter passphrase dan approved_info. Jika parameter telah dimasukkan, kirim parameter tersebut ke API sign_dokumen dengan menekan tombol send.



Jika id_signed valid dan passphrase sesuai maka eSign akan memberikan respon yang terdiri dari waktu yang diperlukan untuk tanda tangan dan pesan “Proses berhasil”.



3.3.3. Download Dokumen Masukkan id_signed yang didapat pada proses send_sign_request pada URL download_dokumen seperti pada gambar di bawah ini.



Jika id_signed valid maka HTTP status respon yang diberikan oleh eSign adalah “200 OK”. Download dokumen yang telah ditandatangani dengan menekan tombol Download dan simpan file tersebut dengan nama yang diinginkan.



3.4. Proses Verifikasi Verifikasi PDF yang memiliki tanda tangan elektronik dapat dilakukan dengan mengakses API verify_dokumen. API verify_dokumen dapat diakses dengan terlebih dahulu melakukan Pengaturan Autentikasi. Dokumen PDF yang akan diverifikasi dapat dimasukkan pada body dari API verify_dokumen dan kirim file tersebut dengan klik tombol send.



Hasil dari verifikasi PDF yang diproses oleh esign berupa respon dengan format data JSON seperti gambar di bawah ini.