Integrasi API BPJS untuk Developer Indonesia: Panduan Praktis

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. Saya sudah mengerjakan integrasi BPJS di Commsult Indonesia, dan pengalaman itu mengajarkan saya bahwa dokumentasi resmi dan perilaku API yang sebenarnya cukup berbeda sehingga layak mendapat panduan praktis.

Ikhtisar BPJS: Yang Perlu Diketahui Developer

Ada dua sistem BPJS yang terpisah: BPJS Ketenagakerjaan (sebelumnya Jamsostek) mencakup asuransi kecelakaan kerja (JKK), asuransi kematian (JKM), tabungan hari tua (JHT), dan pensiun (JP). 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.

Arsitektur API BPJS Ketenagakerjaan

API BPJS Ketenagakerjaan menggunakan arsitektur berbasis REST dengan autentikasi tanda tangan HMAC-SHA256. Kamu membutuhkan: Consumer ID (Cons ID) yang diterbitkan oleh BPJS; Secret Key untuk menandatangani permintaan; dan User Key untuk akses layanan tertentu (ini berbeda per jenis integrasi). Lingkungan pengembangan tersedia di api-dev.bpjsketenagakerjaan.go.id. Lingkungan produksi membutuhkan proses pendaftaran formal melalui portal e-procurement BPJS. Library yang dikontribusikan komunitas ada untuk Node.js (library @ssecd/jkn di GitHub mendukung Node.js, Deno, dan Bun) dan PHP (contoh berbasis curl di GitHub). Tidak ada SDK resmi yang dikelola oleh BPJS.

API PCare dan VClaim BPJS Kesehatan

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). URL basis API baru adalah new-api.bpjs-kesehatan.go.id/pcare-rest-v3.0 untuk PCare v3. Integrasi membutuhkan kemitraan formal dengan BPJS Kesehatan — kamu tidak bisa mengakses API produksi tanpa perjanjian kerja sama yang ditandatangani (PKS — Perjanjian Kerja Sama).

// 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 (2025 rates)
function calcBpjsContributions(gaji: number) {
  const capJP  = 9_077_600
  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,
    kes_employer:  Math.min(gaji, capKes) * 0.04,
    kes_employee:  Math.min(gaji, capKes) * 0.01,
  }
}
        

Logika Perhitungan Kontribusi

Sebelum kamu bisa berintegrasi dengan API BPJS, kamu perlu menghitung kontribusi dengan benar. Tarif kontribusi 2025 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 IDR 9.077.600). Untuk BPJS Kesehatan: 5% dari gaji (4% pemberi kerja + 1% karyawan, gaji dibatasi IDR 12 juta untuk perhitungan premi). Perhitungan ini mudah diimplementasikan tapi harus cocok persis dengan perhitungan BPJS sendiri — perbedaan akan menyebabkan penolakan pelaporan.

Pola Integrasi untuk Sistem ERP

Dua pola integrasi utama untuk BPJS dalam sistem ERP adalah: (1) Pelaporan batch bulanan — hitung semua kontribusi karyawan untuk bulan tersebut, buat file pelaporan BPJS (biasanya file teks atau Excel berformat yang diterima portal BPJS), dan submit. Ini tidak membutuhkan integrasi API langsung dan cukup untuk sebagian besar perusahaan mid-market. (2) Pengecekan eligibilitas real-time — untuk portal HR di mana karyawan ingin memverifikasi status BPJS mereka, panggilan API langsung ke layanan pengecekan saldo BPJS Ketenagakerjaan mengembalikan saldo JHT real-time. Ini membutuhkan integrasi API penuh dengan Cons ID dan Secret Key.

# BPJS Integration Patterns

## Pattern 1: Batch Monthly Reporting (most common)
1. Calculate contributions for all employees at month-end
2. Generate BPJS reporting file (formatted text / Excel)
3. Upload via BPJS portal (no live API required)
4. Store submission receipt in ERP for audit trail

## Pattern 2: Real-time JHT Balance Check (live API)
GET https://api-dev.bpjsketenagakerjaan.go.id/telpuhrd/...
Headers: X-cons-id, X-timestamp, X-signature
Response: { "kpj": "...", "saldo": 12500000, "status": "active" }

## Pattern 3: PPOB Aggregator (no PKS required)
POST https://api.iak.id/api/v1/postpaid/pay
Body: { "product_code": "BPJSTK", "customer_id": "KPJ_NUMBER" }
# Charges per-transaction fee (~IDR 2,500–5,000)
# No direct BPJS partnership needed
        

Autentikasi HMAC BPJS Ketenagakerjaan di Node.js

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.

Layanan Integrasi BPJS Pihak Ketiga

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 dan pembayaran BPJS Ketenagakerjaan sebagai produk pascabayar melalui API agregator PPOB (payment point online bank) mereka. Ini biasanya digunakan oleh aplikasi pembayaran dan platform HR SaaS untuk memeriksa status kontribusi BPJS tanpa kemitraan BPJS langsung. Trade-offnya: kamu membayar biaya per transaksi ke agregator, dan kamu bergantung pada uptime dan akurasi data pihak ketiga.

Membangun Integrasi BPJS yang Maintainable

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.

Sumber & Bacaan Lanjutan

• BPJS Ketenagakerjaan — Development API Portal — https://api-dev.bpjsketenagakerjaan.go.id/
• ssecd/jkn — BPJS JKN Node.js Library — https://github.com/ssecd/jkn
• IAK API — BPJS Ketenagakerjaan Postpaid Integration — https://api.iak.id/api/postpaid/core/products/bpjs-ketenagakerjaan/_dir