@icure/cardinal-prescription-be-react

Cardinal Prescription React Component 🇧🇪

This is a Belgian-specific React library for healthcare professionals to manage electronic prescriptions.
It integrates iCure's APIs — @icure/be-fhc-lite-api, @icure/api, and @icure/medication-sdk — to streamline:

• Practitioner certificate management
• Medication search
• Electronic prescription creation & editing
• Prescription overview & sending
• Printing of prescriptions

This component is designed for integration with Belgium’s SAM platform and can easily be embedded into other medical software projects as a drop-in feature for prescription management.

Table of Contents

• About iCure and Cardinal
• Features
• Technologies
• Prerequisites
• Getting Started
• Available Components and How to Use Them
• Available APIs
• SAM and Recip-e Requirements
• Medications of Interest for Tests
• Example Demo Application

About iCure and Cardinal

iCure is the company that provides a secure, end-to-end encrypted backend-as-a-service for Health-Tech, allowing companies to build fully compliant medical solutions faster.

Cardinal is iCure’s backend platform that provides data management, security, and interoperability features. In this project, we do not use the Cardinal backend directly — we integrate with iCure's public API to access its SAM and Free Health Connector (FHC) features.

Free Health Connector (FHC) The Cardinal Free Health Connector (FHC) is iCure’s open-source implementation of Belgium’s eHealth infrastructure. It enables secure, standards-based connections to government and regional healthcare systems

Features

• Designed specifically for Belgian healthcare professionals
• Practitioner certificate upload & verification
• Medication search powered by iCure's SAM SDK
• Create, edit, list, send, and print prescriptions
• Structured and unstructured posology support
• Interacts with Recip-e to send prescriptions
• Ready to integrate into medical apps
• Secure certificate storage in browser
• Fully internationalized (French, Dutch, German, English)

Technologies

• React 18+
• iCure SDKs (@icure/be-fhc-lite-api, @icure/api, @icure/medication-sdk)
• TypeScript
• React Hook Form for forms
• Styled-components for UI styling
• UUID for unique identifiers
• jsBarcode for barcode generation

Prerequisites

Before starting, make sure you have:

• Node.js v16+ and Yarn or npm installed
• A valid Belgian practitioner certificate file to load into the app
• Practitioner credentials for iCure authentication (generated in your app using @icure/cardinal-sdk or via iCure Cockpit for test purposes):
  • Create a HCP in Cockpit
  • Generate the authentication token for the HCP
• Patient and healthcare professional information to populate prescriptions
• A valid Free Health Connector URL, which depends on the certificate you use: for the acceptance certificate, use https://fhcacc.icure.cloud, and for the production certificate, use https://fhcprd.icure.cloud.
• A valid iCure URL that will be used for SAM. You should use: https://api.icure.cloud.
• Vendor and SamPackage

const practitionerCredentials = {
username: '[e-mail]',
password: 'xxxxxxxxxxx',
}
const ICURE_URL = 'https://api.icure.cloud'
const FHC_URL = 'https://fhcacc.icure.cloud'
const CARDINAL_PRESCRIPTION_LANGUAGE = 'fr'

const vendor = {
vendorName: 'vendorName',
vendorEmail: '[e-mail]',
vendorPhone: '[phone]',
}
const samPackage = {
packageName: 'test[test/1.0]-freehealth-connector',
packageVersion: '1.0]-freehealth-connector',
}

Getting Started

1. Install the library

yarn add @icure/cardinal-prescription-be-react

or

npm install @icure/cardinal-prescription-be-react

2. Peer dependencies

Your project should use React 18+ and styled-components 6+.

Available Components and How to Use Them

Below are usage examples as seen in the latest demo app:

<PractitionerCertificate />

Handles practitioner certificate upload, decryption, and validation.

import { PractitionerCertificate } from '@icure/cardinal-prescription-be-react'

<PractitionerCertificate
  certificateValid={ isCertificateValid }
  certificateUploaded={ isCertificateUploaded }
  errorWhileVerifyingCertificate={ errorWhileVerifyingCertificate }
  onResetCertificate={ onResetCertificate }
  onUploadCertificate={ onUploadCertificate }
  onDecryptCertificate={ onDecryptCertificate }
/>

<MedicationSearch />

Medication search interface using SAM. Triggers an event when a medication is selected for prescription.

import { MedicationSearch } from '@icure/cardinal-prescription-be-react'

<MedicationSearch 
  sdk={cardinalBeSamAInstance} 
  deliveryEnvironment="P" 
  onAddPrescription={onCreatePrescription} 
  disableInputEventsTracking={isPrescriptionModalOpen} 
/>

<PrescriptionList />

Lists created prescriptions and exposes actions to send, modify, print, or delete them.

import { PrescriptionList } from '@icure/cardinal-prescription-be-react'

<PrescriptionList
  prescribedMedications={ prescriptions }
  handleDeletePrescription={ onDeletePrescription }
  handleModifyPrescription={ onModifyPrescription }
  handleSendPrescriptions={ handleSendPrescriptions }
  handlePrintPrescriptions={ handlePrintPrescriptions }
/>

<PrescriptionModal />

Modal for creating or modifying prescriptions.

For creating:

<PrescriptionModal
  onClose={onClosePrescriptionModal}
  onSubmit={onSubmitCreatePrescription}
  modalMood="create"
  medicationToPrescribe={medicationToPrescribe}
/>

For modifying:

<PrescriptionModal
  onClose={onClosePrescriptionModal}
  onSubmit={onSubmitModifyPrescription}
  modalMood="modify"
  prescriptionToModify={prescriptionToModify}
/>

<PrescriptionPrintModal />

Printable PDF view of prescriptions.

import { PrescriptionPrintModal } from '@icure/cardinal-prescription-be-react'
import { HealthcareParty, Patient } from '@icure/be-fhc-lite-api' // types for prescriber and patient

<PrescriptionPrintModal
  prescribedMedications={prescriptions}
  prescriber={hcp}
  patient={patient}
  closeModal={onClosePrescriptionPrintModal}
/>

Available APIs

Alongside React components, the library exports key APIs for working directly with CardinalSDK and Free Health Connector (FHC) for authentication, and utility logic.

Work with SAM SDK

CardinalBeSam initialization

Initialize the CardinalBeSam SDK by creating an instance that will be passed to other services.

import { IccBesamv2Api, SamVersion, EnsembleAuthenticationProvider, NoAuthenticationProvider, IccAuthApi } from '@icure/api'

const cardinalBeSamInstance: IccBesamv2Api = new IccBesamv2Api(
  ICURE_URL,
  {},
  new EnsembleAuthenticationProvider(
    new IccAuthApi(
      ICURE_URL, 
      {}, 
      new NoAuthenticationProvider()
    ), 
    practitionerCredentials.username, 
    practitionerCredentials.password
  ),
)
setCardinalBeSamInstance(cardinalBeSamInstance)

Fetch the current SAM version:

import { fetchSamVersion } from '@icure/cardinal-prescription-be-react'

const samVersion = await fetchSamVersion(cardinalBeSamAInstance)
// cardinalBeSamAInstance is an instance of CardinalBeSamApi.sam (see demo)

Set the active language

Set the library’s language (for UI and errors):

import { cardinalLanguage } from '@icure/cardinal-prescription-be-react'

// Available: 'en', 'fr', 'nl', 'de'
cardinalLanguage.setLanguage('fr')
const currentLang = cardinalLanguage.getCurrentLanguage()

Certificate management

Load and decrypt practitioner certificate information from browser storage:

import { loadCertificateInformation } from '@icure/cardinal-prescription-be-react'

const result = await loadCertificateInformation(hcpSsin)
if (result) {
setCertificateUploaded(!!res)
}

Upload and encrypt a new certificate:

import { uploadAndEncryptCertificate } from '@icure/cardinal-prescription-be-react'

await uploadAndEncryptCertificate(hcpSsin, passphrase, certificateArrayBuffer)

Delete a stored certificate:

import { deleteCertificate } from '@icure/cardinal-prescription-be-react'

await deleteCertificate(hcpSsin)

Validate a decrypted certificate:

import { validateDecryptedCertificate } from '@icure/cardinal-prescription-be-react'

const validation = await validateDecryptedCertificate(hcp, passphrase, FHC_URL)
if (validation.status) {
// Certificate is valid
} else {
// validation.error contains error details (per language)
}

Prescription APIs

Send a prescription (“Recip-e”):

import { sendRecipe } from '@icure/cardinal-prescription-be-react'

const result = await sendRecipe(
{
vendor,                   // { vendorName, vendorEmail, vendorPhone }
samPackage,               // { packageName, packageVersion }
},
samVersion,               // Fetched from SAM SDK
hcp,                      // Healthcare professional object
patient,                  // Patient object
prescribedMedication,     // Medication details
passphrase                // Certificate passphrase
FHC_URL                   // Free health connector url
)
// result[0]?.rid contains the prescription RID if successful

SAM and Recip-e requirements

When the prescriber selects a medication, this application integrates with the SAMv2 database to provide all up-to-date metadata. This includes:

• Links to the leaflet & SPC.

• Special status indicators:

  • Black triangle (additional monitoring).
  • RMA material links.
  • DHPC communications.
  • Temporary supply problems.
  • End of commercialization or future commercialization.
  • VMP group information and switch statuses.
  • Conditions of delivery/prescription and risk minimization messages.
  • Reimbursement details (chapters, categories, extra reimbursement for youth contraception).

More information is available on the SAM portal.

Medications of interest for tests

Commercialization & supply problems

• Polydexa 10 mg/ml
• Crestor
• Cisplatine Teva 1 mg/ml inf. sol. (conc.) i.v. vial 50 ml

Future commercialization

• Kaftrio (black triangle)
• Increlex (black/orange triangle)

Doping status

• Ultiva
• Rapifen

Black triangle (additional monitoring), RMA

• Increlex

Note: This module is built for integration with Belgium’s SAM platform, is modular, and can be easily adapted for use in other medical solutions.

Example: Demo Application

To see the full working version, you can clone the GitHub repository and run the included demo app.

https://github.com/icure/cardinal-prescription-react/tree/main/packages/demo-app

Make sure to set up your .env variables or hardcode your credentials and HCP/Patient data for testing.