Intégration HIS / EMR

Intégration aux systèmes HIS / EMR

BiliTool.Vn prend en charge deux modes : ouvrir l’interface du calculateur par lien profond pour revue médicale, ou appeler une API REST sécurisée avec X-API-Key afin que le HIS reçoive des résultats JSON structurés.

Modes d’intégrationLien profond et API REST

API sécuriséeX-API-Key + limite de débit

ChampNouveau-nés ≥35 semaines, âge 1–336 heures

Méthode 1

Lien profond vers l’interface du calculateur

Approprié lorsque le HIS ouvre BiliTool.Vn dans un nouvel onglet ou une nouvelle fenêtre, préremplit les données de base et laisse le clinicien vérifier avant le calcul. Le lien profond ne nécessite pas de clé API car il n’appelle pas l’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

Paramètre	Obligatoire	Format valide	Notes
`ngaysinh`	Oui pour calcul automatique	`dd/MM/yyyy`, `d/M/yyyy` ou `ddMMyyyy`	Date de naissance.
`giosinh`	Recommandé	`HH:mm` ou `HHmm`	Si absent, l’interface utilise l’heure par défaut.
`ngaymau`	Oui pour calcul automatique	`dd/MM/yyyy`, `d/M/yyyy` ou `ddMMyyyy`	Date du prélèvement de bilirubine.
`giomau`	Recommandé	`HH:mm` ou `HHmm`	Si absent, l’interface utilise l’heure par défaut.
`bili`	Oui pour calcul automatique	Nombre décimal avec point, par exemple `12.5`	Bilirubine totale.
`donvi`	Non	`MgDl` ou `UmolL`	Unité par défaut de l’interface : `UmolL`.
`tuoithai`	Oui pour calcul automatique	Entier `35–45`	Âge gestationnel en semaines révolues.
`autocalc`	Non	`true` ou `false`	`true` lance le calcul au chargement.

Le lien profond ne transmet pas encore les facteurs de risque, l’ETCOc ou l’état de photothérapie. Le clinicien doit les sélectionner dans l’interface, ou le HIS doit appeler l’API REST.

Exemple JavaScript dans un EMR

// Ouvrir BiliTool.Vn depuis un EMR avec un lien profond
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");

Méthode 2

API REST pour calcul sans interface

Utiliser ce mode lorsque le HIS doit recevoir des résultats JSON pour les enregistrer dans le dossier électronique, les afficher dans un écran interne ou intégrer un flux automatisé. L’API exige X-API-Key et applique actuellement une limite de 30 requêtes par minute.

Les clés API de production sont attribuées uniquement aux partenaires d’intégration. Un service d’intégration indisponible retourne 503; une clé absente ou invalide retourne 401.

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

En-tête obligatoire

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

Champs d’entrée principaux

Champ JSON	Obligatoire	Type	Limites / signification
`tuoiTheoGio`	Oui si date/heure absentes	number	Âge au prélèvement, valide `1–336` heures.
`ngaySinh`	Oui si âge absent	Date ISO	Peut inclure l’heure, par exemple `2026-03-15T08:30:00+07:00`.
`gioSinh`	Non	`HH:mm:ss`	Si envoyé séparément, le système le combine avec `ngaySinh`.
`ngayLayMau`	Oui si âge absent	Date ISO	Doit être après la naissance; l’âge calculé doit être `1–336` heures.
`gioLayMau`	Non	`HH:mm:ss`	Si envoyé séparément, le système le combine avec `ngayLayMau`.
`tongBilirubin`	Oui	number	Supérieur à 0; maximum 60 pour mg/dL, 1026 pour µmol/L.
`donViDo`	Non	enum numérique	`0 = MgDl`, `1 = UmolL`. Valeur par défaut : 1.
`tuoiThaiTuan`	Oui	integer	Valide `35–45` semaines révolues.
`yeuToNguyCo`	Non	object	Si absent, tous les facteurs de risque valent false ou null.
`trangThaiChieuDen`	Non	enum numérique	0 sans photothérapie, 1 en cours, 2 intensive, 3 arrêtée.

Groupes de facteurs de risque pris en charge

AAP 2022 - risque de neurotoxicitéHémolyse iso-immune ou déficit G6PD, sepsis ou suspicion, albumine <3 g/dL, instabilité clinique, ETCOc si disponible.

NICE CG98 - risque clinique et étenduFratrie ayant reçu une photothérapie, allaitement maternel exclusif prévu, ictère dans les 24 premières heures, hémolyse Rh/ABO, signes d’encéphalopathie bilirubinique aiguë.

Exemple de requête JSON

{
  "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
}

Champs de réponse importants

Champ de réponse	Signification
`tuoiGio`, `tuoiThaiTuan`	Contexte patient après calcul et normalisation.
`bilirubinMgDl`, `bilirubinUmolL`	Bilirubine convertie dans les deux unités.
`nguongChieuDen`, `nguongChieuDenTichCuc`, `nguongThayCuuMau`	Seuils AAP 2022 en mg/dL.
`nguongChieuDen_NICE_UmolL`, `nguongThayCuuMau_NICE_UmolL`	Seuils NICE CG98 en µmol/L.
`canChieuDenNgay`, `canChieuDenTichCuc`, `canXemXetThayCuuMau`	Indicateurs décisionnels pour alertes HIS.
`gioDoLapTiepTheo`, `lichDoLapNICE`	Suggestion de contrôle répété si retournée par le moteur.
`phacDoQuyetDinh`, `chuThichThamChieu`	Recommandation déterminante et note de source.
`chartData`	Données nomogramme pour un graphique côté HIS si nécessaire.

Référence avancée

Endpoint avec enveloppe clinique

L’endpoint POST /api/v2/clinical/bilirubin/calculate utilise la même entrée que l’API v1, mais enveloppe le résultat dans guideline, patientContext, thresholds, recommendation et legacyResult. Il exige aussi X-API-Key.

Exploitation

Codes d’erreur à gérer côté HIS

400Données invalides : âge ou date de prélèvement manquants, âge hors 1–336 heures, gestation hors 35–45 semaines ou bilirubine au-dessus de la limite.

401X-API-Key absent ou invalide.

429Limite de débit API dépassée.

503Le service d’intégration est temporairement indisponible. Contactez le support BiliTool.Vn si le problème persiste.

500Erreur système; la réponse inclut traceId pour corrélation des journaux.