HIS / EMR Integration

HIS / EMR system integration

BiliTool.Vn supports two integration modes: open the calculator UI through a Deep Link for clinician review, or call a secure REST API with X-API-Key so the HIS receives structured JSON results.

Integration modesDeep Link and REST API

Secured APIX-API-Key + rate limit

ScopeInfants ≥35 weeks, age 1–336 hours

Method 1

Deep Link to open the calculator UI

Best when the HIS opens BiliTool.Vn in a new tab or window, pre-fills basic data, and lets the clinician review before calculating. Deep Link does not require an API key because it does not call the JSON endpoint.

GEThttps://bilitool.vn/may-tinh?ngaysinh=15/03/2026&giosinh=08:30&ngaymau=16/03/2026&giomau=10:00&bili=12.5&donvi=MgDl&tuoithai=38&autocalc=true

Parameter	Required	Valid format	Notes
`ngaysinh`	Yes for auto calculation	`dd/MM/yyyy`, `d/M/yyyy`, or `ddMMyyyy`	Birth date.
`giosinh`	Recommended	`HH:mm` or `HHmm`	If omitted, the UI uses its default time.
`ngaymau`	Yes for auto calculation	`dd/MM/yyyy`, `d/M/yyyy`, or `ddMMyyyy`	Bilirubin sample date.
`giomau`	Recommended	`HH:mm` or `HHmm`	If omitted, the UI uses its default time.
`bili`	Yes for auto calculation	Decimal number with dot, for example `12.5`	Total bilirubin.
`donvi`	No	`MgDl` or `UmolL`	The UI default is `UmolL`.
`tuoithai`	Yes for auto calculation	Integer `35–45`	Gestational age in completed weeks.
`autocalc`	No	`true` or `false`	`true` runs calculation after page load.

Deep Link currently does not pass risk factors, ETCOc, or phototherapy status. Clinicians must select those in the UI, or the HIS must call the REST API.

JavaScript example inside an EMR

// Open BiliTool.Vn from an EMR using Deep Link
const url = new URL("https://bilitool.vn/may-tinh");
url.searchParams.append("ngaysinh", "15/03/2026");
url.searchParams.append("giosinh", "08:30");
url.searchParams.append("ngaymau", "16/03/2026");
url.searchParams.append("giomau", "10:00");
url.searchParams.append("bili", "12.5");
url.searchParams.append("donvi", "MgDl");
url.searchParams.append("tuoithai", "38");
url.searchParams.append("autocalc", "true");
window.open(url.toString(), "_blank", "width=1200,height=800");

Method 2

REST API for headless calculation

Use this mode when the HIS needs JSON results for storage in the electronic record, display inside an internal screen, or automated workflow. The API requires X-API-Key and currently applies a 30 requests per minute rate limit window.

Production API keys are issued only to integration partners. An unavailable integration service returns 503; missing or invalid keys return 401.

POSThttps://bilitool.vn/api/v1/bilirubin/calculate

Required header

X-API-Key: {your_api_key}
Content-Type: application/json

Main input fields

JSON field	Required	Type	Limits / meaning
`tuoiTheoGio`	Yes if date/time omitted	number	Age at sampling, valid `1–336` hours.
`ngaySinh`	Yes if age omitted	ISO datetime	May include time, for example `2026-03-15T08:30:00+07:00`.
`gioSinh`	No	`HH:mm:ss`	If sent separately, system combines it with `ngaySinh`.
`ngayLayMau`	Yes if age omitted	ISO datetime	Must be after birth; computed age must be `1–336` hours.
`gioLayMau`	No	`HH:mm:ss`	If sent separately, system combines it with `ngayLayMau`.
`tongBilirubin`	Yes	number	Greater than 0; maximum 60 for mg/dL, 1026 for µmol/L.
`donViDo`	No	number enum	`0 = MgDl`, `1 = UmolL`. Default is 1.
`tuoiThaiTuan`	Yes	integer	Valid `35–45` completed weeks.
`yeuToNguyCo`	No	object	If omitted, all risk factors default to false or null.
`trangThaiChieuDen`	No	number enum	0 no phototherapy, 1 ongoing, 2 intensive, 3 stopped.

Supported risk factor groups

AAP 2022 - neurotoxicity riskIsoimmune hemolysis or G6PD deficiency, sepsis or suspected sepsis, albumin <3 g/dL, clinical instability, ETCOc if available.

NICE CG98 - clinical and extended riskSibling previously treated with phototherapy, exclusive breastfeeding intent, jaundice in first 24 hours, Rh/ABO hemolysis, acute bilirubin encephalopathy signs.

JSON request example

{
  "ngaySinh": "2026-03-15T08:30:00+07:00",
  "ngayLayMau": "2026-03-16T10:00:00+07:00",
  "tongBilirubin": 12.5,
  "donViDo": 0,
  "tuoiThaiTuan": 38,
  "yeuToNguyCo": {
    "benhTanHuyetMienDichHoacThieuG6PD": false,
    "nhiemKhuanHuyetHoacNghiNgo": false,
    "albuminThapDuoi3gDl": false,
    "tinhTrangLamSangKhongOnDinh": false,
    "etCOcPpm": null,
    "anhChiBiVangDaCanChieuDen": false,
    "meBuMeHoanToan": false,
    "vangDaTrong24hDau": false,
    "tanHuyetRh": false,
    "tanHuyetABO": false,
    "dauHieuBenhNaoBilirubinCap": false
  },
  "trangThaiChieuDen": 0
}

Important response fields

Response field	Meaning
`tuoiGio`, `tuoiThaiTuan`	Patient context after system calculation and normalization.
`bilirubinMgDl`, `bilirubinUmolL`	Bilirubin value converted in both units.
`nguongChieuDen`, `nguongChieuDenTichCuc`, `nguongThayCuuMau`	AAP 2022 thresholds in mg/dL.
`nguongChieuDen_NICE_UmolL`, `nguongThayCuuMau_NICE_UmolL`	NICE CG98 thresholds in µmol/L.
`canChieuDenNgay`, `canChieuDenTichCuc`, `canXemXetThayCuuMau`	Decision flags for HIS alerts.
`gioDoLapTiepTheo`, `lichDoLapNICE`	Suggested repeat-measurement timing when returned by the guideline engine.
`phacDoQuyetDinh`, `chuThichThamChieu`	Deciding guideline and source note.
`chartData`	Nomogram data for HIS-side chart rendering if needed.

Advanced reference

Clinical wrapper endpoint

Endpoint POST /api/v2/clinical/bilirubin/calculate uses the same input as API v1, but wraps the result as guideline, patientContext, thresholds, recommendation, and legacyResult. This endpoint also requires X-API-Key.

Operations

Error codes the HIS should handle

400Invalid data: missing age or sample date, age outside 1–336 hours, gestation outside 35–45 weeks, or bilirubin above limit.

401Missing or invalid X-API-Key.

429API rate limit exceeded.

503The integration service is temporarily unavailable. Contact BiliTool.Vn support if the issue persists.

500System error; response includes traceId for log correlation.