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

Usage (Node.js)

Bahasa / Language: English · Bahasa Indonesia


English

1. Installation and setup

npm install @ivanwilliammd/satusehat-integration

2. Environment configuration

SATUSEHAT_ENV=DEV  # DEV | STAGING | PROD
SATUSEHAT_CLIENT_ID=your_client_id
SATUSEHAT_CLIENT_SECRET=your_client_secret
SATUSEHAT_ORGANIZATION_ID=your_org_id

3. Recommended usage pattern

Full example: create a Patient

import 'dotenv/config';
import {
  OAuth2Client,
  SSRequest,
  Identifier,
  HumanName,
  PayloadBuilderPatient,
} from '@ivanwilliammd/satusehat-integration';

async function main() {
  // 1. Initialize the OAuth2 client
  const oauth2 = new OAuth2Client({
    clientId: process.env.SATUSEHAT_CLIENT_ID!,
    clientSecret: process.env.SATUSEHAT_CLIENT_SECRET!,
    organizationId: process.env.SATUSEHAT_ORGANIZATION_ID!,
    environment: (process.env.SATUSEHAT_ENV as 'DEV' | 'STAGING' | 'PROD') || 'DEV',
  });

  // 2. Initialize the HTTP client
  const ss = new SSRequest(oauth2, { maxRetries: 5 });

  // 3. Build a Patient with the PayloadBuilder
  const patient = new PayloadBuilderPatient()
    .addIdentifier(
      new Identifier({
        system: 'http://sys-ids.kemkes.go.id/nik',
        value: '3312345678901234',
        use: 'official',
      })
    )
    .addName(
      new HumanName({
        family: 'Sitorus',
        given: ['John', 'Michael'],
        use: 'official',
      })
    )
    .setGender('male')
    .setBirthDate('1990-08-15')
    .setActive(true)
    .build();

  // 4. POST to Satu Sehat
  const response = await ss.post('Patient', patient);

  // 5. Handle the response
  if (response.isSuccess()) {
    console.log(`Patient created: ${response.getResourceId()}`);
  } else {
    for (const msg of response.getErrorMessages()) {
      console.log(`Error: ${msg}`);
    }
  }
}

main();

GET by ID

const response = await ss.get('Patient', 'abc-123-uuid');

if (response.isSuccess()) {
  console.log('Patient:', response.getBody());
}

Search Patients

const response = await ss.get('Patient', undefined, {
  params: { name: 'Sitorus' },
});

PUT (update)

const updated = new PayloadBuilderPatient()
  .setNik('3312345678901234')
  .setName('Sitorus', ['John'], 'official')
  .setGender('male')
  .setBirthDate('1990-08-15')
  .setActive(true)
  .build();

const response = await ss.put('Patient/abc-123-uuid', updated);

DELETE

const response = await ss.delete('Encounter/xyz-789');

4. Using data types directly

import {
  Identifier,
  HumanName,
  CodeableConcept,
  Coding,
  Quantity,
  Reference,
  Period,
} from '@ivanwilliammd/satusehat-integration';

const identifier = new Identifier({
  system: 'http://sys-ids.kemkes.go.id/nik',
  value: '3312345678901234',
  use: 'official',
});

const name = new HumanName({
  family: 'Doe',
  given: ['John', 'Michael'],
  use: 'official',
  prefix: ['Dr.'],
  suffix: ['SpPD'],
});

const conditionCode = new CodeableConcept()
  .addCoding(
    new Coding({
      system: 'http://terminology.kemkes.go.id/CodeSystem/clinical-term',
      code: 'A00.1',
      display: 'Cholera due to Vibrio cholerae 01, biovar eltor',
    })
  )
  .addCoding(
    new Coding({
      system: 'http://hl7.org/fhir/sid/icd-10',
      code: 'A00.1',
      display: 'Cholera due to Vibrio cholerae 01, biovar eltor',
    })
  )
  .setText('A00.1 - Cholera due to Vibrio cholerae')
  .toJSON();

const quantity = new Quantity({
  value: 120.5,
  comparator: '>=',
  unit: 'mmHg',
  system: 'http://unitsofmeasure.org',
  code: 'mm[Hg]',
});

const ref = new Reference({
  reference: 'Patient/abc-123-uuid',
  display: 'John Doe',
});

const period = new Period({
  start: '2024-01-01T00:00:00Z',
  end: '2024-12-31T23:59:59Z',
});

5. Error handling

const response = await ss.post('Patient', patient);

if (response.isError()) {
  for (const msg of response.getErrorMessages()) {
    console.log(`Error: ${msg}`);
  }

  const body = response.getBody();
  for (const issue of body.issue ?? []) {
    const severity = issue.severity;         // 'error' | 'warning' | 'information'
    const code = issue.code;                 // 'value' | 'structure' | 'required'
    const text = issue.details?.text;
    const expression = issue.expression?.[0];
    console.log(`[${severity}] ${text} (at ${expression})`);
  }
}

Common rule patterns

Rule Path Fix
10001 * Code not found in the code system — use approved terminology
10132 Composition.date Use YYYY-MM-DDThh:mm:ss+00:00; the date cannot be in the future or before 2022-08-31
10117 Encounter.identifier Use http://sys-ids.kemkes.go.id/asik/{org-id} or http://sys-ids.kemkes.go.id/sitb/{org-id}
10124 Encounter.serviceProvider Include a valid serviceProvider reference
10134 Composition.title The text must not be empty
10254 Claim.supportingInfo[*].sequence Send the integer as an unquoted number

6. OAuth2 token

const oauth2 = new OAuth2Client({ ... });
const token = await oauth2.getToken();

SSRequest resolves and refreshes the token on every HTTP call; manual access is rarely needed.

7. Retry behaviour

Status Action Strategy
401 Unauthorized Refresh the token, retry Exponential backoff (2^n s)
429 Rate Limited Retry Retry-After header or exponential backoff
5xx Server Error Retry Exponential backoff (2, 4, 8, 16, 32 s)
4xx Client Error No retry Return the error immediately

The sleep is capped at 60 seconds; the number of attempts is set with the maxRetries option.


Bahasa Indonesia

1. Pemasangan dan penyiapan

npm install @ivanwilliammd/satusehat-integration

2. Konfigurasi environment

SATUSEHAT_ENV=DEV  # DEV | STAGING | PROD
SATUSEHAT_CLIENT_ID=your_client_id
SATUSEHAT_CLIENT_SECRET=your_client_secret
SATUSEHAT_ORGANIZATION_ID=your_org_id

3. Pola pemakaian yang dianjurkan

Contoh lengkap: membuat Patient

import 'dotenv/config';
import {
  OAuth2Client,
  SSRequest,
  Identifier,
  HumanName,
  PayloadBuilderPatient,
} from '@ivanwilliammd/satusehat-integration';

async function main() {
  // 1. Siapkan klien OAuth2
  const oauth2 = new OAuth2Client({
    clientId: process.env.SATUSEHAT_CLIENT_ID!,
    clientSecret: process.env.SATUSEHAT_CLIENT_SECRET!,
    organizationId: process.env.SATUSEHAT_ORGANIZATION_ID!,
    environment: (process.env.SATUSEHAT_ENV as 'DEV' | 'STAGING' | 'PROD') || 'DEV',
  });

  // 2. Siapkan klien HTTP
  const ss = new SSRequest(oauth2, { maxRetries: 5 });

  // 3. Bangun Patient dengan PayloadBuilder
  const patient = new PayloadBuilderPatient()
    .addIdentifier(
      new Identifier({
        system: 'http://sys-ids.kemkes.go.id/nik',
        value: '3312345678901234',
        use: 'official',
      })
    )
    .addName(
      new HumanName({
        family: 'Sitorus',
        given: ['John', 'Michael'],
        use: 'official',
      })
    )
    .setGender('male')
    .setBirthDate('1990-08-15')
    .setActive(true)
    .build();

  // 4. Kirim ke Satu Sehat
  const response = await ss.post('Patient', patient);

  // 5. Tangani respons
  if (response.isSuccess()) {
    console.log(`Patient dibuat: ${response.getResourceId()}`);
  } else {
    for (const msg of response.getErrorMessages()) {
      console.log(`Error: ${msg}`);
    }
  }
}

main();

Ambil berdasarkan ID

const response = await ss.get('Patient', 'abc-123-uuid');

if (response.isSuccess()) {
  console.log('Patient:', response.getBody());
}

Cari Patient

const response = await ss.get('Patient', undefined, {
  params: { name: 'Sitorus' },
});

PUT (perbarui)

const updated = new PayloadBuilderPatient()
  .setNik('3312345678901234')
  .setName('Sitorus', ['John'], 'official')
  .setGender('male')
  .setBirthDate('1990-08-15')
  .setActive(true)
  .build();

const response = await ss.put('Patient/abc-123-uuid', updated);

DELETE

const response = await ss.delete('Encounter/xyz-789');

4. Memakai tipe data secara langsung

import {
  Identifier,
  HumanName,
  CodeableConcept,
  Coding,
  Quantity,
  Reference,
  Period,
} from '@ivanwilliammd/satusehat-integration';

const identifier = new Identifier({
  system: 'http://sys-ids.kemkes.go.id/nik',
  value: '3312345678901234',
  use: 'official',
});

const name = new HumanName({
  family: 'Doe',
  given: ['John', 'Michael'],
  use: 'official',
  prefix: ['Dr.'],
  suffix: ['SpPD'],
});

const conditionCode = new CodeableConcept()
  .addCoding(
    new Coding({
      system: 'http://terminology.kemkes.go.id/CodeSystem/clinical-term',
      code: 'A00.1',
      display: 'Cholera due to Vibrio cholerae 01, biovar eltor',
    })
  )
  .addCoding(
    new Coding({
      system: 'http://hl7.org/fhir/sid/icd-10',
      code: 'A00.1',
      display: 'Cholera due to Vibrio cholerae 01, biovar eltor',
    })
  )
  .setText('A00.1 - Cholera due to Vibrio cholerae')
  .toJSON();

const quantity = new Quantity({
  value: 120.5,
  comparator: '>=',
  unit: 'mmHg',
  system: 'http://unitsofmeasure.org',
  code: 'mm[Hg]',
});

const ref = new Reference({
  reference: 'Patient/abc-123-uuid',
  display: 'John Doe',
});

const period = new Period({
  start: '2024-01-01T00:00:00Z',
  end: '2024-12-31T23:59:59Z',
});

5. Penanganan galat

const response = await ss.post('Patient', patient);

if (response.isError()) {
  for (const msg of response.getErrorMessages()) {
    console.log(`Error: ${msg}`);
  }

  const body = response.getBody();
  for (const issue of body.issue ?? []) {
    const severity = issue.severity;         // 'error' | 'warning' | 'information'
    const code = issue.code;                 // 'value' | 'structure' | 'required'
    const text = issue.details?.text;
    const expression = issue.expression?.[0];
    console.log(`[${severity}] ${text} (di ${expression})`);
  }
}

Pola aturan yang sering muncul

Aturan Path Perbaikan
10001 * Kode tidak ditemukan di code system — pakai terminologi yang disetujui
10132 Composition.date Pakai YYYY-MM-DDThh:mm:ss+00:00; tanggal tidak boleh di masa depan atau sebelum 2022-08-31
10117 Encounter.identifier Pakai http://sys-ids.kemkes.go.id/asik/{org-id} atau http://sys-ids.kemkes.go.id/sitb/{org-id}
10124 Encounter.serviceProvider Sertakan referensi serviceProvider yang sah
10134 Composition.title Teks tidak boleh kosong
10254 Claim.supportingInfo[*].sequence Kirim bilangan bulat sebagai angka tanpa tanda kutip

6. Token OAuth2

const oauth2 = new OAuth2Client({ ... });
const token = await oauth2.getToken();

SSRequest mengambil dan menyegarkan token pada setiap panggilan HTTP; akses manual jarang diperlukan.

7. Perilaku retry

Status Tindakan Strategi
401 Unauthorized Segarkan token, ulangi Backoff eksponensial (2^n detik)
429 Rate Limited Ulangi Header Retry-After atau backoff eksponensial
5xx Server Error Ulangi Backoff eksponensial (2, 4, 8, 16, 32 detik)
4xx Client Error Tidak diulang Kembalikan galat segera

Jeda dibatasi 60 detik; jumlah percobaan diatur lewat opsi maxRetries.

Clone this wiki locally