Integrating BPJS VClaim with SIMRS is a crucial step for hospital operational efficiency. This article will guide you through the technical aspects, from basic concepts to code implementation, to create an integrated and responsive system. Learn how to optimize workflows and reduce manual errors.
In the Indonesian healthcare service ecosystem, the operational efficiency of hospitals and clinics depends heavily on integrated information systems. One of the biggest challenges is the management of BPJS Kesehatan claims, which often takes time, is prone to manual errors, and hampers the speed of patient services. A claim verification process (VClaim) that is not automated can cause long queues, delay in issuing the Participant Eligibility Letter (SEP), and even potential financial losses due to rejected claims. Imagine a scenario where staff must repeatedly enter patient data manually from SIMRS into a separate VClaim application, or face difficulties in tracking claim status. This situation not only burdens staff but also lowers the quality of the patient experience. This article serves as a comprehensive guide for hospital IT managers, clinic owners, operations managers, and decision makers who want to overcome this problem. We will deeply dissect how to integrate BPJS VClaim directly into your Hospital Management Information System (SIMRS), from understanding basic concepts, technical preparation, implementation code examples, to error handling and best practices. Our goal is to provide practical, in-depth, and actionable solutions so that you can build a more efficient, accurate, and standards-compliant system.
Basic Concepts of BPJS VClaim & SIMRS Integration
Integrating BPJS VClaim with SIMRS is not merely connecting two systems; it creates a seamless data bridge to automate the claim verification and issuance process. VClaim (Electronic Claim Verification) is a system developed by BPJS Kesehatan to facilitate the electronic submission and verification of claims, in order to ensure that every health service provided to BPJS participants complies with their provisions and rights. Without integration, hospital staff must use a separate VClaim application or web portal, entering data that already exists in SIMRS manually, an inefficient process that is highly prone to data entry errors (typo).
The main benefits of this integration are very significant. First, operational efficiency. The patient registration process and SEP issuance can be done instantly from SIMRS, reducing patient waiting time by up to 70% and freeing staff to focus on more important services. Second, data accuracy. By minimizing duplicate data entry, the risk of data errors that can cause claims to be rejected is drastically reduced. Patient data that has been validated in SIMRS is directly used for VClaim. Third, better decision-making. Integrated claim data allows management to analyze service patterns, claim efficiency, and compliance with BPJS regulations more accurately and in real-time. Fourth, regulatory compliance. Integration helps ensure that every step in the claim process complies with Minister of Health Regulations (PMK) related to BPJS Kesehatan, such as PMK No. 3 of 2023 concerning Health Service Tariff Standards in the Implementation of the Health Insurance Program, and the latest VClaim technical guidelines from BPJS Kesehatan.
The key components involved in this integration include: SIMRS Database that stores patient data, medical history, and administrative information; BPJS Kesehatan VClaim API that provides endpoint for various functions such as participant search, SEP creation, and data updates; and Bridging Module in SIMRS that acts as a connector and data translator between SIMRS and the VClaim API. The data flow generally starts when a patient registers at SIMRS. SIMRS will send patient data to the VClaim API for participant verification. Once valid, SIMRS will call the SEP creation API, and the generated SEP number will be stored back into SIMRS. This entire process must be secured with authentication and encryption mechanisms determined by BPJS Kesehatan, such as the use of Consumer ID, Consumer Secret, Timestamp, and Signature based on HMAC-SHA256.
As a concrete example, imagine a BPJS patient comes to the hospital. Without integration, the registration officer must search for patient data in SIMRS, then open the VClaim application, enter the BPJS card number, service date, and other data manually. If there is an error, the process must be repeated. With integration, the officer simply searches for the patient in SIMRS. When the patient data is found, SIMRS will automatically call the VClaim API to verify participant active status and retrieve referral data (if any). After verification succeeds, SIMRS will display a partially filled SEP form, and with one click, the SEP will be created through the VClaim API and its number will be directly stored in SIMRS. A process that previously took 5-10 minutes per patient can now be completed in less than 1 minute. This is real efficiency and directly impacts the patient experience and staff workload.
Preparation & Technical Implementation Details
Before starting the technical implementation of BPJS VClaim integration, there are several essential preparations that must be met to ensure the smooth running of the project. First and foremost, you must have an active VClaim account provided by BPJS Kesehatan for your healthcare facility (PPK). This account will be equipped with Consumer ID, Consumer Secret, PPK Code, and Application Code. Make sure you store these credentials securely and do not share them carelessly. Second, your SIMRS must support custom development or have a modifiable module for API integration. Most modern SIMRS built with technologies such as Laravel 11.x (PHP), Node.js 20 LTS, or Java Spring Boot, usually have this capability. Ensure your development team is familiar with the framework used and has full access to the SIMRS source code.
Third, a solid database infrastructure is very important. VClaim integration will involve storing SEP numbers, referral data, and claim status in your SIMRS database. We recommend using a relational database such as PostgreSQL 16.x or MySQL 8.x that is known for its stability and scalability. Make sure your SIMRS database schema can accommodate new columns relevant to VClaim data, such as `no_sep`, `tgl_sep`, `kode_rujukan`, `poli_tujuan_sep`, and others. Fourth, an in-depth understanding of RESTful API concepts, JSON data format, and security mechanisms such as HMAC-SHA256 encryption is a technical prerequisite for developers. The official VClaim API documentation from BPJS Kesehatan (frequently updated, make sure you use the latest version, for example version 1.1) is the main reference that must be studied.
Architecturally, your SIMRS backend will act as an API client that sends requests to the VClaim API endpoint of BPJS Kesehatan. The bridging module in SIMRS is responsible for: (1) Collecting data from SIMRS (for example, BPJS card number, service date). (2) Building the appropriate request header (Consumer ID, Timestamp, Signature). (3) Sending HTTP requests (GET/POST/PUT) to the VClaim API. (4) Receiving responses from VClaim. (5) Decrypting responses (if needed). (6) Processing and saving response data to the SIMRS database or displaying it in the user interface. The data mapping process between columns in SIMRS and the parameters required by the VClaim API is a crucial step. For example, the `jenis_kelamin` column in SIMRS may need to be converted to 'L' or 'P' according to the VClaim format.
Some main VClaim APIs that are generally integrated include: GET /peserta/{nokartu}/{tglpelayanan} for searching participant data and membership status; POST /sep/insert to create a new SEP; PUT /sep/update to update SEP data; GET /sep/{nosep} to search for SEP details based on SEP number; and GET /Rujukan/List/Peserta/{nokartu} to retrieve a list of participant referrals. The security aspect is the foundation. Every request to the VClaim API requires a special header: X-Cons-ID (your Consumer ID), X-Timestamp (Unix timestamp when the request is made), and X-Signature. This signature is generated from a combination of your Consumer ID, Timestamp, and Consumer Secret using the HMAC-SHA256 algorithm, then encrypted with Base64. Responses from VClaim are also often encrypted and need to be decrypted on the SIMRS side using the same encryption key as the Consumer Secret. Ensuring this security implementation is correct is key to preventing unauthorized access and maintaining data integrity.
Implementation Code Example
This section will present a concrete code example in PHP, specifically with the Laravel 11.x framework, which is often used in SIMRS development. This code will show how to generate the signature required for every VClaim API request and how to make a simple API call to get participant data.
Code Block 1: Function to Generate VClaim Security Headers
<?php namespace AppServicesBpjs; use CarbonCarbon; class VclaimService { protected $consId; protected $secretKey; protected $baseUrl; public function __construct() { $this->consId = env('BPJS_VCLAIM_CONS_ID'); $this->secretKey = env('BPJS_VCLAIM_SECRET_KEY'); $this->baseUrl = env('BPJS_VCLAIM_BASE_URL', 'https:apijkn.bpjs-kesehatan.go.id/vclaim-kemenkes/'); } protected function generateHeaders() { $timestamp = CarbonCarbon::now()->timestamp; // Unix timestamp $data = $this->consId . '&' . $timestamp; $signature = hash_hmac('sha256', $data, $this->secretKey, true); $encodedSignature = base64_encode($signature); return [ 'X-Cons-ID' => $this->consId, 'X-Timestamp' => $timestamp, 'X-Signature' => $encodedSignature, 'user_key' => env('BPJS_VCLAIM_USER_KEY') // Jika diperlukan, misal untuk VClaim versi tertentu ]; } public function decrypt($string) { $key = $this->consId . $this->secretKey . $this->consId; $encrypt_method = 'AES-256-CBC'; // Standard BPJS encryption method $key_hash = hex2bin(hash('sha256', $key)); $iv = substr(hex2bin(hash('sha256', $key)), 0, 16); $output = openssl_decrypt(base64_decode($string), $encrypt_method, $key_hash, OPENSSL_RAW_DATA, $iv); return unction_exists('gzuncompress') ? gzuncompress($output) : $output; } // ... fungsi lain untuk panggilan API ... }Explanation of Code Block 1: The `generateHeaders()` function is the core of secure communication with the VClaim API. It retrieves the Consumer ID and Secret Key from environment variables (`.env` file), generates the current timestamp, then combines the Consumer ID and timestamp to create a data string. This data string is then hashed using the HMAC-SHA256 algorithm with the Secret Key as the key, and the result is encoded with Base64 to become `X-Signature`. The `decrypt()` function is used to decrypt responses from VClaim, which are often encrypted using the AES-256-CBC method. The decryption key is created from a combination of the Consumer ID and Secret Key, according to BPJS specifications. It is important to ensure that `BPJS_VCLAIM_CONS_ID`, `BPJS_VCLAIM_SECRET_KEY`, and `BPJS_VCLAIM_USER_KEY` are already defined in your `.env` file.
Code Block 2: Making an API Call to Retrieve Participant Data
<?php namespace AppServicesBpjs; use GuzzleHttpClient; class VclaimService { // ... (property dan generateHeaders() & decrypt() dari code block sebelumnya) ... public function getPeserta($noKartu, $tglPelayanan) { $headers = $this->generateHeaders(); try { $client = new Client(['base_uri' => $this->baseUrl]); $response = $client->request('GET', 'Peserta/nokartu/' . $noKartu . '/tglpelayanan/' . $tglPelayanan, [ 'headers' => $headers, 'verify' => false // Sesuaikan dengan konfigurasi SSL Anda, sebaiknya true di production ]); $body = json_decode($response->getBody()->getContents(), true); if ($body['metaData']['code'] == 200) { $decryptedResponse = json_decode($this->decrypt($body['response']), true); return [ 'status' => true, 'data' => $decryptedResponse ]; } else { return [ 'status' => false, 'message' => $body['metaData']['message'] ]; } } catch ( hrowable $e) { // Log the error for debugging logger()->error('VClaim API Error: ' . $e->getMessage(), ['exception' => $e]); return [ 'status' => false, 'message' => 'Terjadi kesalahan saat memanggil API VClaim: ' . $e->getMessage() ]; } } }Explanation of Code Block 2: The `getPeserta()` function shows how to call the VClaim API endpoint `Peserta/nokartu/{nokartu}/tglpelayanan/{tglpelayanan}`. It uses the Guzzle HTTP Client (version 7.x recommended) to make a GET request. The security headers generated by `generateHeaders()` are included in the request. After receiving the response, the code checks `metaData.code`. If 200 (success), the response is decrypted using the previously created `decrypt()` function, then decoded from JSON. It is important to handle cases where the `metaData.code` response is not 200, which indicates a problem on the VClaim side. A `try-catch` block is also included to handle network exceptions or other errors that may occur during the API call. For production environments, ensure that `verify` in Guzzle is set to `true` for proper SSL validation, or configure your CA certificate correctly.
Data & Error Handling
Strong API integration is not only about sending requests and receiving responses, but also about how your system handles incoming data and, most importantly, how it responds when errors occur. Proper data handling ensures that information is stored accurately and consistently, while effective error handling prevents system failures and provides a better user experience.
Example JSON Payload for SEP Creation (POST /sep/insert)
The following is an example JSON payload commonly used for SEP creation through the POST /sep/insert endpoint. This payload is sent in encrypted form according to VClaim specifications, but the data structure is approximately as follows:
{ "request": { "t_sep": { "noKartu": "0001234567890", "tglSep": "2025-01-15", "ppkPelayanan": "1234567", "jnsPelayanan": "2", "klsRawat": "3", "noMR": "MR-001", "rujukan": { "asalRujukan": "1", "tglRujukan": "2025-01-10", "noRujukan": "1234567890123", "ppkRujukan": "1234567" }, "catatan": "Kontrol rutin", "diagAwal": "A01.0", "poli": { "tujuan": "INT", "eksekutif": "0" }, "cob": "0", "katarak": "0", "jaminan": { "lakaLantas": "0", "penjamin": { "penjamin": "1", "noHP": "08123456789" } }, "skdp": { "noSurat": "SKDP-001", "kodeDPJP": "12345" }, "noTelp": "08123456789", "user": "admin" } } }After the SEP is successfully created, store the SEP number returned by VClaim in your SIMRS database and display a confirmation to the officer. Also be sure to log the raw response (before decryption) to facilitate audits if a claim dispute occurs in the future.
Practical Tips for Implementation in the Field
First, always use a retry with backoff mechanism for VClaim API calls. The network to the BPJS server may experience temporary disruptions, and a momentary failure does not mean the data is invalid. Implement a maximum of 3 retry attempts with escalating delays (for example, 2, 4, and 8 seconds) before showing an error message to the user. Avoid excessive retries that could actually trigger blocking from the BPJS server.
Second, separate credentials and configuration (cons ID, secret key, user key, base URL) into a .env file or environment variable; do not hardcode them in the code. Also use sandbox mode first for testing before switching to production. Store the timestamp of every request and response for debugging purposes, but never store complete patient personal data in logs for privacy compliance.
Third, perform double validation on the SIMRS side before sending data to VClaim. Ensure the card number, service date, diagnosis code (ICD-10), and polyclinic code are in the correct format. Small errors such as date format or unregistered codes are often the main cause of error responses from VClaim. In addition, create a simple monitoring dashboard that displays the daily integration success status so the IT team can quickly detect anomalies.
FAQ
Does VClaim integration require specific encryption?
Yes. The latest version of VClaim generally uses AES-256 encryption with CBC mode and HMAC-SHA256 for signature. You must follow the technical specifications issued by BPJS, including the generation of X-cons-id, X-timestamp, X-signature, and X-authorization. Do not change the order or format of headers because this will cause a 401 or 403 response.
What if the VClaim response returns a code other than 200?
Check the message in metaData.message. Code 201 usually means data not found, 400 means invalid parameter, and 500 indicates a disruption on the BPJS server side. Handle each code with an informative message to the user, and log response details for further analysis. Do not display raw messages from the server to staff to avoid confusion.
Can SEP data be changed after it is successfully created?
It can, but only to a limited extent. Some fields such as discharge date, final diagnosis, and service type can be updated via the SEP update endpoint. However, the SEP number and card number generally cannot be changed. Always update before the claim closing date to avoid rejection by the BPJS verifier.
How long does this integration take?
For a team already familiar with REST API and encryption, basic integration can be completed in 1-2 weeks. However, for full production with error handling, logging, and end-to-end testing, allocate 3-4 weeks to be safer and more stable.
Conclusion
Integrating BPJS VClaim with SIMRS is not merely a technical matter of calling an API, but involves compliance, data security, and the smooth operation of the hospital. By understanding the authentication flow, encryption, error handling, and applying the practical tips above, you can build a reliable integration with minimal disruptions. Ensure every API version change is followed by thorough testing so that claim services continue to run without obstacles.
If your IT team faces obstacles in implementation, security audit, or wants to ensure the integration runs according to BPJS standards, do not hesitate to consult with us. We are ready to help from architecture design, VClaim module development, to go-live assistance. Contact our team now to get a solution tailored to your SIMRS needs.
This article is part of the education by Nugroho Setiawan, IT consultant in Jogja. Related solutions: SIMRS SIM Klinik Integrator Bridging BPJS & SatuSehat. Need free consultation?
Komentar
Belum ada komentar. Jadilah yang pertama!
Saya membantu konsultasi IT, pengembangan aplikasi, dan visualisasi data untuk rumah sakit, klinik, dan bisnis di Yogyakarta (DIY), Magelang, dan sekitarnya.