Kiosk Integration Contract (1.0.0)

Contrat REST vendor-neutral entre la borne d'accueil patient (ApiBorne kiosk) et l'éditeur du système de gestion médical. Il couvre le parcours patient complet : identification, consultation du RDV, mise à jour du patient, gestion des documents, check-in et opérations satellites.

Pendant le parcours patient, l'éditeur est appelé selon l'un des deux modes de connectivité configurés côté ApiBorne (réglage kioskContractVia, page Intégration de l'admin) :

• borne en direct (défaut) : la borne appelle l'éditeur directement depuis son navigateur — éventuellement sur une adresse locale du réseau de l'établissement, différente de celle que voit le serveur ApiBorne ;
• relais serveur : la borne appelle {serveur ApiBorne}/api/contractRelay/api/apiborneIntegrationService/... et le serveur ApiBorne relaie la requête telle quelle vers l'éditeur (passthrough — éditeur injoignable → 502 RELAY_UPSTREAM_UNREACHABLE côté borne).

Le contrat vu par l'éditeur est identique dans les deux modes : seul le chemin réseau change. Dans tous les cas, le serveur ApiBorne reste requis pour la configuration de la borne au démarrage et la numérotation des tickets.

Toutes les opérations du contrat sont OBLIGATOIRES. Il n'y a pas de routes optionnelles ni de déclaration de support : un éditeur qui n'a pas la fonctionnalité implémente la forme minimale conforme — liste de documents vide (la borne saute le flow), 204 sans effet (PATCH patient, prescripteur), 404 systématique (codes de convocation non gérés), 401 INVALID_CREDENTIALS (pas de comptes personnel), { "ready": true } (pas de notion de notification). C'est ce qui garde la configuration côté ApiBorne simple et sans exception.

Chaque requête porte deux headers obligatoires :

L'éditeur DOIT valider les deux : device inconnu → 401 UNKNOWN_DEVICE, clé invalide pour ce device → 401 INVALID_AUTH_KEY.

ApiBorne envoie en plus le header X-Kiosk-Office-Id : l'identité de l'office/du groupe de licences telle que configurée côté ApiBorne (identifiant libre choisi par l'éditeur ; EasyDoct utilise la forme composée {officeId}!#!{officeVisibleId}). Un éditeur multi-sites DEVRAIT s'en servir pour sélectionner l'office cible au lieu de le résoudre via sa table de devices (la flotte des bornes est gérée dans l'admin ApiBorne, un device peut lui être inconnu). Un éditeur mono-site peut l'ignorer. Ce header doit être autorisé dans Access-Control-Allow-Headers (CORS).

En mode relais serveur, ces headers (X-Kiosk-Auth-Key, X-Kiosk-Device-Id, X-Kiosk-Office-Id) sont transmis inchangés à l'éditeur : X-Kiosk-Device-Id reste l'identifiant de la borne réelle, jamais celui du serveur ApiBorne — la validation attendue de l'éditeur est identique dans les deux modes.

Chiffrement de bout en bout (obligatoire)

Le contrat impose un chiffrement applicatif de bout en bout entre la borne et l'éditeur, par-dessus TLS : l'établissement génère une paire de clés RSA, la clé PRIVÉE reste sur le serveur de l'éditeur, la clé PUBLIQUE est saisie dans l'admin ApiBorne et transportée à la borne via sa configuration. Le serveur ApiBorne et tous les intermédiaires réseau sont incapables de déchiffrer (zero-knowledge) : en mode relais serveur, le relais ne voit passer que des corps chiffrés (passthrough zero-knowledge). C'est aussi ce chiffrement qui rend acceptable une URL contrat http sur un réseau local en mode borne directe.

Périmètre

Le chiffrement s'applique aux routes de communication émises par la borne (les 10 opérations du parcours patient : identifyPatients, getAppointmentByCode, getAppointmentById, updatePatient, setAppointmentPrescriber, listAppointmentDocuments, uploadAppointmentDocument, deleteAppointmentDocument, checkInAppointment, getNotificationReadiness) — requêtes et réponses 2xx.

Ne sont PAS chiffrés :

• les routes de configuration (openapi-config.yaml) : ce sont des référentiels sans donnée patient, consommés par le serveur ApiBorne ;
• staffSignIn et setAppointmentStatus : émises par le serveur ApiBorne, qui est le consommateur légitime de leurs réponses (E2E sans objet, TLS seul).

Protocole (v1)

• Chiffrement symétrique : AES-256-GCM, IV de 96 bits, tag d'authentification de 128 bits concaténé à la fin du ciphertext (convention WebCrypto).
• Enveloppe de clé : la clé de session (32 octets) est wrappée en RSA-OAEP avec SHA-256 (clé publique de l'établissement, RSA ≥ 2048 bits, 4096 recommandé).
• Clé de session unique PAR TENTATIVE : chaque requête (y compris chaque retry) génère une sessionKey ET un IV neufs — jamais de réutilisation.

La borne envoie deux headers sur toutes les méthodes (GET inclus, car les réponses sont sensibles) :

Le corps chiffré (requêtes avec corps) remplace le JSON clair par l'enveloppe (voir le schéma EncryptedEnvelope) :

{ "encrypted": { "v": 1, "iv": "<base64 12 octets>", "data": "<base64 ciphertext+tag>" } }

Réponses

• 2xx avec corps : l'éditeur répond la même enveloppe { "encrypted": { v, iv, data } }, chiffrée avec la même sessionKey que la requête et un IV neuf (jamais celui de la requête), plus le header X-Kiosk-Encryption: v1.
• 204 : pas de corps, rien à chiffrer.
• Erreurs 4xx/5xx : toujours EN CLAIR (format ErrorDto normal) — cela préserve la politique de retry et le diagnostic. Les messages d'erreur ne doivent JAMAIS contenir de données patient.

Échec de déchiffrement

Si l'éditeur ne peut pas déchiffrer (clé inconnue, tag invalide, enveloppe malformée), il répond 400 DECRYPTION_FAILED (en clair). La borne ne retente jamais et ne bascule jamais en clair (anti-downgrade) : l'erreur est affichée et tracée.

Taille des uploads

La limite contractuelle de 10 Mo (uploadAppointmentDocument) s'entend sur le JSON en clair. Le transport chiffré ajoute ~35 % (base64 du ciphertext) : l'éditeur DOIT dimensionner sa limite de corps HTTP en conséquence.

Rotation des clés

L'éditeur PEUT conserver plusieurs clés privées et essayer chacune à l'unwrap de la sessionKey. Procédure : déployer la nouvelle clé privée chez l'éditeur AVANT de saisir la nouvelle clé publique dans l'admin ApiBorne, puis retirer l'ancienne clé privée après la propagation de la configuration.

CORS

Les deux headers doivent être ajoutés au CORS de l'éditeur :

• Access-Control-Allow-Headers: …, X-Kiosk-Encryption, X-Kiosk-Encryption-Key
• Access-Control-Expose-Headers: X-Kiosk-Encryption

En mode relais serveur, les routes du parcours ne reçoivent que des appels serveur → serveur : l'exigence CORS navigateur (preflights et headers ci-dessus) ne s'applique plus au parcours.

Contexte de configuration (context)

Chaque requête POST/PATCH/PUT peut porter un objet context optionnel :

• context.locationId : identifiant du lieu (site) associé au device.
• context.config : sous-ensemble strict de la configuration borne consommé par l'éditeur (identification, documents, checkIn).
• context.vendorData : données opaques précédemment renvoyées par l'éditeur (voir plus bas).

Règle contractuelle : si context.config est fourni, l'éditeur DOIT l'utiliser et NE DOIT JAMAIS rappeler le serveur ApiBorne pour obtenir de la configuration. Si context.config est absent, l'éditeur utilise sa propre base de configuration (mode legacy direct).

vendorData

Les réponses peuvent contenir des champs vendorData (objets JSON opaques, au niveau réponse, patient ou rendez-vous). La borne ne les interprète jamais : elle les renvoie tels quels dans context.vendorData des appels suivants du même parcours qui concernent la même entité. L'éditeur peut s'en servir pour véhiculer des identifiants internes (éviter des relectures en base).

• DTOs : JSON camelCase, en anglais.
• Dates : ISO 8601 — date (YYYY-MM-DD) pour les dates de naissance, date-time avec offset (YYYY-MM-DDThh:mm:ss±hh:mm) pour les horodatages.
• Listes : vraies listes JSON (jamais de chaînes jointes par séparateur).
• Fichiers : pages en base64 dans des tableaux JSON (sans préfixe data:).
• Identifiants (patient.id, appointment.id, documentId, examId, locationId…) : chaînes opaques choisies par l'éditeur (max 128 caractères, utilisables dans une URL). La borne ne les interprète pas.

Statuts HTTP réels + corps { "error": { "code", "message", "details" } } :

La borne retente les erreurs réseau et les 5xx (selon sa politique de retry), mais jamais les 4xx.

Les anomalies de check-in sont transmises par code métier vendor-neutral (ex. PR, DI), jamais par identifiant interne d'un éditeur. Le référentiel des codes provient de la configuration borne (serveur ApiBorne).

Le contrat renvoie des données patient/RDV pures. Le matching des critères d'admission et des messages d'information (kiosk informations) est effectué côté borne à partir de sa propre configuration — l'éditeur n'a rien à implémenter.

Identification et mise à jour des patients

Consultation des rendez-vous, prescripteur, check-in

Documents attachés à un rendez-vous

Questionnaire préparatoire d'un rendez-vous (OPTIONNEL)

Authentification du personnel d'accueil (Cockpit)