HIS / EMR Integration

Tích hợp hệ thống HIS / EMR

BiliTool.Vn hỗ trợ 2 cách tích hợp: mở giao diện bằng Deep Link để bác sĩ kiểm tra trực tiếp, hoặc gọi REST API bảo mật bằng X-API-Key để HIS nhận kết quả JSON.

Hình thức tích hợpDeep Link và REST API

API bảo mậtX-API-Key + rate limit

Phạm viTrẻ ≥35 tuần, tuổi 1–336 giờ

Phương pháp 1

Deep Link mở giao diện máy tính

Phù hợp khi HIS muốn mở BiliTool.Vn trong tab/cửa sổ mới, tự điền dữ liệu cơ bản, để bác sĩ kiểm tra lại trước khi tính. Deep Link không yêu cầu API key vì không gọi endpoint JSON.

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

Tham số	Bắt buộc	Định dạng hợp lệ	Ghi chú
`ngaysinh`	Có nếu auto tính	`dd/MM/yyyy`, `d/M/yyyy`, hoặc `ddMMyyyy`	Ngày sinh.
`giosinh`	Khuyến nghị	`HH:mm` hoặc `HHmm`	Nếu bỏ trống, UI dùng giờ mặc định.
`ngaymau`	Có nếu auto tính	`dd/MM/yyyy`, `d/M/yyyy`, hoặc `ddMMyyyy`	Ngày lấy mẫu bilirubin.
`giomau`	Khuyến nghị	`HH:mm` hoặc `HHmm`	Nếu bỏ trống, UI dùng giờ mặc định.
`bili`	Có nếu auto tính	Số thập phân dùng dấu chấm, ví dụ `12.5`	Bilirubin toàn phần.
`donvi`	Không	`MgDl` hoặc `UmolL`	Mặc định giao diện là `UmolL`.
`tuoithai`	Có nếu auto tính	Số nguyên `35–45`	Tuổi thai khi sinh theo tuần.
`autocalc`	Không	`true` hoặc `false`	`true` tự chạy tính toán sau khi mở trang.

Deep Link hiện chưa hỗ trợ truyền yếu tố nguy cơ, ETCOc hoặc trạng thái chiếu đèn. Dữ liệu này cần bác sĩ chọn trên giao diện hoặc HIS gọi REST API.

Ví dụ JavaScript trong HIS

// Mở BiliTool.Vn từ EMR bằng Deep Link
const url = new URL("https://bilitool.vn/may-tinh");
url.searchParams.set("ngaysinh", "15/03/2026");
url.searchParams.set("giosinh", "08:30");
url.searchParams.set("ngaymau", "16/03/2026");
url.searchParams.set("giomau", "10:00");
url.searchParams.set("bili", "12.5");
url.searchParams.set("donvi", "MgDl");
url.searchParams.set("tuoithai", "38");
url.searchParams.set("autocalc", "true");

window.open(url.toString(), "_blank", "width=1200,height=800");

Phương pháp 2

REST API cho HIS/EMR

Phù hợp khi HIS cần nhận kết quả JSON để lưu vào bệnh án điện tử, hiển thị trong màn hình nội bộ hoặc tích hợp workflow tự động. API yêu cầu header X-API-Key và đang áp dụng rate limit 30 request/phút cho mỗi cửa sổ giới hạn.

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

Production chỉ cấp API key cho đơn vị tích hợp. Khi dịch vụ tích hợp chưa khả dụng, API trả 503; nếu thiếu hoặc sai khóa, API trả 401.

Header bắt buộc

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

Trường đầu vào chính

Trường JSON	Bắt buộc	Kiểu	Giới hạn / ý nghĩa
`tuoiTheoGio`	Có nếu không gửi ngày giờ	number	Tuổi lúc lấy mẫu, hợp lệ `1–336` giờ.
`ngaySinh`	Có nếu không gửi `tuoiTheoGio`	ISO datetime	Có thể gửi kèm giờ, ví dụ `2026-03-15T08:30:00+07:00`.
`gioSinh`	Không	`HH:mm:ss`	Nếu gửi riêng, hệ thống dùng ngày của `ngaySinh` cộng giờ này.
`ngayLayMau`	Có nếu không gửi `tuoiTheoGio`	ISO datetime	Phải sau thời điểm sinh, tuổi tính được `1–336` giờ.
`gioLayMau`	Không	`HH:mm:ss`	Nếu gửi riêng, hệ thống dùng ngày của `ngayLayMau` cộng giờ này.
`tongBilirubin`	Có	number	>0; tối đa `60` nếu mg/dL, `1026` nếu µmol/L.
`donViDo`	Không	number enum	`0` = MgDl, `1` = UmolL. Mặc định `1`.
`tuoiThaiTuan`	Có	integer	Hợp lệ `35–45` tuần.
`yeuToNguyCo`	Không	object	Không gửi thì mặc định tất cả yếu tố là `false/null`.
`trangThaiChieuDen`	Không	number enum	`0` không chiếu đèn, `1` đang chiếu, `2` chiếu đèn tích cực, `3` đã dừng.

Yếu tố nguy cơ hỗ trợ trong API

AAP 2022 - nguy cơ độc thần kinh

benhTanHuyetMienDichHoacThieuG6PD nhiemKhuanHuyetHoacNghiNgo albuminThapDuoi3gDl tinhTrangLamSangKhongOnDinh etCOcPpm

NICE CG98 - nguy cơ lâm sàng / mở rộng

anhChiBiVangDaCanChieuDen meBuMeHoanToan vangDaTrong24hDau benhTanHuyetRh benhTanHuyetABO dauHieuBenhNaoBilirubinCap

Ví dụ request JSON

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

Nhóm trường kết quả quan trọng

Trường trả về	Ý nghĩa
`tuoiGio`, `tuoiThaiTuan`	Ngữ cảnh bệnh nhi sau khi hệ thống tính/chuẩn hóa.
`bilirubinMgDl`, `bilirubinUmolL`	Giá trị bilirubin quy đổi song song 2 đơn vị.
`nguongChieuDen`, `nguongChieuDenTichCuc`, `nguongThayCuuMau`	Ngưỡng AAP 2022 theo mg/dL.
`nguongChieuDen_NICE_UmolL`, `nguongThayCuuMau_NICE_UmolL`	Ngưỡng NICE CG98 theo µmol/L.
`canChieuDenNgay`, `canChieuDenTichCuc`, `canXemXetThayCuuMau`	Cờ quyết định để HIS hiển thị cảnh báo.
`gioDoLapTiepTheo`, `lichDoLapNICE`	Gợi ý thời điểm đo lại khi phác đồ trả về.
`phacDoQuyetDinh`, `chuThichThamChieu`	Phác đồ quyết định và ghi chú nguồn tham chiếu.
`chartData`	Dữ liệu nomogram để HIS tự vẽ biểu đồ nếu cần.

Tham khảo nâng cao

API v2 clinical wrapper

Endpoint POST /api/v2/clinical/bilirubin/calculate dùng cùng input như API v1 nhưng bọc kết quả theo cấu trúc clinical wrapper: guideline, patientContext, thresholds, recommendation, legacyResult. Endpoint này cũng yêu cầu X-API-Key.

GEThttps://bilitool.vn/api/v2/clinical/bilirubin/guidelines/active

Vận hành

Mã lỗi cần HIS xử lý

400Dữ liệu không hợp lệ: thiếu tuổi/ngày mẫu, tuổi ngoài 1–336 giờ, tuổi thai ngoài 35–45 tuần, bilirubin vượt giới hạn.

401Thiếu hoặc sai X-API-Key.

429Vượt rate limit API.

503Dịch vụ tích hợp tạm thời chưa khả dụng. Liên hệ hỗ trợ BiliTool.Vn nếu lỗi kéo dài.

500Lỗi hệ thống; response có traceId để đối soát log.