Open-source Python SDK for integrating with SATUSEHAT — Indonesia's national health data platform powered by FHIR R4. Pure Python, no framework dependency.
| Area | Count | Evidence |
|---|---|---|
| Builder | 141 resources | satusehat_integration/builder |
| Builder methods | 1,405 | satusehat_integration/builder/test_method_name_parity.py (contract contracts/php_method_surface.json) |
| Parser | 141 resources (one per builder) | satusehat_integration/parser, satusehat_integration/parser/test_parser_surface.py |
| R5 namespace | 144 builder modules | satusehat_integration/r5/builder, satusehat_integration/r5/test_r5_namespace.py |
| Tests | 2,080 | python -m pytest |
R4 stays the reference; R5 means changing one import:
from satusehat_integration.builder.basic import BasicBuilder # R4
from satusehat_integration.r5.builder.basic import BasicBuilder # R5 — this line onlysatusehat-integration is an open-source Python SDK for integrating with SATUSEHAT — Indonesia's national health data platform powered by FHIR R4.
Built on the official SATUSEHAT Platform Guidelines. Ships with:
- 140 PayloadBuilder classes — fluent builders for all FHIR R4 resources (Patient, Practitioner, Organization, Encounter, Observation, Procedure, etc.)
- 50 DataType classes — composable FHIR R4 value objects with
to_json()serialization OAuth2Client&SSRequest— full SATUSEHAT OAuth2 authentication (DEV,STG,PROD), FHIR R4 HTTP client (GET,POST,PUT,DELETE,PATCH,patch_fhir_path,post_bundle) with automatic 401 token refresh and 429/5xx exponential backoffSSResponse,BundleResponse&SSValidationError— response wrappers and complete 558-rule SATUSEHAT validation error dictionary (RuleNumber10003–20021)- 142 FHIR Resource Parsers —
PatientParser,EncounterParser,ObservationParser,DiagnosticReportParser,PractitionerParser,ProcedureParser,ServiceRequestParser,SpecimenParser,TaskParser, and more - SQLite Queue + Worker + Monitor — full 8-module persistent SQLite queue (
SqliteQueue,Worker,QueueMonitor,RateLimiter,ErrorClassifier,QueueResult,QueueException,QueueInterface) with DLQ and retry scheduling TerminologyClient&TerminologyResolver— SmarTerm HTTP client + castable terminology strings ("ICD10:A00","LOINC:2951-2","SNOMED:38341003") directly to CodeableConcept- 3 SATUSEHAT-specific resources: BillingStatus (NON-FHIR JSON), PurificationDecision (NON-FHIR JSON), Endpoint (FHIR R4)
- pytest test suite — 92 unit tests covering builders, datatypes, HTTP transport, validation rules, parsers, queue, and terminology
Works standalone or with Django/FastAPI/Flask.
- Python 3.10 or later
pip install satusehat-integration
# or
git clone https://github.com/ivanwilliammd/satusehat-integration.git
cd satusehat-integration && pip install -e .# .env
SATUSEHAT_ENV=DEV # DEV | STG | PROD
SATUSEHAT_BASE_URL_DEV=https://api-satusehat-dev.dto.kemkes.go.id
CLIENTID_DEV=your_client_id
CLIENTSECRET_DEV=your_client_secret
ORGID_DEV=your_org_idAtomic FHIR R4 value objects. All provide a to_json() method — nested types serialize to clean FHIR JSON automatically.
| Category | Classes |
|---|---|
| Core | Coding, CodeableConcept, Identifier, ContactPoint, Address, HumanName, Reference |
| Quantity | Age, Quantity |
| Utility | Period, ParameterComponent |
Example — HumanName:
from satusehat_integration.datatype.datatypes import HumanName
name = HumanName(
family='Doe',
given=['John', 'Michael'],
use='official'
)
# name.to_json() → {'family': 'Doe', 'given': ['John', 'Michael'], 'use': 'official'}Fluent builder for each FHIR resource. Each builder exposes chainable methods and returns the resource payload via to_json().
from satusehat_integration.builder.payload_builders import PatientBuilder, HumanName
patient = PatientBuilder()
patient.add_name(HumanName(family='Doe', given=['John'], use='official').to_json())
patient.set_gender('male')
patient.set_birth_date('1990-01-15')
payload = patient.to_json()HTTP Client & Response Handling (satusehat_integration/ssrequest/, satusehat_integration/ssresponse/)
from satusehat_integration.ssrequest import OAuth2Client, SSRequest
from satusehat_integration.ssresponse import BundleResponse, SSValidationError
oauth = OAuth2Client(satusehat_env="DEV")
req = SSRequest(oauth2=oauth)
res = req.post("Observation", observation_payload)
if res.is_success():
print("Created resource ID:", res.get_resource_id())
else:
validator = SSValidationError.from_response(res)
print(validator.get_summary())from satusehat_integration.parser import EncounterParser, ObservationParser
enc = EncounterParser(encounter_json)
print(enc.get_subject_reference(), enc.get_location_references())from satusehat_integration.queue import SqliteQueue, Worker, QueueMonitor
queue = SqliteQueue("satusehat_queue.db")
queue.enqueue("POST", "Encounter", "Encounter", encounter_payload)
worker = Worker(queue, {
"base_url": oauth.base_url,
"fhir_url": oauth.fhir_url,
"client_id": oauth.client_id,
"client_secret": oauth.client_secret,
})
stats = worker.process(limit=50)
monitor = QueueMonitor(queue)
print(monitor.health_check())140 PayloadBuilder classes covering all FHIR R4 resources used in SATUSEHAT interoperability, plus 3 SATUSEHAT-specific resources.
| # | Resource | Builder |
|---|---|---|
| 1 | Account | AccountBuilder |
| 2 | AllergyIntolerance | AllergyIntoleranceBuilder |
| 3 | BillingStatus ⚡NON-FHIR | BillingStatusBuilder |
| 4–37 | CarePlan, Condition, Encounter, Goal, Immunization, Location, Medication*, Observation, Organization, Patient, Practitioner, Procedure, ServiceRequest, Specimen, Substance, Task, and more | see satusehat_integration/builder/ |
| 38 | Endpoint | EndpointBuilder |
| 39 | MedicationStatement | MedicationStatementBuilder |
| 40 | Task | TaskBuilder |
| 41 | PurificationDecision ⚡NON-FHIR | PurificationDecisionBuilder |
| 42–47 | Claim, ClaimResponse, CoverageEligibilityRequest/Response, DocumentReference, QuestionnaireResponse | see satusehat_integration/builder/ |
⚡ = NON-FHIR JSON (SATUSEHAT-specific extension)
from satusehat_integration.builder.billing_status import BillingStatusBuilder
billing = (BillingStatusBuilder()
.set_id('bs-001')
.add_identifier('http://sys-ids.kemkes.go.id/billing/org-001', 'BILL-12345')
.set_status('active')
.set_insurer('Organization/org-bpjs', 'BPJS Kesehatan')
.set_subject('100000030009', 'Budi Santoso')
.set_request('cer-001')
.build())from satusehat_integration.builder.endpoint import EndpointBuilder
endpoint = (EndpointBuilder()
.set_id('ep-001')
.set_status('active')
.set_connection_type('ihe-xcpd', 'IHE XCPD')
.set_name('SATUSEHAT FHIR Endpoint')
.set_managing_organization('Organization/org-ihs')
.set_address('https://satusehat-api.example.com/fhir/r4')
.build())from satusehat_integration.builder.purification_decision import PurificationDecisionBuilder
pd = (PurificationDecisionBuilder()
.set_id('pd-001')
.add_identifier('http://sys-ids.kemkes.go.id/purification/org-001', 'PD-12345')
.set_status('approved', 'Approved')
.set_insurer('Organization/org-bpjs', 'BPJS Kesehatan')
.set_provider('Organization/hos-001', 'Rumah Sakit Sehat')
.set_claim_response('cr-001')
.set_created('2024-01-15T10:35:00+00:00')
.build())from satusehat_integration.terminology.resolver import resolve, expand_array
# Cast terminology strings directly to CodeableConcept
resolve('ICD10:A00')
# → {'coding': [{'system': 'http://hl7.org/fhir/sid/icd-10', 'code': 'A00', 'display': 'A00'}], 'text': 'A00'}
resolve('LOINC:2951-2')
# → {'coding': [{'system': 'http://loinc.org', 'code': '2951-2', 'display': '2951-2'}], 'text': '2951-2'}
# Batch expand
expand_array(['ICD10:A00', 'ICD10:J18.9'])
# → [resolved_A00, resolved_J18.9]TerminologyClient is a standalone HTTP client for SmarTerm, separate from the SATUSEHAT
ecosystem — do not reuse the Kemkes SATUSEHAT OAuth. SmarTerm has its own authentication, in two
modes:
- Sanctum PAT (static token) sent as a
Bearerheader. Environment:TERMINOLOGY_API_TOKEN. - OIDC client_credentials against
auth.ivanmd.id(Passport) — the JWT is fetched lazily, cached until expiry, and refreshed once on a401. Environment:TERMINOLOGY_CLIENT_ID,TERMINOLOGY_CLIENT_SECRET,TERMINOLOGY_TOKEN_URL(defaulthttps://auth.ivanmd.id/oauth/token).
When both are supplied, PAT wins. Other environment variables: TERMINOLOGY_BASE_URL
(default https://terminology.ivanmd.id).
from satusehat_integration.terminology import TerminologyClient
term = TerminologyClient() # baca env, atau: TerminologyClient(token='pat-xxx')
# Fluent chaining
term.query('pemasangan kateter').on('kptl').limit(10).get()
term.query('demam').category('diagnosis').first()
term.query('paracetamol').on('kfa').all()
# as_code() → POST validate; the system is inferred from the shape of the code
term.query('93004944').as_code().get() # 93xxxx → system 'kfa'
term.query('J18.9').as_code().get() # ICD-10
# Pencarian & mapping
term.search('demam', category='all', limit=20) # unified search
term.search_system('icd10', 'demam', limit=20) # per-sistem
term.kptl_combine('9.10.1', ['9.11.1', '9.11.2']) # modifier join koma
term.map('icd10', 'snomed', 'J18.9') # cross-mapping
term.validate('icd10', 'J18.9')
term.auto_map('icd10', 'J18.9') # → SNOMED
# Context-aware FHIR resolution (body otomatis buang field None)
term.resolve_condition('J18.9')
term.resolve_chief_complaint('demam')
term.resolve_observation('2951-2', system_hint='loinc')
term.resolve_medication('93004944')
term.resolve_service_request('LAB001', category='lab')
# Value sets
term.value_sets()
term.value_set('kfa')HTTP status >= 400 melempar RuntimeError("TerminologyClient HTTP {status}: …");
network error melempar RuntimeError("TerminologyClient network error: …").
from satusehat_integration.builder.payload_builders import PatientBuilder
patient = PatientBuilder()
patient.add_name({
'family': 'Doe',
'given': ['John'],
'use': 'official'
})
patient.set_gender('male')
patient.set_birth_date('1990-01-15')
patient.add_telecom({'system': 'phone', 'value': '081234567890', 'use': 'mobile'})
payload = patient.to_json()
print(payload)from satusehat_integration.builder.payload_builders import ClaimBuilder
claim = ClaimBuilder()
claim.set_status('active')
claim.set_use('claim')
claim.set_type('institutional')
claim.set_patient('pat-123', 'enc-456')
claim.add_item(1, 'PROCID001', 150000, 'IDR')
claim.set_total(150000, 'IDR')
payload = claim.to_json()SATUSEHAT speaks FHIR R4; analyzers and LIS speak HL7 v2 over MLLP. Both ship in this package, so one install covers the whole path from instrument to national platform.
from satusehat_integration.hl7v2 import Ack, Client, Message, Profiles
msg = Message.parse(er7) # CR, LF or CRLF; encoding characters read from MSH-2
msg.message_type() # "ADT"
msg.get("PID.5.1") # family name, escapes decoded
msg.set("PID.8", "F") # re-escaped on write
str(msg) # ER7, CR-terminated, byte-for-byte round tripresult = Client("10.0.0.21:2575").send(msg)
result.accepted # MSA-1 == "AA"
result.control_id # MSA-2, verified against MSH-10
results = Client("10.0.0.21:2575").session(messages) # one socket, one result eachRules that are enforced rather than documented:
- Transport failures retry, verdicts do not.
AE/ARis returned to the caller; retrying an application rejection turns one bad message into a thousand. - MSA-2 must echo MSH-10. A reply with a different control id is stale or misrouted and raises.
- Frames carry over.
MllpReaderkeeps bytes that arrive after a complete frame, because onerecv()often returns two or three ACKs — a stateless reader would return the first and lose the rest.
Validation is data:
from satusehat_integration.hl7v2 import PROFILES, Message
issues = PROFILES["oruR01"]().validate(Message.parse(er7)) # also adtA01, adtA08
errors = [i for i in issues if i.severity == "error"] # warnings do not blockThe test corpus lives in satusehat_integration/hl7v2/fixtures/ and is copied byte-for-byte from the
PHP SDK: ten messages a hospital actually sends and ten that must be refused. Porting the corpus
rather than rewriting the tests is what makes "same behaviour in five languages" measurable.
Not implemented yet, and not claimed: batches (FHS/BHS), vendor-specific profiles beyond the three built in, HL7 v2 table validation, and a supervised MLLP server daemon.
HL7 CDA R2 is the document format that travels alongside HL7 v2 messages: v2 carries the transaction, CDA carries the signed document. This SDK reads and writes the part that is actually used — the header and the sections with narrative text — and leaves everything else alone.
from satusehat_integration.cda import Document
doc = Document.parse(xml) # refuses anything whose root is not ClinicalDocument
doc.title() # "Resume Medis Rawat Inap"
doc.patient().identifier("2.16.840.1.113883.3.3157.1003.1") # NIK
doc.patient().name()
doc.authors() # ["Ivan HARSONO"]
doc.section("10164-2").title # section by LOINC, searched depth-first
doc.section_text("10164-2") # narrative flattened to text, paragraphs kept
doc.validate() # [] means exchangeable, not clinically correctfrom satusehat_integration.cda import Document
doc = Document.build({
"id": "DOC-1",
"title": "Resume Medis",
"custodian": "RS Contoh",
"author": "Dokter Contoh",
"patientId": "3171234567890001",
"patientName": "ANGGRAENI",
"gender": "F",
"birthTime": "19850312",
"sections": [{"loinc": "10164-2", "title": "Riwayat", "text": "<paragraph>Demam.</paragraph>"}],
})
print(doc.to_xml())Two decisions worth stating:
- Unknown structure survives a round trip. Parsing keeps the
ElementTreeandto_xml()writes it back, socomponentOf/encompassingEncounter,participant,legalAuthenticatorand vendor extensions are preserved even though the SDK does not model them. A parser that rebuilds the document from its own model quietly deletes everything it did not understand. - Identifiers keep their
root. A NIK without its assigning-authority root cannot be matched against anything, and dropping the root is how a local MRN silently becomes a national NIK.
No new dependency: xml.etree.ElementTree is the standard library. It does not resolve external
entities, so a hostile document cannot pull in a local file through the parser. The HL7 CDA R2
schemas are licensed; the classes implement the structural rules from the specification and do not
redistribute them.
Not implemented: signature verification (ds:Signature), templates beyond the generic
POCD_MT000040 header, nonXMLBody attachments, CDA → FHIR mapping.
| Page | Description |
|---|---|
| Wiki Home | Full documentation |
| Getting Started | Installation, configuration |
| DataTypes | Complete type reference |
| Builders | Builder usage guide |
| Resources | All FHIR resources |
| Claim Module | BPJS Klaim integration |
Contributions are welcome. Please ensure tests pass and follow existing code conventions.
MIT — see LICENSE.