RESTful API Tanda Tangan Elektronik

Dokumentasi lengkap untuk RESTful API Tanda Tangan Elektronik dari Optima Solution. API ini menyediakan layanan untuk autentikasi, manajemen profil, enkripsi/dekripsi data, dan generasi QR Code.

Base URL

https://api-ttd.optimasolution.co.id

API Information

Version 2.1.0
Contact [email protected]
License Apache 2.0
Terms of Service https://optimasolution.co.id/terms

🔐 Security Requirements

Sebagian besar endpoint memerlukan autentikasi menggunakan Bearer Token dan X-Secret-Key header untuk validasi enkripsi.

Authentication

API ini menggunakan dua jenis autentikasi untuk keamanan maksimal:

Bearer Token Authentication

JWT token yang diperoleh setelah login berhasil

Authorization Header

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Secret Key Authentication

Secret key untuk validasi enkripsi

X-Secret-Key Header

X-Secret-Key: your-secret-key-here

⚠️ Important Security Note

Kedua header autentikasi diperlukan untuk mengakses endpoint yang dilindungi. Pastikan untuk menjaga kerahasiaan token dan secret key Anda.

🔐 Enkripsi Data Dokumen

Gambaran Umum

Enkripsi ini digunakan untuk mengamankan data dokumen (seperti slip gaji, nomor dokumen, nilai amount, dll) sebelum dikirim atau digunakan oleh client. Sistem menggunakan algoritma AES-256-CBC dan menghasilkan output dalam format Base64.

Alur Kerja Enkripsi

Fungsi encrypt() melakukan proses enkripsi:

• Mengubah secret key menjadi hash SHA-256 (256-bit)

• Membuat IV (Initialization Vector) dari 16 byte pertama hash

• Mengubah data menjadi format JSON

• Mengenkripsi JSON menggunakan AES-256-CBC

• Mengubah hasil enkripsi menjadi Base64

2 API mengembalikan ciphertext (hasil enkripsi) ke client

Parameter yang Diperlukan

Fungsi enkripsi memerlukan 2 parameter utama:

1. Secret Key

key String - Secret key unik milik setiap user, digunakan sebagai basis untuk menghasilkan encryption key dan IV

2. Data

Object/Array yang berisi informasi dokumen yang akan dienkripsi:

name String - Nama penerima/pemilik dokumen
document_name String - Nama/jenis dokumen (contoh: "SLIP GAJI BULAN JANUARI")
document_number String - Nomor unik dokumen (contoh: "0123/I/2025")
document_date String - Tanggal dokumen (format: "DD-MM-YYYY")
amount Integer - Nilai nominal/jumlah dalam dokumen

Contoh Data:

{
    "name": "Malik",
    "document_name": "SLIP GAJI BULAN JANUARI",
    "document_number": "0123/I/2025",
    "document_date": "18-01-2025",
    "amount": 10000000
}

ℹ️ Catatan Penting

• IV (Initialization Vector) dibuat dari 16 byte pertama hasil hash SHA-256 dari secret key

• Setiap user memiliki secret key yang berbeda, sehingga hasil enkripsi akan berbeda

• Data dikonversi ke JSON sebelum dienkripsi untuk memastikan format yang konsisten

Implementasi Fungsi encrypt()

Berikut adalah contoh implementasi fungsi enkripsi dalam berbagai bahasa pemrograman:

function encrypt($key, $data) { // Metode enkripsi yang digunakan $method = 'AES-256-CBC'; // Generate hash SHA-256 dari key (menghasilkan 32 bytes) $keyHash = hash('sha256', $key, true); // Ambil 16 bytes pertama dari hash sebagai IV $iv = substr($keyHash, 0, 16); // Konversi data ke JSON $jsonData = json_encode($data); // Enkripsi data menggunakan AES-256-CBC $encrypted = openssl_encrypt( $jsonData, // Data yang akan dienkripsi $method, // Algoritma enkripsi $keyHash, // Encryption key (32 bytes) OPENSSL_RAW_DATA, // Output raw binary $iv // Initialization Vector (16 bytes) ); // Encode hasil enkripsi ke Base64 untuk transmisi return base64_encode($encrypted); }

Alur endpoint testEncrypt

1. Mengambil secret key milik user yang sedang login.

2. Menyiapkan array data dari input atau menggunakan nilai default.

3. Memanggil fungsi encrypt() dengan key dan data tersebut.

4. Mengembalikan response sukses dengan hasil enkripsi.

Implementasi Endpoint testEncrypt()

Endpoint ini digunakan untuk testing enkripsi dengan data sampel atau data yang dikirim oleh client:

public function testEncrypt(Request $request) { // Ambil secret key dari user yang sedang login $key = auth()->user()->key; // Siapkan data dokumen // Gunakan data dari request jika ada, jika tidak gunakan nilai default $data = [ 'name' => $request->input('name', 'Malik'), 'document_name' => $request->input('document_name', 'SLIP GAJI BULAN JANUARI'), 'document_number' => $request->input('document_number', '0123/I/2025'), 'document_date' => $request->input('document_date', '18-01-2025'), 'amount' => $request->input('amount', 10000000) ]; // Enkripsi data menggunakan fungsi encrypt() $encryptedData = $this->encrypt($key, $data); // Kembalikan response sukses dengan hasil enkripsi return response()->json([ 'message' => 'Success', 'status' => 200, 'data' => $encryptedData ]); }