Web Dev
Integrasi API BPJS untuk Developer Indonesia: Panduan Praktis
November 202512 menit bacaDiperbarui 15 Jul 2026
Web Dev
API BPJS Ketenagakerjaan menggunakan autentikasi tanda tangan HMAC-SHA256. Kamu membutuhkan Consumer ID (Cons ID) yang diterbitkan BPJS, Secret Key untuk menandatangani permintaan, dan User Key untuk jenis layanan tertentu. Tanda tangan dibangun dari string yang terdiri dari ConsID, timestamp permintaan (dalam detik Unix epoch), dan Secret Key.
Penyebab paling umum adalah drift jam server. Autentikasi HMAC BPJS Ketenagakerjaan mengharuskan timestamp permintaan cocok dengan jam server mereka dalam jendela toleransi yang sempit — selisih beberapa detik saja sudah memicu 401 yang terlihat seperti kesalahan kredensial. Selalu gunakan sinkronisasi waktu NTP di server integrasi dan catat timestamp yang kamu kirim beserta kode respons untuk mengisolasi masalah.
Hanya jika kamu membutuhkan API bridging HMAC-SHA256 yang live untuk pengecekan real-time — sebagian besar sistem payroll tidak pernah sampai ke tingkat itu, karena SIPP Online (pelaporan gratis, self-service) dan EPS (pembayaran host-to-host) sudah mencakup pelaporan bulanan dan pembayaran kontribusi. Jika kamu memang membutuhkannya, BPJS mengharapkan entitas hukum formal (PT atau CV) sebagai pihak penandatangan, kasus penggunaan yang terdokumentasi, kontak teknis yang bisa melewati review keamanan, dan kesabaran: siklus dari permohonan hingga PKS ditandatangani dan kredensial produksi umumnya butuh berminggu-minggu hingga berbulan-bulan. Untuk proyek klien, perusahaan klien — bukan milik developer — hampir selalu menjadi pihak yang menandatangani.
Untuk BPJS Ketenagakerjaan: JKK sebesar 0,24-1,74% dari gaji (pemberi kerja, sesuai kelas risiko); JKM 0,30% (pemberi kerja); JHT 5,7% total (3,7% pemberi kerja + 2% karyawan); JP 3% total (2% pemberi kerja + 1% karyawan, dibatasi pada basis gaji IDR 11.086.300 per Maret 2026 — batas ini disesuaikan setiap tahun berdasarkan PP No. 45/2015, jadi simpan sebagai nilai konfigurasi); dan JKP 0,46%, didanai sepenuhnya oleh pemerintah dan rekomposisi kontribusi JKK/JKM, bukan dipotong dari gaji. Untuk BPJS Kesehatan: 5% dari gaji (4% pemberi kerja + 1% karyawan), dengan gaji dibatasi IDR 12 juta untuk perhitungan premi. Angka-angka ini harus cocok persis dengan perhitungan BPJS sendiri agar laporan tidak ditolak.
Layanan agregator pihak ketiga seperti IAK API (api.iak.id) menawarkan inquiry BPJS Ketenagakerjaan sebagai produk pascabayar melalui API agregator PPOB, dengan kode produk terpisah untuk pekerja penerima upah (BPJSTKPU) dan peserta informal (BPJSTKBPU), tanpa perlu kemitraan langsung dengan BPJS. Permintaan ditandatangani dengan hash MD5 sederhana, bukan skema HMAC-SHA256 milik BPJS sendiri, sehingga rute ini populer di kalangan aplikasi pembayaran dan platform HR SaaS. Trade-offnya adalah biaya per transaksi yang dibayarkan ke agregator dan ketergantungan pada uptime serta akurasi data pihak ketiga.
Mulai dari anak tangga terbawah: hitung kontribusi dengan benar dan ekspor file yang kompatibel dengan SIPP untuk diunggah manual — tanpa perlu persetujuan. Selanjutnya, daftarkan perusahaanmu ke SIPP Online (sipp.bpjsketenagakerjaan.go.id) untuk mengelola data tenaga kerja dan upah langsung lewat portal, bukan file manual. Tambahkan EPS (eps.bpjsketenagakerjaan.go.id) untuk pembayaran host-to-host lewat bank mitra. Kejar API bridging yang live — yang membutuhkan PKS yang dinegosiasikan — hanya jika produkmu benar-benar membutuhkan pengecekan saldo real-time yang tidak bisa disediakan SIPP dan EPS.
Fasilitasmu harus sudah menjadi faskes mitra BPJS Kesehatan yang menjalankan software klinik/rumah sakitnya minimal satu bulan, dengan minimal satu sesi training staf yang selesai dan 30+ rekam medis elektronik aktif dalam sebulan terakhir. Ajukan surat permohonan tertulis ke Kantor Cabang BPJS Kesehatan setempat yang mencantumkan Kode Faskes, nama fasilitas, Pakta Integritas yang ditandatangani, dan URL web service produksimu untuk whitelist IP/domain. BPJS menerbitkan kredensial development terlebih dahulu; setelah UAT bersama tim IT regional BPJS lolos, kamu menerima Consumer ID, Secret Key, dan User Key produksi. Sisihkan waktu beberapa minggu untuk siklus lengkapnya.
Ringkasan Utama
Integrasi BPJS untuk sistem payroll dan ERP di Indonesia bukan sekadar API publik tunggal: sebagian besar perusahaan menghitung dan melaporkan iuran lewat portal gratis SIPP Online, API bridging real-time dengan tanda tangan HMAC-SHA256 hanya tersedia lewat perjanjian PKS resmi dengan BPJS Ketenagakerjaan, sementara akses VClaim dan PCare BPJS Kesehatan terbuka bagi fasilitas kesehatan yang memenuhi syarat dan mengajukan langsung.
Jika kamu membangun sistem penggajian, HR, atau ERP untuk perusahaan Indonesia, integrasi BPJS pada akhirnya tidak bisa dihindari. BPJS Ketenagakerjaan (jaminan sosial ketenagakerjaan) dan BPJS Kesehatan (asuransi kesehatan) wajib bagi semua karyawan formal Indonesia — yang berarti sistem penggajian apapun yang menangani data karyawan Indonesia perlu menghitung kontribusi BPJS, melaporkannya, dan idealnya menyerahkannya secara programatis. Panduan ini saya susun saat meriset integrasi BPJS untuk rencana proyek ERP sebuah kantor hukum berskala menengah di Indonesia — proyek itu belum dibangun, jadi anggap ini sebagai catatan riset dan pembelajaran, bukan laporan dari lapangan. Meski begitu, jarak antara dokumentasi resmi BPJS dan perilaku API-nya di dunia nyata ternyata cukup lebar sehingga saya ingin membagikan apa yang saya temukan.
Ada dua sistem BPJS yang terpisah: BPJS Ketenagakerjaan (sebelumnya Jamsostek) mencakup asuransi kecelakaan kerja (JKK), asuransi kematian (JKM), tabungan hari tua (JHT), pensiun (JP), dan jaminan kehilangan pekerjaan (JKP — ditambahkan pada 2022). BPJS Kesehatan mencakup asuransi kesehatan (JKN). Keduanya memiliki API terpisah, kredensial terpisah, dan persyaratan integrasi terpisah. Untuk integrasi penggajian, kamu terutama membutuhkan perhitungan kontribusi dan pelaporan BPJS Ketenagakerjaan. Untuk sistem manajemen layanan kesehatan (klinik, rumah sakit), API PCare dan VClaim BPJS Kesehatan adalah antarmuka yang relevan.
BPJS Ketenagakerjaan tidak menjalankan portal developer publik yang self-service. Subdomain api-dev.bpjsketenagakerjaan.go.id yang dulu dirujuk artikel ini kini sudah 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 payroll berhubungan dengan BPJS Ketenagakerjaan lewat dua portal web resmi, bukan API mentah: SIPP Online (sipp.bpjsketenagakerjaan.go.id) untuk mengelola data tenaga kerja, upah, dan kontribusi — gratis untuk perusahaan berbadan hukum yang terdaftar, dan makin mampu menerima sinkronisasi langsung dari software payroll lewat API key yang diterbitkan per perusahaan — serta EPS (eps.bpjsketenagakerjaan.go.id) untuk pembayaran kontribusi host-to-host lewat bank mitra. API bridging HMAC-SHA256 yang live (Cons ID, Secret Key, User Key) memang ada, tapi bukan pendaftaran self-service; ini dinegosiasikan kasus per kasus dengan tim kemitraan IT BPJS, dan kebanyakan tim tidak pernah membutuhkannya karena SIPP dan EPS sudah mencakup pelaporan dan pembayaran.
BPJS Kesehatan menawarkan beberapa layanan API: VClaim untuk verifikasi eligibilitas dan manajemen klaim (digunakan oleh rumah sakit); PCare untuk integrasi klinik primer (puskesmas, klinik pratama); Antrean untuk manajemen antrian di fasilitas kesehatan terdaftar BPJS; dan Apotek untuk manajemen farmasi. Autentikasi menggunakan kredensial dasar (username/password, sering dikodekan dalam base64) ditambah tanda tangan yang diturunkan dari secret bersama. Integrasi membutuhkan kemitraan formal dengan BPJS Kesehatan — kamu tidak bisa mengakses API produksi tanpa perjanjian kerja sama yang ditandatangani (PKS — Perjanjian Kerja Sama). Berbeda dengan BPJS Ketenagakerjaan, BPJS Kesehatan memiliki ekosistem library komunitas yang aktif: ssecd/jkn membungkus VClaim, PCare, Antrean, Apotek, dan i-Care untuk Node.js, Deno, dan Bun, sedangkan aamdsam/bridging-bpjs menawarkan versi Laravel/PHP untuk VClaim dan PCare — keduanya layak dievaluasi sebelum menulis klien dari nol.
Berbeda dengan BPJS Ketenagakerjaan, proses bridging BPJS Kesehatan untuk fasilitas kesehatan sudah terdokumentasi dengan baik dan sebagian besar bisa diinisiasi sendiri. Untuk mengajukan, fasilitasmu (klinik, puskesmas, atau rumah sakit) harus sudah menjadi faskes mitra BPJS Kesehatan yang menjalankan software klinik/rumah sakitnya minimal satu bulan, dengan minimal satu sesi training staf yang selesai dan minimal 30 rekam medis elektronik aktif dalam sebulan terakhir. Kamu kemudian mengajukan surat permohonan tertulis ke Kantor Cabang BPJS Kesehatan setempat untuk meminta Consumer ID, Secret Key, dan User Key tingkat development. Surat permohonan harus mencantumkan Kode Faskes dan nama fasilitasmu, Pakta Integritas yang ditandatangani (pakta yang mengatur penggunaan Consumer ID), dan URL web service produksimu agar BPJS bisa melakukan whitelist IP atau domain. Setelah pengembangan selesai, kamu mengajukan permohonan UAT (User Acceptance Test); tim IT helpdesk regional dan PMP BPJS menjalankan UAT bersama developer-mu, dan hanya setelah lolos kamu menerima kredensial produksi. Sisihkan waktu beberapa minggu untuk siklus lengkap ini, dan konfirmasi ke kantor cabangmu apakah surat permohonan perlu tanda tangan fisik dan materai — sebagian besar cabang masih mewajibkan pengajuan kertas selain yang digital.
// BPJS Ketenagakerjaan — HMAC-SHA256 Auth (Node.js)
import crypto from "crypto"
function buildBpjsHeaders(consId: string, secret: string) {
const timestamp = Math.floor(Date.now() / 1000).toString()
// Signature string: consId + "&" + timestamp
const sigString = consId + "&" + timestamp
const signature = crypto
.createHmac("sha256", secret)
.update(sigString)
.digest("base64")
return {
"X-cons-id": consId,
"X-timestamp": timestamp,
"X-signature": signature,
"Content-Type":"application/json",
}
}
// Contribution calculation (2026 rates — JP cap effective March 2026)
function calcBpjsContributions(gaji: number) {
const capJP = 11_086_300 // adjusted yearly per PP No. 45/2015, GDP-indexed
const capKes = 12_000_000
return {
jht_employer: gaji * 0.037,
jht_employee: gaji * 0.02,
jp_employer: Math.min(gaji, capJP) * 0.02,
jp_employee: Math.min(gaji, capJP) * 0.01,
jkk: gaji * 0.0024, // risk class 1 (office)
jkm: gaji * 0.003,
jkp: gaji * 0.0046, // JKP — government-funded, not payroll-deducted
kes_employer: Math.min(gaji, capKes) * 0.04,
kes_employee: Math.min(gaji, capKes) * 0.01,
}
}
Format timestamp API BPJS adalah sumber kegagalan integrasi yang umum. Autentikasi HMAC BPJS Ketenagakerjaan membutuhkan timestamp permintaan dalam format tertentu yang cocok dengan jam server mereka dalam jendela toleransi. Jika jam servermu menyimpang lebih dari beberapa detik, semua permintaan akan mengembalikan error 401 yang terlihat seperti masalah kredensial. Selalu gunakan sinkronisasi waktu NTP di server integrasi dan catat timestamp yang kamu kirim beserta kode respons saat men-debug kegagalan autentikasi BPJS.
Sebelum kamu bisa berintegrasi dengan API BPJS, kamu perlu menghitung kontribusi dengan benar. Per Maret 2026, tarif kontribusi untuk BPJS Ketenagakerjaan adalah: JKK (Jaminan Kecelakaan Kerja): 0,24%–1,74% dari gaji (pemberi kerja, tarif tergantung kelas risiko); JKM (Jaminan Kematian): 0,30% dari gaji (pemberi kerja); JHT (Jaminan Hari Tua): 5,7% dari gaji total (3,7% pemberi kerja + 2% karyawan); JP (Jaminan Pensiun): 3% dari gaji total (2% pemberi kerja + 1% karyawan), dibatasi pada basis upah IDR 11.086.300 — angka yang disesuaikan BPJS setiap tahun berdasarkan pertumbuhan PDB Indonesia sesuai PP No. 45/2015, jadi simpan sebagai nilai yang bisa dikonfigurasi, bukan konstanta tetap; JKP (Jaminan Kehilangan Pekerjaan): 0,46% dari gaji, didanai sepenuhnya oleh pemerintah pusat dan rekomposisi kontribusi JKK/JKM — tidak pernah dipotong dari gaji pemberi kerja maupun karyawan, jadi jangan masukkan ke perhitungan gaji bersih meski muncul di file pelaporan BPJS. Untuk BPJS Kesehatan: 5% dari gaji (4% pemberi kerja + 1% karyawan, gaji dibatasi IDR 12 juta untuk perhitungan premi, belum berubah sejak penyesuaian terakhir). Perhitungan ini mudah diimplementasikan tapi harus cocok persis dengan perhitungan BPJS sendiri — perbedaan akan menyebabkan penolakan pelaporan.
Daripada satu pola integrasi, anggap akses BPJS Ketenagakerjaan sebagai tangga — pilih anak tangga terendah yang memenuhi kebutuhanmu, karena setiap anak tangga ke atas membutuhkan waktu persetujuan lebih lama. Anak tangga 1: hitung kontribusi dengan benar di mesin payroll-mu dan ekspor file yang kompatibel dengan SIPP untuk diunggah manual — tanpa persetujuan sama sekali, bisa dilakukan perusahaan mana pun hari ini. Anak tangga 2: daftar langsung ke SIPP Online dan kelola mutasi tenaga kerja serta upah, plus pengajuan kontribusi, lewat portal alih-alih penanganan file manual — gratis, self-service, tersedia untuk perusahaan terdaftar mana pun. Anak tangga 3: hubungkan EPS ke bank mitra untuk pembayaran kontribusi host-to-host, menghilangkan langkah transfer bank manual. Anak tangga 4: gunakan agregator PPOB seperti IAK API untuk inquiry atau pembayaran BPJS Ketenagakerjaan on-demand tanpa hubungan langsung dengan BPJS — ada biaya per transaksi, tapi live. Anak tangga 5: negosiasikan PKS formal untuk API bridging HMAC-SHA256 yang live — pengecekan saldo real-time dan kontrol programatik penuh, tapi hanya masuk akal pada skala yang signifikan, karena proses persetujuannya butuh berminggu-minggu hingga berbulan-bulan. Sebagian besar produk HR dan payroll untuk pasar Indonesia tidak pernah melewati anak tangga 3.
# 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": 12500000, "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)"
}
# Charges per-transaction fee (~IDR 2,500–5,000)
# No direct BPJS partnership needed — separate inquiry + payment calls
Berikut pola autentikasi untuk API BPJS Ketenagakerjaan di Node.js. Tanda tangan dibuat menggunakan HMAC-SHA256 atas string yang terdiri dari ConsID:timestamp:Secret. Timestamp harus dalam detik sejak Unix epoch (bukan milidetik). Header permintaan membutuhkan X-cons-id, X-timestamp, X-signature, dan Content-Type. Gotcha kritis: lingkungan staging BPJS terkadang mengembalikan kode error yang berbeda dari produksi — selalu uji kredensial produksi yang tepat di staging sebelum menganggap integrasi selesai. Perlakukan ini sebagai tingkat anak tangga 5 yang dijelaskan di atas — pastikan kamu benar-benar sudah menghabiskan opsi SIPP Online, EPS, dan agregator sebelum berinvestasi pada level integrasi ini.
Jika kamu benar-benar membutuhkan anak tangga 5 — API bridging yang live — siapkan diri untuk proses persetujuan sungguhan, bukan formulir pendaftaran. BPJS Ketenagakerjaan akan mengharapkan: entitas hukum formal (PT atau CV, bukan individu atau kontrak freelance) sebagai pihak penandatangan; kasus penggunaan yang terdokumentasi yang membenarkan akses real-time, karena pelaporan batch lewat SIPP sudah mencakup sebagian besar kebutuhan; kontak teknis yang bisa melewati review keamanan dan integrasi BPJS; dan kesabaran — siklus dari permohonan awal hingga PKS yang ditandatangani dan kredensial produksi umumnya butuh berminggu-minggu hingga berbulan-bulan, dan BPJS yang mengendalikan timeline, bukan kamu. Jika kamu membangun untuk klien alih-alih perusahaanmu sendiri, entitas hukum klien — bukan studio developmentmu — hampir selalu menjadi pihak yang harus menandatangani, jadi konfirmasi ini sebelum memberikan estimasi waktu pengerjaan. Ada baiknya secara eksplisit bertanya ke tim kemitraan BPJS apakah kasus penggunaanmu benar-benar membutuhkan API live, karena SIPP Online, EPS, atau agregator PPOB sering kali sudah memenuhi kebutuhan bisnis sebenarnya dengan biaya persetujuan jauh lebih kecil.
Untuk proyek di mana integrasi API BPJS langsung terlalu kompleks atau timeline PKS terlalu lama, layanan integrasi BPJS pihak ketiga ada di Indonesia. IAK API (api.iak.id) menawarkan inquiry BPJS Ketenagakerjaan sebagai produk pascabayar melalui API agregator PPOB (payment point online bank) mereka, dengan kode produk terpisah untuk pekerja penerima upah (BPJSTKPU) dan peserta bukan penerima upah/informal (BPJSTKBPU). Permintaan ditandatangani dengan hash MD5 dari username, API key, dan reference ID — bukan skema HMAC-SHA256 milik BPJS sendiri — sehingga jauh lebih mudah diintegrasikan, yang menjelaskan mengapa agregator PPOB populer di kalangan platform HR SaaS. Trade-offnya: kamu membayar biaya per transaksi ke agregator, dan kamu bergantung pada uptime serta akurasi data pihak ketiga.
Regulasi BPJS dan spesifikasi API berubah — tarif kontribusi telah diperbarui beberapa kali dalam lima tahun terakhir, dan endpoint API telah bermigrasi. Bangun integrasi BPJS-mu dengan mempertimbangkan perubahan: letakkan semua tarif kontribusi di tabel database atau file konfigurasi (bukan konstanta yang di-hardcode); implementasikan klien API yang sadar versi yang bisa diperbarui tanpa menulis ulang logika bisnis; log semua permintaan dan respons API untuk debugging; dan implementasikan automated test yang memvalidasi perhitungan kontribusi terhadap contoh yang diketahui benar. Ketika BPJS mengubah tarif (biasanya diumumkan dalam Peraturan Pemerintah), kamu seharusnya bisa memperbarui sistemmu di satu tempat dengan percaya diri.
Istilah kunci: BPJS Ketenagakerjaan, BPJS Kesehatan, JHT, JP, JKK, JKM, JKP, PKS, SIPP Online, EPS, HMAC-SHA256, PCare, VClaim
JHTJPJKPPKSSIPP OnlineHMAC-SHA256