Skip to content
Ivan William Harsono edited this page Nov 17, 2026 · 3 revisions

Usage

Bahasa / Language: English · Bahasa Indonesia


English

The flow that matters

A clinical record is always the same walk: Patient → Encounter → everything else. Each later resource references the id of the one before it, and the server rejects a reference it cannot resolve.

import os

from dotenv import load_dotenv

from satusehat_integration import OAuth2Client, SSRequest
from satusehat_integration.builder import EncounterBuilder, ObservationBuilder, PatientBuilder
from satusehat_integration.datatype import Coding, Identifier, HumanName, Quantity

load_dotenv()

ss = SSRequest(OAuth2Client(satusehat_env=os.getenv("SATUSEHAT_ENV", "DEV")))

# 1. Patient
patient = (
    PatientBuilder()
    .add_identifier(Identifier(system="https://fhir.kemkes.go.id/id/nik",
                               value="3312345678901234", use="official"))
    .add_name(HumanName(family="Sitorus", given=["John"], use="official"))
    .set_gender("male")
    .set_birth_date("1990-01-15")
    .build()
)
patient_resp = ss.post("Patient", patient)

if not patient_resp.is_success():
    raise SystemExit(patient_resp.get_error_messages())

patient_id = patient_resp.get_resource_id()

# 2. Encounter — subject is the Patient id from step 1
encounter = (
    EncounterBuilder()
    .set_status("arrived")
    .set_class("AMB", "ambulatory")
    .set_subject(f"Patient/{patient_id}")
    .set_period(start="2026-11-17T02:00:00+00:00")     # 09:00 WIB in UTC
    .build()
)
encounter_id = ss.post("Encounter", encounter).get_resource_id()

# 3. Observation — needs both Patient and Encounter
observation = (
    ObservationBuilder()
    .set_status("final")
    .add_category("vital-signs", "Vital Signs")
    .set_code("8867-4", "Heart rate")
    .set_subject(f"Patient/{patient_id}")
    .set_encounter(f"Encounter/{encounter_id}")
    .set_value_quantity(Quantity(value=80, unit="beats/minute",
                                 system="http://unitsofmeasure.org", code="/min"))
    .build()
)
print(ss.post("Observation", observation).get_resource_id())

Dates are UTC

SATUSEHAT compares timestamps as instants. Jakarta is UTC+7, so a local 09:00 becomes 2026-11-17T02:00:00+00:00. Sending +07:00 is not wrong per the specification but is rejected by several rule numbers in practice — convert before building.

Searching

resp = ss.get("Patient", {"identifier": "https://fhir.kemkes.go.id/id/nik|3312345678901234"})

for entry in resp.get_body().get("entry", []):
    resource = entry.get("resource", {})
    print(resource.get("id"), resource.get("name", [{}])[0].get("text"))

Follow link[rel=next] by passing the full URL to ss.get(); the base URL is not prefixed twice.

Updating and deleting

ss.put(f"Patient/{patient_id}", patient_with_id)   # replace the whole resource
ss.patch(f"Patient/{patient_id}", patch_bundle)    # partial update
ss.delete(f"Encounter/{encounter_id}")

Bundles

bundle = (
    BundleBuilder()
    .set_type("transaction")
    .add_entry(patient, full_url="urn:uuid:1")
    .add_entry(encounter, full_url="urn:uuid:2")
    .build()
)
ss.post_bundle("", bundle)

A transaction Bundle is the only way to send resources that reference each other before any of them has an id: the server resolves urn:uuid: references in one operation.

Reading responses

resp.get_http_code()        # 200 / 201 / 400
resp.is_success()
resp.get_resource_id()      # id of the created or read resource, or None
resp.get_error_messages()   # human-readable strings from the OperationOutcome
resp.get_body()             # the parsed JSON body

Bahasa Indonesia

Alur yang paling penting

Rekam klinis selalu berjalan sama: Patient → Encounter → sisanya. Setiap resource berikutnya mereferensikan id resource sebelumnya, dan server menolak referensi yang tidak bisa diselesaikan.

import os

from dotenv import load_dotenv

from satusehat_integration import OAuth2Client, SSRequest
from satusehat_integration.builder import EncounterBuilder, ObservationBuilder, PatientBuilder
from satusehat_integration.datatype import Coding, Identifier, HumanName, Quantity

load_dotenv()

ss = SSRequest(OAuth2Client(satusehat_env=os.getenv("SATUSEHAT_ENV", "DEV")))

# 1. Patient
patient = (
    PatientBuilder()
    .add_identifier(Identifier(system="https://fhir.kemkes.go.id/id/nik",
                               value="3312345678901234", use="official"))
    .add_name(HumanName(family="Sitorus", given=["John"], use="official"))
    .set_gender("male")
    .set_birth_date("1990-01-15")
    .build()
)
patient_resp = ss.post("Patient", patient)

if not patient_resp.is_success():
    raise SystemExit(patient_resp.get_error_messages())

patient_id = patient_resp.get_resource_id()

# 2. Encounter — subject adalah id Patient dari langkah 1
encounter = (
    EncounterBuilder()
    .set_status("arrived")
    .set_class("AMB", "ambulatory")
    .set_subject(f"Patient/{patient_id}")
    .set_period(start="2026-11-17T02:00:00+00:00")     # 09:00 WIB dalam UTC
    .build()
)
encounter_id = ss.post("Encounter", encounter).get_resource_id()

# 3. Observation — butuh Patient dan Encounter
observation = (
    ObservationBuilder()
    .set_status("final")
    .add_category("vital-signs", "Vital Signs")
    .set_code("8867-4", "Heart rate")
    .set_subject(f"Patient/{patient_id}")
    .set_encounter(f"Encounter/{encounter_id}")
    .set_value_quantity(Quantity(value=80, unit="beats/minute",
                                 system="http://unitsofmeasure.org", code="/min"))
    .build()
)
print(ss.post("Observation", observation).get_resource_id())

Tanggal wajib UTC

SATUSEHAT membandingkan stempel waktu sebagai instan. Jakarta UTC+7, jadi 09:00 lokal menjadi 2026-11-17T02:00:00+00:00. Mengirim +07:00 tidak melanggar spesifikasi, tetapi dalam praktik ditolak oleh beberapa nomor aturan — konversi sebelum menyusun payload.

Pencarian

resp = ss.get("Patient", {"identifier": "https://fhir.kemkes.go.id/id/nik|3312345678901234"})

for entry in resp.get_body().get("entry", []):
    resource = entry.get("resource", {})
    print(resource.get("id"), resource.get("name", [{}])[0].get("text"))

Ikuti link[rel=next] dengan memberi URL penuh ke ss.get(); base URL tidak akan ditempel dua kali.

Memperbarui dan menghapus

ss.put(f"Patient/{patient_id}", patient_with_id)   # ganti seluruh resource
ss.patch(f"Patient/{patient_id}", patch_bundle)    # pembaruan sebagian
ss.delete(f"Encounter/{encounter_id}")

Bundle

bundle = (
    BundleBuilder()
    .set_type("transaction")
    .add_entry(patient, full_url="urn:uuid:1")
    .add_entry(encounter, full_url="urn:uuid:2")
    .build()
)
ss.post_bundle("", bundle)

Transaction Bundle adalah satu-satunya cara mengirim resource yang saling mereferensikan sebelum ada yang punya id: server menyelesaikan referensi urn:uuid: dalam satu operasi.

Membaca respons

resp.get_http_code()        # 200 / 201 / 400
resp.is_success()
resp.get_resource_id()      # id resource yang dibuat atau dibaca, atau None
resp.get_error_messages()   # string yang bisa dibaca manusia dari OperationOutcome
resp.get_body()             # body JSON yang sudah diurai

Clone this wiki locally