Download the PHP package mdestafadilah/satusehat-sdk without Composer

SATUSEHAT SDK untuk PHP

API wrapper tidak resmi untuk integrasi dengan platform SATUSEHAT (Kementerian Kesehatan RI).
FHIR R4 · Consent · KFA · KYC · OAuth2

composer require mdestafadilah/satusehat-sdk

Tentang Proyek • Sumber Kode • PR #13 • Catatan • Fitur • Instalasi • Mulai Cepat • Konfigurasi • Partial Update • Paging • KYC • Logging • Token Caching • Pengujian • Lisensi

Tentang Proyek

mdestafadilah/satusehat-sdk adalah pustaka PHP (tanpa framework) untuk berbicara dengan platform SATUSEHAT milik Kementerian Kesehatan RI. Paket ini adalah fork dari agumil/satusehat-sdk. Pustaka ini membungkus lima kelompok API yang dipakai faskes sehari-hari:

Semua modul berbagi satu token dan satu mekanisme transport, sehingga retry, timeout, logging, dan penyamaran data pasien berlaku seragam di seluruh permukaan API.

Repo ini adalah fork dari proyek asal. Isinya bukan sekadar salinan: seluruh perubahan pada PR #13 sudah masuk, ditambah perbaikan dokumentasi ini. Rincian asal-usul kode ada di Sumber Kode.

Sumber Kode

PR #13 berstatus terbuka (belum di-merge) saat README ini ditulis: 89 berkas berubah, +5.551 / −281 baris, dikerjakan oleh mdestafadilah. Versi yang berisi seluruh perbaikan di bawah dirilis di Packagist dengan nama mdestafadilah/satusehat-sdk — lihat Instalasi.

Apa yang Dibawa PR #13

PR ini mengubah SDK dari "pembungkus HTTP" menjadi pustaka yang layak dipakai di fasilitas kesehatan. Ringkasannya:

Catatan

Paket ini masih dalam pengembangan. Dokumentasi terbatas dan beberapa komponen belum lengkap. Uji dulu di environment development sebelum menyentuh produksi.

Fitur Utama

• Payload Builder — susun payload senyata mungkin dengan builder; tidak suka? Boleh diabaikan dan kirim array biasa.
• Sederhana — dependensi seminimal mungkin; kelas resource mengikuti standar HL7 FHIR.
• Fleksibel — tidak terikat framework tertentu; payload bisa dikirim dengan gaya apa pun sesuai proyek Anda.
• Tangguh secara default — retry otomatis untuk 429/5xx dengan Retry-After dan exponential backoff; hanya method idempoten yang diulang.
• Aman secara default — ID resource divalidasi sebelum masuk URL, dan PHI disamarkan sebelum menyentuh log.
• Helper praktis — BundlePager untuk menelusuri halaman FHIR, FileTokenStore agar worker PHP-FPM berbagi satu access token.

Kebutuhan Sistem

Guzzle 6 tidak lagi didukung: sudah EOL dan punya advisory tanpa perbaikan. Guzzle 8 juga belum didukung karena memerlukan psr7 3 dan promises 3 — migrasi tersendiri.

Instalasi

Bila hanya butuh versi upstream apa adanya:

Untuk mengikuti branch main tanpa menunggu rilis (mis. ingin ikut perubahan yang belum di-tag):

Atau langsung di composer.json:

Simpan kredensial di .env:

SATUSEHAT_ENV menentukan host untuk seluruh modul (FHIR, Consent, KFA, KYC, dan OAuth2): development → api-satusehat-dev.dto.kemkes.go.id, staging → api-satusehat-stg.dto.kemkes.go.id, production → api-satusehat.kemkes.go.id. Nilai .env didahulukan; parameter 'environment' pada config hanya dipakai bila .env tidak diisi.

Catatan Logging bersifat opsional. SDK hanya bergantung pada psr/log (antarmuka saja) dan tidak menulis apa pun kecuali Anda memberikan instance logger. Logger PSR-3 apa pun bisa dipakai — composer require monolog/monolog bila belum ada.

Mulai Cepat

Dengan PHPDOTENV:

Tanpa PHPDOTENV:

Host ditentukan oleh environment, bukan oleh URL yang Anda masukkan. Tidak ada kunci base_url: bila URL bisa diatur pemanggil, satu payload yang salah dapat mengarahkan Bearer token ke host lain (SSRF).

Contoh lain yang siap dijalankan ada di direktori examples/ (bootstrap.php memuat autoloader dan .env).

Konfigurasi

Argumen kedua SSClient diteruskan ke setiap request. Semua kunci opsional dan nilai default-nya aman dipakai apa adanya.

Perilaku Retry

Request hanya diulang bila dua syarat terpenuhi:

1. Status respons 429, 500, 502, 503, atau 504.
2. Method HTTP terdaftar di retry_methods.

4xx lain (400, 401, 403, 404) tidak pernah diulang karena pengulangannya menghasilkan jawaban yang sama. POST dikecualikan secara default: bila request pertama sebenarnya berhasil tetapi responsnya hilang, mengulang akan membuat resource tercatat dua kali. Tambahkan 'POST' ke retry_methods hanya bila endpoint Anda memang aman diduplikasi.

Bila server mengirim header Retry-After, nilainya dihormati (dibatasi 60 detik). Jika tidak, SDK menunggu retry_base_delay_ms * 2^(attempt - 1) dengan jitter, tidak melebihi retry_max_delay_ms. Setelah retry_attempts habis, respons terakhir dikembalikan apa adanya — tidak diubah menjadi exception, sehingga $response->getHttpCode() dan $response->getErrorMessages() tetap bisa dipakai.

Partial Update

createPatient() selalu mengirim seluruh resource. Untuk mengubah satu field tanpa mengirim ulang semuanya, gunakan updatePatient() yang mengirim dokumen JSON Patch (RFC 6902):

SATUSEHAT saat ini hanya menerima operasi replace. Beberapa operasi boleh dikirim dalam satu array, dan setiap path relatif terhadap akar resource (misalnya /name/0/text). Contoh lengkap: examples/FHIR/Patient/patch.php.

Paging

Pencarian FHIR mengembalikan Bundle yang link.next-nya berisi _page_token buram. Anda tidak bisa menghitung halaman berikutnya sendiri — parameternya harus dikirim ulang dari link tersebut. BundlePager mengerjakannya untuk Anda:

next() mengembalikan null saat tidak ada halaman berikutnya. Ia juga berhenti ketika request gagal, atau ketika server mengembalikan link yang sama dua kali (pengaman terhadap loop tanpa akhir). Argumen ketiga yang opsional membatasi jumlah halaman, default 1000.

BundleHelper berguna sendiri saat Anda sudah punya Bundle ter-decode:

KYC

KYC (verifikasi NIK) punya base URL sendiri (/kyc/v1) dengan Bearer token yang sama, jadi ia dipakai lewat client terpisah: SSClientKYC.

Alurnya tiga langkah, dan SDK hanya mengerjakan dua di antaranya — enkripsi dan dekripsi tetap di sisi aplikasi karena kuncinya dipegang faskes:

1. Enkripsi pesan permintaan memakai kunci publik dari Kemkes (di luar SDK).
2. generateUrl() menukar pesan terenkripsi itu dengan sesi KYC. Responsnya masih ciphertext; dekripsikan untuk mengambil url_token.
3. generateChallengeCode() atau requestPerNik() meminta challenge code memakai url_token tersebut.

Beberapa hal yang perlu diketahui:

• $urlToken dikirim sebagai header X-Frame-Token. SDK tidak menyimpannya, jadi ambil dari respons generate-url() lalu teruskan sendiri.
• $debugMode = true menambahkan X-Debug-Mode: 1 supaya challenge code dikembalikan langsung tanpa widget KYC. Pakai hanya di development/staging: mode ini melewati verifikasi yang seharusnya dilakukan pasien, jadi SDK menolaknya sendiri (SSEnvException) bila environment-nya production — request tidak dikirim sama sekali.
• NIK diperiksa 16 digit sebelum dikirim, karena respons memuat ihs_number milik NIK tersebut — salah ketik berarti challenge code untuk orang lain.
• Lingkungan mengikuti SATUSEHAT_ENV (.env didahulukan) atau 'environment' pada config. Nilai yang sah: development, staging, production — sama seperti modul lain.

Contoh: examples/KYC/request_per_nik.php.

Logging

Berikan logger PSR-3 apa pun dan setiap pertukaran HTTP akan dicatat. Data pasien disamarkan lebih dulu, sehingga identifier, nama, tanggal lahir, alamat, dan kontak tidak pernah sampai ke berkas log Anda.

Yang dicatat:

Query string dan body JSON dilewatkan ke PhiRedactor, yang bekerja secara default-deny: setiap nilai diganti [REDACTED] dan hanya nama kunci, sejumlah kecil field struktural (resourceType, status), serta parameter paging (_count, _offset, ...) yang bertahan. Menyamarkan daftar kunci "sensitif" tidak cukup untuk FHIR, karena identitas juga berada di tempat yang nama kuncinya tampak lugu — subject.display, text.div, dan note.text semuanya pernah membawa nama dan NIK pasien pada versi sebelumnya. ID resource di path URL (/Patient/100000030009) disamarkan karena alasan yang sama. Pertahankan level logger di DEBUG hanya di mesin development — payload yang sudah disamarkan pun tetap membocorkan volume request dan jenis resource.

Token Caching

Secara default access token hidup di memori, per instance Oauth2. Di bawah PHP-FPM itu berarti satu request token per worker, dan setiap worker terus menanggung latensi tersebut sampai token kedaluwarsa.

FileTokenStore membagi satu token antar proses:

Berkas ditulis dengan permission 0600 memakai pola temp-file-plus-rename yang atomik, sehingga pembaca tidak pernah melihat token setengah tertulis. Mode tersebut kemudian diverifikasi dengan fileperms(), karena chmod() melaporkan sukses bahkan pada filesystem yang tidak bisa menerapkan permission POSIX (FAT/vfat, sebagian network share); dalam kasus itu penulisan gagal dengan suara keras alih-alih meninggalkan kredensial yang bisa dibaca. Penyegaran berjalan di bawah flock eksklusif: ketika sepuluh worker mendapati token kedaluwarsa pada saat bersamaan, tepat satu yang memanggil SATUSEHAT dan sembilan lainnya memakai hasilnya.

Token yang disimpan ditandatangani HMAC dengan kunci client_secret, yang disuntikkan Oauth2 secara otomatis. Berkas yang ditulis pihak lain — misalnya token milik organisasi berbeda — gagal verifikasi dan diabaikan, sehingga data klinis tidak bisa dibelokkan ke organisasi yang salah hanya dengan menaruh berkas di disk. Berkas dari versi lama (tanpa tanda tangan) dianggap tidak ada dan diganti pada penyegaran berikutnya. Perlu dicatat: dua aplikasi dengan client_secret berbeda tidak bisa berbagi satu berkas token — masing-masing akan menolak token yang lain dan menyegarkan pada setiap panggilan, dan itulah sinyal yang memang diinginkan bahwa keduanya tidak seharusnya berbagi.

Catatan Windows Windows tidak menerapkan bit permission POSIX, jadi chmod() di sana hanya mengubah flag read-only dan fileperms() selalu melaporkan 0666. SDK tidak berpura-pura sebaliknya: pemeriksaan mode dilewati di Windows, dan kerahasiaan bergantung pada ACL direktori yang Anda tunjuk. Di Windows, lindungi direktori itu dengan NTFS ACL. Pemeriksaan HMAC tetap berlaku di semua platform. Host PHP-FPM produksi tidak terpengaruh.

Arahkan path ke direktori yang bisa ditulis user PHP dan berada di luar web root. Berkasnya berisi kredensial hidup — perlakukan seperti secret lain dan jangan pernah di-commit.

Pengujian

Suite berjalan di PHPUnit dan tidak memerlukan akses jaringan: handler Guzzle di-mock, dan transport KYC/FHIR diganti recorder. Hasil pada repo ini (PHP 8.4, PHPUnit 11.5):

Dua test permission dilewati di Windows karena perilaku yang diuji (bit mode POSIX) tidak ada di sana; PosixFileTokenStore di tests/Support menutup jalur verifikasi tersebut di Windows.

CI berjalan di setiap push ke main dan setiap pull request, dengan 3 job (7 run) sesuai .github/workflows/ci.yml:

PHP 8.0 dan 8.1 memakai PHPUnit versi sendiri (9.6 dan 10.5) karena PHPUnit 11 yang terkunci membutuhkan PHP 8.2; PHP 8.0 menjalankan test yang sama lewat composer test:compat, yang melewati berkas konfigurasi yang tidak bisa dibaca PHPUnit 9.6.

Kredit

Perangkat lunak ini memakai paket open source berikut:

• Composer
• Guzzle
• PSR-3 Log
• PHP Dotenv

Lisensi

MIT License

Copyright (c) 2024 Agung Gumilang Copyright (c) 2026 Muchamad Desta Fadilah ~ mdestafadilah

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.