Bridging BPJS VClaim: Yang Perlu Disiapkan Sebelum Menulis Kode

Rumah sakit yang melayani pasien JKN hampir pasti berurusan dengan VClaim, web service BPJS Kesehatan untuk kebutuhan seperti pengecekan kepesertaan, pembuatan SEP, dan rujukan. “Bridging” berarti menghubungkan SIMRS langsung ke layanan ini, supaya petugas tidak perlu mengetik ulang data di aplikasi terpisah.

Artikel ini adalah checklist hal-hal yang sebaiknya beres sebelum menulis kode integrasi.

1. Kredensial dari BPJS Kesehatan

Rumah sakit perlu mendapatkan kredensial resmi dari BPJS Kesehatan, umumnya berupa:

• Consumer ID (cons ID)
• Secret key
• User key untuk layanan yang dipakai

Perlakukan semuanya seperti password: simpan di environment variable atau secret manager, pisahkan kredensial untuk lingkungan pengujian dan production, dan batasi siapa yang bisa melihatnya.

2. Signature di setiap request

Setiap request ke VClaim membawa header identitas dan signature yang dibuat oleh sisi klien:

• X-cons-id — consumer ID
• X-timestamp — waktu request
• X-signature — hasil HMAC-SHA256 yang ditandatangani dengan secret key
• user_key — kunci layanan

Karena signature bergantung pada timestamp, signature harus dibuat ulang untuk setiap request. Jangan menyimpan dan memakai ulang signature lama.

3. Jam server harus akurat

Kesalahan yang sering menghabiskan waktu: request ditolak padahal kode sudah benar, ternyata jam server SIMRS melenceng. Pastikan server tersinkron dengan NTP. Ini hal kecil yang sering terlupa saat server dipindah atau dibuat ulang.

4. Respons terenkripsi

Pada VClaim versi 2, data respons dikirim dalam bentuk terenkripsi dan terkompresi. SIMRS perlu:

1. mendekripsi respons menggunakan kunci yang diturunkan dari kredensial dan timestamp request, lalu
2. mendekompresi hasilnya (menggunakan LZ-string) sebelum bisa dibaca sebagai JSON.

Buat fungsi dekripsi ini sebagai satu modul terpisah yang punya unit test, karena semua fitur bridging bergantung padanya.

5. Tangani metadata respons, bukan hanya HTTP status

Respons VClaim membawa bagian metadata berisi kode dan pesan. Request bisa saja berhasil secara HTTP, tetapi metadata menyatakan data tidak ditemukan atau ada aturan bisnis yang dilanggar. Tampilkan pesan ini dengan jelas ke petugas, jangan hanya “terjadi kesalahan”.

6. Log, retry, dan fallback

• Log request dan respons (tanpa membocorkan data sensitif) untuk menelusuri masalah.
• Retry untuk gangguan jaringan sementara, tapi jangan retry otomatis untuk aksi yang tidak boleh terduplikasi.
• Rencana cadangan saat layanan BPJS sedang gangguan, supaya pelayanan pasien tidak berhenti.

Ringkasan

Area	Yang perlu dipastikan
Kredensial	Cons ID, secret key, user key tersimpan aman, terpisah per lingkungan
Signature	Dibuat ulang tiap request dengan HMAC-SHA256
Server	Jam tersinkron NTP
Respons	Modul dekripsi + dekompresi yang teruji
Error	Metadata dibaca dan ditampilkan jelas ke petugas
Operasional	Log, retry yang aman, dan rencana cadangan