Composants embarqués

Les composants embarqués posent dans votre page les écrans de la facture électronique : la carte lue, le patient et ses droits, les actes tarifés à chaque geste, les parts, la signature par la CPS du poste, puis la chronologie de la feuille. Vous gardez vos écrans autour ; nous portons les évolutions des règles.

Ce sont des custom elements, en Shadow DOM, sans framework imposé, avec des enveloppes React et Vue. Ils s’appuient sur le composant navigateur : la page ne parle jamais à l’agent, l’agent n’ouvre aucun port, et le code porteur se saisit dans la fenêtre de l’agent.

Le paquet @ophelix/elements est en préversion et n’est pas encore publié.

Je veux…

Ouvrir une session

L’origine de la page doit être autorisée, comme pour toute page web. Votre serveur ouvre ensuite la session avec sa clé secrète, et dit ce que la page peut afficher :

curl -X POST https://api.ophelix.fr/v1/browser-sessions \
  -H "Authorization: Bearer sk_test_…" \
  -d origin=https://app.exemple.fr \
  -d "components[]=patient" \
  -d "components[]=acts" \
  -d "components[]=claim_summary" \
  -d "components[]=claim_timeline"

$session = $ophelix->browserSessions->create([
    'origin' => 'https://app.exemple.fr',
    'components' => ['patient', 'acts', 'claim_summary', 'claim_timeline'],
]);

const session = await ophelix.browserSessions.create({
  origin: 'https://app.exemple.fr',
  components: ['patient', 'acts', 'claim_summary', 'claim_timeline'],
})

Donnez session.client_secret à la page. Une session sans components lit les cartes et fait signer, rien de plus. Chaque composant n’ouvre que les objets de la session :

Tout autre objet répond 404, comme s’il n’existait pas. La page ne peut ni nommer un patient, ni imposer un prix : elle facture ce qu’elle a lu, et l’API tarife. Chaque lecture d’une donnée de santé est tracée au nom de la session, dans le journal d’audit.

Poser les éléments

<script src="ophelix-elements.global.js"></script>
 
<ophelix-card-reader></ophelix-card-reader>
<ophelix-patient></ophelix-patient>
<ophelix-acts></ophelix-acts>
<ophelix-claim-summary></ophelix-claim-summary>
<ophelix-claim-timeline></ophelix-claim-timeline>
 
<script>
  OphelixElements.load({
    fetchClientSecret: async () => (await (await fetch('/ophelix/session', { method: 'POST' })).json()).client_secret,
  })
</script>

import { loadOphelix } from '@ophelix/elements'
import { OphelixActs, OphelixCardReader, OphelixClaimSummary, OphelixPatient } from '@ophelix/elements/react'
 
loadOphelix({ fetchClientSecret })
 
export function Facturer() {
  return (
    <>
      <OphelixCardReader onCardRead={(event) => console.info(event.detail.action)} />
      <OphelixPatient />
      <OphelixActs />
      <OphelixClaimSummary onClaimSecured={(event) => relire(event.detail.claim)} />
    </>
  )
}

<script setup>
import { loadOphelix } from '@ophelix/elements'
import { OphelixActs, OphelixCardReader, OphelixClaimSummary, OphelixPatient } from '@ophelix/elements/vue'
 
loadOphelix({ fetchClientSecret })
</script>
 
<template>
  <OphelixCardReader />
  <OphelixPatient />
  <OphelixActs />
  <OphelixClaimSummary @claim-secured="(event) => relire(event.detail.claim)" />
</template>

Les éléments d’une page partagent la session et se suivent : la carte lue devient le patient, le premier acte ouvre la facture, le récapitulatif la fait signer et la chronologie la suit. Un attribut coverage ou claim montre un autre objet de la session.

Tous prennent theme="light" ou theme="dark" pour forcer un thème.

Le praticien

La facture se fait au nom du praticien qui facture depuis la page : celui que vous nommez par practitioner à l’ouverture de la session, sinon le dernier lu sur une CPS par cette page. Sans l’un ni l’autre, le premier acte répond browser_practitioner_missing. <ophelix-card-reader> et <ophelix-practitioner-onboarding> lisent la CPS.

Pour activer un praticien, <ophelix-practitioner-onboarding> va du poste (l’agent installé, la page associée par le code de l’agent) à l’identité lue sur la CPS, puis aux lecteurs. Un poste à appairer se fait par un code que votre serveur obtient par POST /v1/workstation-pairing-codes, passé dans pairing-code.

Le thème

Le thème passe par des propriétés CSS, posées sur :root ou sur un élément : elles traversent le Shadow DOM, et le code des éléments n’a pas à changer. Sans elles, les éléments prennent les couleurs d’Ophelix, claires ou sombres selon le réglage du poste (prefers-color-scheme).

:root {
  --ophelix-color-accent: #0f766e;
  --ophelix-color-accent-hover: #115e59;
  --ophelix-color-on-accent: #ffffff;
  --ophelix-font-family: Georgia, serif;
  --ophelix-radius-control: 999px;
  --ophelix-radius-card: 18px;
}
 
@media (prefers-color-scheme: dark) {
  :root {
    --ophelix-color-accent: #5eead4;
    --ophelix-color-on-accent: #042f2e;
  }
}

Une valeur que vous posez vaut pour les deux thèmes : redéfinissez-la dans votre bloc sombre. Gardez au moins 4,5:1 entre un texte et son fond, dans les deux.

Événements JavaScript

Les éléments émettent des CustomEvent qui remontent le DOM et sortent du Shadow DOM : un écouteur sur document les entend tous. Ils ne portent que des identifiants, jamais de nom, de NIR ni d’acte. Votre serveur relit l’objet avec sa clé.

Côté serveur, les webhooks disent la même chose : workstation_action.succeeded, coverage.retrieved, claim.created, claim.secured.

Accessibilité

Les éléments se parcourent au clavier : / mène à la recherche d’actes, ↑ ↓ y choisissent, Entrée pose l’acte, Échap ferme la liste. Le focus reste sur le champ d’un rendu à l’autre, les étapes de l’activation se suivent au clavier, et une région annonce aux lecteurs d’écran la lecture d’une carte et la signature. Les couleurs par défaut gardent 4,5:1 en clair comme en sombre.

En mode test

Avec une clé de test, le simulateur lit les cartes : scenario="vitale_exempted" sur <ophelix-card-reader> choisit le scénario d’une carte Vitale, cps-scenario celui d’une CPS. Voir Cartes et scénarios de test.

Pièges

• Un composant non ouvert répond browser_component_disabled : ajoutez-le à components. Une session vit trente minutes ; le composant en redemande une par fetchClientSecret, avec les mêmes composants si votre serveur les redonne.
• Ne croyez pas un identifiant venu de la page. Un événement dit ce qui s’est passé, votre serveur le vérifie : relisez la facture avec votre clé avant d’en tirer une conséquence.
• Une nouvelle session ne voit pas les factures de la précédente. Nommez-les par claims pour les montrer.
• La politique de sécurité de votre page doit laisser connect-src vers l’API. Les éléments n’écrivent aucun style dans un attribut : une politique stricte sur les styles ne les gêne pas.
• Le code porteur reste dans l’agent. Aucun élément ne le demande, et votre page ne doit pas le demander non plus.