Bridging Bpjs Laravel Package

Technical Evaluation

Architecture fit. virusphp/bridging-bpjs is a Laravel-style integration package that wraps two Indonesian national health-insurance APIs: BPJS Kesehatan VClaim V2 (membership eligibility, SEP issuance, referrals, reference data, monitoring) and Antrol V2 (outpatient queue/booking). Its distinguishing feature is the V2 wire format: payloads are encrypted, then compressed with an LZ-String implementation, then transported. That is the core value proposition — the package hides a non-obvious, easy-to-get-wrong crypto/compression handshake behind a familiar Laravel service-provider/config façade. For a Laravel shop building a hospital SIMRS/RME integration, this is a natural architectural fit: config-driven credentials, an injectable client, and Eloquent/queue-friendly call sites. For a non-Laravel or service-oriented PHP stack it is a poorer fit — expect to lift the crypto layer out and discard the framework glue.

Integration feasibility. High on mechanics, low on certainty. Composer install plus a published config file with consumerID / secretKey / userKey (VClaim) and separate Antrol credentials gets you to a first request quickly. The gating item is not code — it is credential provisioning: BPJS issues per-facility credentials through the local kantor cabang, often with a staging environment first. Budget calendar time for that, not engineering time.

Technical risk. This is the crux. The package has ~41 stars, an MIT license, a single apparent maintainer, and sits in a regulated, patient-safety-adjacent, financially material domain. Risks, ranked:

1. Correctness of the crypto/compression layer. LZ-String is a JavaScript library; PHP ports diverge on Unicode, surrogate pairs, and edge-case dictionaries. A near-miss produces requests BPJS rejects with unhelpful errors, or worse, silently truncated payloads. This must be validated against BPJS's own reference implementation, not just the package's tests.
2. Key derivation and clock sensitivity. V2 derives per-request keys from a timestamp and the secret key. Server clock skew, NTP drift, or a container with a stale clock becomes an intermittent, hard-to-reproduce outage.
3. Bus factor. One maintainer, small community, no published SLA. BPJS changes its contract on its own schedule; the package may lag.
4. Test coverage and PHI handling. Unknown whether the suite covers failure paths, and whether request/response logging can inadvertently persist national ID numbers and diagnoses. Under Indonesian PDP Law (UU PDP) that is a reportable-incident risk, not a code-style nit.
5. Vendor lock at the wrong layer. If controllers call the package facade directly, swapping to an in-house client during a BPJS breaking change becomes a refactor under incident pressure.

Key questions to put to the maintainer / internal spike.

• Which VClaim V2 endpoint groups are covered (Peserta, SEP, Rujukan, Referensi, Monitoring) and which Antrol V2 operations?
• Which LZ-String PHP port is vendored, and has it been diff-tested against the JS reference on multi-byte and emoji-bearing payloads?
• Is key derivation (timestamp + secret) implemented per BPJS spec, and is clock skew handled or surfaced?
• What is the automated test story — unit only, or contract tests against a BPJS sandbox?
• Does the package support Laravel 9/10/11 and PHP 8.1+, and what is the declared support window?
• Are credentials read from config only, or is there a path to a secrets manager?
• How are BPJS response codes and error metadata surfaced — raw arrays or typed exceptions?
• Is there any idempotency guidance for SEP creation and Antrol booking (the two operations where a retry creates a duplicate)?

Integration Approach

Stack fit. Laravel 10/11, PHP 8.1+, ext-openssl and ext-json, Guzzle/Laravel HTTP underneath. Nothing exotic; it will run in standard queue workers and scheduled commands, which matters because reference-data sync and Antrol polling belong in jobs, not in the request cycle.

Wrapping is mandatory. Do not let controllers touch the package directly. Define a narrow internal port — EligibilityChecker, SepIssuer, ReferralReader, QueueBooker — and implement it with an adapter over virusphp/bridging-bpjs. This costs roughly a day and converts a future BPJS breaking change or package abandonment from an incident into a swap. It also gives you one place to enforce audit logging, redaction, retry policy, and idempotency keys.

Migration path (V1 → V2). V1 is effectively legacy; V2's encryption requirement is the migration's whole difficulty, and that is precisely what this package absorbs. Run V1 and V2 adapters behind the same port, route by feature flag per facility, and shadow-compare eligibility/SEP responses in staging before cutting over. Treat the V1 code path as a rollback lever for one release cycle, then delete it.

Compatibility checkpoints before committing. Pin the package to a tagged release; verify the composer.json constraints against your Laravel and PHP versions; confirm no global helper/function collisions; confirm the service provider is auto-discovered or explicitly registerable; verify the config file publishes cleanly and that credentials can be injected from env/vault rather than committed.

Sequencing.

1. Week 0 — Access. Request BPJS staging credentials for one pilot facility. This is the critical path; start it before writing code.
2. Week 1 — Crypto PoC. Stand up the package, hit one trivial endpoint (referensi/kode diagnosa), and independently verify the encrypted request against a reference implementation. Do not proceed until this passes.
3. Week 2 — Adapter + eligibility + SEP. Highest clinical value, highest risk; build audit logging and idempotency here.
4. Week 3 — Reference data sync and monitoring, as scheduled jobs with cached outputs.
5. Week 4 — Antrol (separate auth, separate failure domain), then observability dashboards and alerting.
6. Week 5+ — Facility-by-facility cutover behind feature flags, one branch at a time.

Operational Impact

Maintenance. Assume you own this code. Budget ~10–15% of one backend engineer's capacity for dependency updates, BPJS contract changes, and upstream triage; more in the quarter BPJS ships a V2 revision. Mitigations: pin the version, mirror the repo internally, and keep the adapter thin enough that a fork is a weekend, not a project. Watch the repo's release cadence as a leading indicator — a stall of more than two quarters is your signal to fork preemptively.

Support. There is no commercial SLA. Support splits into three tiers you must staff separately: (a) package-level bugs — internal, since the community is tiny; (b) BPJS API behavior and credential issues — BPJS helpdesk, with response times outside your control; (c) hospital operational incidents ("patient can't be registered") — your on-call. Because hospitals run 24/7 and emergency registration cannot wait, define an explicit degraded-mode policy up front: what staff do when eligibility or SEP issuance is unavailable (manual/offline SEP with reconciliation), and how reconciliation is audited afterward. This is a policy decision, not an engineering one, and it needs clinical operations sign-off.

Scaling. Throughput is dominated by BPJS-side rate limits and latency, not by this package. Design accordingly: async jobs for anything not on the registration critical path, bounded concurrency, exponential backoff with jitter, and aggressive caching of reference data (diagnoses, procedures, facility lists, doctor schedules) that changes rarely. Antrol booking needs a queue to serialize per-poli slot contention. None of this is expensive; all of it is easy to omit.

Failure modes to instrument explicitly.

• Decryption/compression mismatch → verify a known-good payload at boot/healthcheck, not just on first patient.
• Clock skew → alert when host time drifts from NTP beyond a few seconds; timestamp-derived keys fail silently otherwise.
• Credential expiry / token invalidation → pre-expiry alerting.
• BPJS-side outage or latency spike → circuit breaker with a fast, explicit degraded path rather than 30-second timeouts at the registration desk.
• Duplicate SEP or duplicate Antrol booking from retries → idempotency keys plus a reconciliation report.
• Secret leakage into logs or exception traces → structured logging with field-level redaction, reviewed before go-live.
• Unicode payload corruption → a test fixture with Indonesian names containing diacritics and long compound names.

Ramp-up. A competent Laravel engineer reaches productive use of the package in 1–2 days; the crypto layer is opaque but the call sites are conventional. The real ramp is domain fluency — 3–5 weeks: SEP semantics, referral chains and their validity windows, kode diagnosa rules, Antrol slot lifecycles, and the specific rejection codes BPJS returns. Pair that engineering ramp with a BPJS-literate business analyst or a hospital billing/registration SME, or the team will build the wrong workflows correctly. Add a half-day of runbook training for registration staff and helpdesk on the degraded mode before cutover.