Integrasi API BPJS untuk Developer Indonesia: Panduan Praktis

Jika kamu membangun sistem HR, ERP, atau klinik untuk organisasi di Indonesia, integrasi BPJS cepat atau lambat akan muncul. BPJS Ketenagakerjaan (jaminan sosial ketenagakerjaan) dan BPJS Kesehatan (jaminan kesehatan nasional) menjalankan program wajib bagi pekerja formal, sehingga sistem yang menyimpan data karyawan atau pasien di Indonesia sering perlu bertukar data dengan keduanya. Saya menyusun panduan ini saat meriset integrasi BPJS untuk calon proyek ERP sebuah firma hukum menengah di Indonesia. Proyek itu belum dibangun, jadi anggap ini tulisan riset, bukan laporan lapangan. Meski begitu, jarak antara kanal resmi BPJS dan kenyataan yang dihadapi developer ternyata cukup lebar untuk dibagikan.

Ikhtisar BPJS: Yang Perlu Diketahui Developer

Ada dua badan BPJS yang terpisah. BPJS Ketenagakerjaan (sebelumnya Jamsostek) menjalankan jaminan kecelakaan kerja (JKK), jaminan kematian (JKM), jaminan hari tua (JHT), jaminan pensiun (JP), dan jaminan kehilangan pekerjaan (JKP, dibentuk lewat PP 37/2021). BPJS Kesehatan menjalankan jaminan kesehatan nasional (JKN). Keduanya punya sistem, kredensial, dan persyaratan integrasi yang terpisah. Untuk sistem HR dan ERP, sisi yang relevan adalah kanal pelaporan dan pembayaran BPJS Ketenagakerjaan. Untuk sistem layanan kesehatan (klinik, rumah sakit), layanan PCare dan VClaim BPJS Kesehatan adalah antarmuka yang relevan.

Arsitektur API BPJS Ketenagakerjaan

BPJS Ketenagakerjaan tidak menjalankan portal developer publik yang self-service. Subdomain api-dev.bpjsketenagakerjaan.go.id yang dulu dirujuk artikel ini kini dialihfungsikan menjadi sistem presensi internal, pengingat bahwa subdomain BPJS bisa ditata ulang tanpa pemberitahuan, jadi selalu verifikasi URL BPJS sebelum membangun integrasi di atasnya. Dalam praktiknya, sebagian besar sistem HR dan payroll berhubungan dengan BPJS Ketenagakerjaan lewat dua portal web resmi, bukan API mentah: SIPP Online (sipp.bpjsketenagakerjaan.go.id), tempat pemberi kerja terdaftar mengelola data pekerja dan laporan iuran, serta EPS (eps.bpjsketenagakerjaan.go.id) untuk pembayaran iuran host-to-host lewat bank mitra. API bridging live dengan kredensial yang diterbitkan memang ada, tetapi bukan pendaftaran self-service: aksesnya dinegosiasikan kasus per kasus dengan tim kemitraan IT BPJS, dan kebanyakan tim tidak pernah membutuhkannya karena SIPP dan EPS sudah mencakup pelaporan dan pembayaran.

API PCare dan VClaim BPJS Kesehatan

BPJS Kesehatan menyediakan beberapa layanan bridging: VClaim untuk pengecekan eligibilitas dan klaim (dipakai rumah sakit), PCare untuk layanan primer (puskesmas, klinik pratama), Antrean untuk manajemen antrean di faskes mitra BPJS, dan Apotek untuk farmasi. Permintaan diautentikasi dengan consumer ID, timestamp Unix, dan tanda tangan HMAC-SHA256 yang dihitung dengan secret key faskes, dikirim bersama header user key. Akses produksi membutuhkan kemitraan formal dengan BPJS Kesehatan; layanan produksi tidak bisa diakses tanpa kredensial yang diterbitkan untuk faskes mitra. Berbeda dengan BPJS Ketenagakerjaan, BPJS Kesehatan punya ekosistem open-source yang aktif: ssecd/jkn membungkus VClaim, PCare, Antrean, Apotek, dan i-Care untuk Node.js, Deno, dan Bun, sedangkan aamdsam/bridging-bpjs menyediakan versi Laravel/PHP untuk VClaim dan PCare. Keduanya layak dievaluasi sebelum menulis klien dari nol.

Mengajukan Akses Bridging BPJS Kesehatan (VClaim / PCare)

Berbeda dengan BPJS Ketenagakerjaan, BPJS Kesehatan mendokumentasikan proses bridging untuk fasilitas kesehatan. Pedoman bridging VClaim 2.0 miliknya menjabarkan tahapan untuk rumah sakit: faskes mengirim Surat Permohonan Bridging Sistem ke Kantor Cabang BPJS Kesehatan beserta Pakta Integritas yang ditandatangani; BPJS menerbitkan kredensial tester, yaitu Consumer ID, Secret Key, dan User Key, untuk pengembangan; faskes membangun sistem dengan kredensial itu dan menjalani user acceptance test, yang hanya lolos jika seluruh ceklis UAT terpenuhi; baru setelah itu BPJS menerbitkan kredensial produksi, dengan Pakta Integritas kedua. Pedoman itu ditujukan untuk rumah sakit, jadi klinik dan puskesmas yang mengintegrasikan PCare sebaiknya menanyakan prosedur terkini ke kantor cabangnya sebelum menyusun jadwal.

// BPJS Kesehatan bridging (VClaim, PCare, Antrean): HMAC-SHA256 signature
// in Node.js, the pattern the open-source ssecd/jkn client implements.
// BPJS Ketenagakerjaan's bridging API issues its own spec under a PKS.
import crypto from "crypto"

function buildBpjsHeaders(consId: string, secret: string, userKey: string) {
  // Seconds since the Unix epoch, not milliseconds
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const signature = crypto
    .createHmac("sha256", secret)
    .update(consId + "&" + timestamp)
    .digest("base64")

  return {
    "X-cons-id":    consId,
    "X-timestamp":  timestamp,
    "X-signature":  signature,
    "user_key":     userKey, // listed in BPJS Kesehatan's signature docs
    "Content-Type": "application/json",
  }
}
        

Angka Iuran Milik Peraturan, Bukan Kode Kamu

Sistem yang melapor ke BPJS Ketenagakerjaan membutuhkan besaran iuran, tetapi panduan ini sengaja tidak mencantumkan tarif atau batas upah. Semuanya ditetapkan oleh peraturan pemerintah dan oleh BPJS, berbeda per program dan, untuk jaminan kecelakaan kerja, per kelas risiko, dan sebagian batas disesuaikan secara berkala, sehingga angka yang disalin dari blog, termasuk blog ini, bisa sudah usang saat kamu membacanya. Perlakukan sebagai konfigurasi bertanggal: simpan setiap nilai beserta dasar hukum dan tanggal berlakunya, ambil dari BPJS atau peraturannya langsung, dan uji hasil sistemmu terhadap angka BPJS sendiri sebelum go-live. Satu hal struktural yang tidak berubah bersama angkanya: JKP tidak punya potongan terpisah dari pekerja, karena berdasarkan PP 6/2025 program ini didanai dari iuran Pemerintah Pusat dan rekomposisi iuran JKK.

Tangga Integrasi Realistis untuk BPJS Ketenagakerjaan

Daripada satu pola integrasi, anggap akses BPJS Ketenagakerjaan sebagai tangga, dan pilih anak tangga terendah yang memenuhi kebutuhanmu, karena setiap anak tangga ke atas membutuhkan waktu persetujuan lebih lama. Anak tangga 1: siapkan data pekerja dan mutasi bulan itu di sistem HR dan ekspor file yang kompatibel dengan SIPP untuk diunggah manual, tanpa perlu persetujuan. Anak tangga 2: bekerja langsung di SIPP Online dan kelola mutasi pekerja serta laporan iuran lewat portal, bukan menangani file secara manual; ini self-service bagi pemberi kerja terdaftar. Anak tangga 3: hubungkan EPS ke bank mitra untuk pembayaran iuran host-to-host, menghilangkan langkah transfer bank manual. Anak tangga 4: gunakan agregator PPOB seperti IAK API untuk inquiry atau pembayaran BPJS Ketenagakerjaan sesuai kebutuhan tanpa hubungan langsung dengan BPJS; ini layanan pihak ketiga berbayar, tetapi live. Anak tangga 5: negosiasikan PKS formal untuk API bridging live, dengan pengecekan real-time dan kendali programatik penuh, yang hanya masuk akal pada skala signifikan, karena persetujuannya butuh berminggu-minggu hingga berbulan-bulan. Sebagian besar produk HR untuk pasar Indonesia tidak pernah melewati anak tangga 3.

1. Siapkan data pekerja bulan itu — Di akhir bulan, kumpulkan karyawan baru, karyawan keluar, dan mutasi pekerja lainnya dari sistem HR, dengan besaran iuran diambil dari konfigurasi bertanggal, bukan nilai yang di-hardcode.
2. Buat file sesuai format SIPP — Ekspor data pekerja dan mutasi bulan itu ke format file yang diterima SIPP Online.
3. Unggah lewat SIPP Online — Kirim file tersebut melalui sipp.bpjsketenagakerjaan.go.id, portal self-service untuk pemberi kerja yang tidak memerlukan PKS atau akses API live.
4. Bayar lewat EPS atau bank mitra — Selesaikan tagihan iuran melalui Electronic Payment System BPJS atau kanal pembayaran bank yang disetujui.
5. Simpan bukti pengiriman — Simpan tanda terima konfirmasi dari SIPP di sistem ERP atau HR sebagai jejak audit.

# BPJS Integration Patterns (beyond batch reporting via SIPP Online)

## Pattern 2: Real-time JHT Balance Check (negotiated bridging API)
GET https://<cons-id-issued-endpoint>/saldo/...
Headers: X-cons-id, X-timestamp, X-signature
Response: { "kpj": "...", "saldo": "...", "status": "active" }
# Endpoint issued per-company after PKS approval — not publicly documented

## Pattern 3: PPOB Aggregator (no PKS required)
POST https://api.iak.id/api/v1/bill/check
Body: {
  "commands": "inq-pasca",
  "username": "your_registered_phone_number",
  "code": "BPJSTKPU",       // Penerima Upah (salaried); BPJSTKBPU for informal workers
  "hp": "KPJ_or_bill_number",
  "ref_id": "unique_ref_id",
  "sign": "md5(username + api_key + ref_id)"
}
# A paid third-party service: check the aggregator's own terms
# No direct BPJS partnership needed — separate inquiry + payment calls
        

Kode Praktis: Autentikasi Bridging Berbasis Tanda Tangan di Node.js

BPJS Ketenagakerjaan tidak memublikasikan skema autentikasi API bridging-nya; spesifikasinya diberikan bersama kredensial di bawah PKS. Sebaliknya, layanan bridging BPJS Kesehatan sudah banyak dicakup klien open-source, dan contoh di bawah mengikuti ssecd/jkn: tanda tangan HMAC-SHA256 atas consumer ID dan timestamp Unix dalam detik yang digabung dengan tanda ampersand, dikunci dengan secret key lalu di-encode base64, dikirim lewat header X-cons-id, X-timestamp, dan X-signature bersama user_key. Katalog web service resmi BPJS Kesehatan mendokumentasikan skema yang sama. Jebakan penting: staging kadang mengembalikan kode error yang berbeda dari produksi, jadi uji dengan kredensial persis yang akan kamu pakai. Jika kamu mencapai anak tangga 5 di sisi Ketenagakerjaan, ikuti spesifikasi yang diberikan BPJS, bukan contoh ini.

Layanan Integrasi BPJS Pihak Ketiga

Untuk proyek yang integrasi BPJS langsungnya terlalu rumit atau timeline PKS-nya terlalu lama, ada layanan pihak ketiga di Indonesia. IAK API (api.iak.id) menawarkan inquiry BPJS Ketenagakerjaan sebagai produk pascabayar melalui API agregator PPOB (payment point online bank), dengan kode produk terpisah untuk peserta penerima upah (BPJSTKPU) dan peserta bukan penerima upah atau informal (BPJSTKBPU). Permintaan ditandatangani dengan hash MD5 dari username, API key, dan reference ID, bukan skema milik BPJS sendiri, sehingga jauh lebih mudah diintegrasikan, yang menjelaskan mengapa agregator PPOB populer di kalangan platform HR SaaS. Trade-off-nya: ini layanan pihak ketiga berbayar, dan kamu bergantung pada uptime serta akurasi data pihak ketiga.

Membangun Integrasi BPJS yang Mudah Dirawat

Aturan BPJS dan spesifikasi API berubah, dan endpoint pernah berpindah. Bangun integrasimu dengan mempertimbangkan perubahan: simpan setiap parameter iuran di tabel database atau file konfigurasi beserta tanggal berlakunya, bukan konstanta yang di-hardcode; tulis klien API yang sadar versi agar bisa diperbarui tanpa menulis ulang logika bisnis; catat setiap permintaan dan respons API untuk debugging; dan tulis automated test yang memeriksa hasil sistemmu terhadap contoh yang sudah dikonfirmasi dengan BPJS. Ketika aturan berubah, biasanya lewat Peraturan Pemerintah, kamu seharusnya bisa memperbarui sistem di satu tempat dengan yakin.

Sumber & Bacaan Lanjutan