Recommandations d’intégration

Objectif et périmètre

Cette page décrit les exigences d’intégration d’une interface cliente utilisant l’API SADV, pour garantir une utilisation sûre et efficace.

Elle s’adresse aux intégrateurs logiciels qui conçoivent l’interface utilisateur finale (logiciel métier, portail patient, application web ou mobile).

Les règles présentées ici reposent sur :

  • Des évaluations d’usage menées sur des échantillons représentatifs d’utilisateurs finaux (professionnels de santé et grand public), dans des situations proches de l’usage réel.
  • La spécification technique OpenAPI SADV, qui reste la source de vérité pour les schémas JSON.

Application de référence “Mentor”

L’application Mentor est l’implémentation de référence des recommandations d’intégration présentées dans ce guide. Elle est accessible publiquement et peut être utilisée pour tester les parcours d’intégration, la saisie des données, les appels API et la restitution des recommandations.

Niveaux normatifs

Niveau Signification
MUST Exigence obligatoire pour la sécurité d’utilisation et la conformité d’intégration.
SHOULD Recommandation forte pour améliorer l’ergonomie, la qualité et l’adoption.
MAY Option possible selon le contexte produit, sans impact direct sur la sécurité critique.

Flux d’intégration recommandé

Étape Description Endpoint principal
1. Collecte des données minimales Saisir date de naissance et sexe, puis préparer le contexte de saisie. POST /questionnaire (profil filtré) ou GET /questionnaire (profil complet)
2. Saisie du profil santé Afficher l’arborescence des sections et collecter les conditions typées. POST /questionnaire
3. Construction du dossier patient Assembler le payload patient avec les champs requis et optionnels. POST /diagnostic_for_patient
4. Restitution du diagnostic Présenter les conclusions, les dates, les messages et les documents de référence. POST /diagnostic_for_patient

Mises à jour non rétrocompatibles

Lorsqu’une nouvelle version SADV n’est pas rétrocompatible, elle est mise à disposition en environnement d’intégration pendant un délai de prévenance.

Concrètement :

  1. Syadem met à disposition la version en environnement d’intégration.
  2. Syadem met à jour la documentation d’intégration correspondant à cette version et la transmet aux clients.
  3. L’intégrateur valide son implémentation sur l’environnement d’intégration pendant la période de prévenance.
  4. La version est ouverte en production après expiration du délai de prévenance, si les validations sont conformes.

Exigences MUST - Collecte et saisie

ID Exigence Justification
MUST-01 L’interface doit collecter patient > birthdate et patient > gender avant tout appel au diagnostic. Champs requis du schéma OpenAPI.
MUST-02 L’interface doit imposer un format de date précis et valider la date avant envoi. Réduit les erreurs de saisie critiques.
MUST-03 L’interface doit afficher un mécanisme anti-erreur entre date de naissance et âge (calcul dynamique visible). Réduis les erreurs de saisie critique.
MUST-04 Le profil santé doit être saisi via la structure arborescente renvoyée par /questionnaire et supporter les types boolean, integer, date, float. Alignement contrat API et réduction des omissions.
MUST-05 Le profil santé doit inclure une fonction de recherche des conditions. Mesure validée comme efficace en sommative.
MUST-06 Chaque élément de patient > prevention_acts doit contenir date, prevention_method_id et booster (booléen explicite). booster est requis dans les objets d’acte vaccinal.

Exigences MUST - Appels API et robustesse

ID Exigence Justification
MUST-07 L’interface doit valider la complétude JSON avant POST /diagnostic_for_patient. Évite les erreurs bloquantes et les incohérences de diagnostic.
MUST-08 L’interface doit gérer les réponses 400 de façon compréhensible en exposant error > code et un détail actionnable. Permet la correction des données par l’utilisateur.
MUST-09 Avant d’établir une communication HTTPS, l’interface cliente doit vérifier le certificat TLS du serveur (chaîne de confiance, période de validité, correspondance du nom de domaine). En cas d’échec de vérification, la connexion doit être rejetée et la requête ne doit pas être envoyée. Voir la page Authentication. Réduit le risque de compromission de la confidentialité et de l’intégrité des échanges.

Exigences MUST - Restitution clinique

ID Exigence Justification
MUST-10 La restitution doit afficher pour chaque maladie advice > conclusion, targeted_date, limit_date, messages et documents. Champs requis du diagnostic détaillé.
MUST-11 L’interface doit distinguer visuellement les situations critiques (exemple : contraindicated et alert) et afficher un récapitulatif des données saisies avant décision finale. Réduction du risque d’interprétation dangereuse.
MUST-12 Les enums techniques de conclusion doivent être traduits en libellés compréhensibles par l’utilisateur final. Évite l’ambiguïté clinique.
MUST-13 Le parcours professionnel doit rappeler explicitement que la responsabilité finale de prescription reste au professionnel de santé. Exigence de sécurité d’usage documentée.
MUST-14 L’interface doit afficher les versions des bases de connaissances de knowledge_base_references (recommendation_rules, nuva_vaccine_nomenclature, condition_nomenclature) dans la restitution des recommandations. Assure la traçabilité des recommandations et des données utilisées.

Recommandations SHOULD - Ergonomie et adoption

ID Recommandation Bénéfice
SHOULD-01 Collecter patient > area_of_residency > zipcode quand l’information est disponible. Recommandations plus fines selon la zone de résidence.
SHOULD-02 Collecter patient > birthplace > countrycode quand l’information est connue. Affinage contextuel des recommandations.
SHOULD-03 Supporter le champ patient > journey pour les interfaces couvrant la vaccination voyageur. Couvre des cas d’usage élargis.
SHOULD-04 Proposer la recherche vaccinale par nom et maladie cible, avec options génériques. Réduit la friction de saisie de l’historique.
SHOULD-05 Ajouter un bouton Précédent et des breadcrumbs de navigation. Diminue les erreurs de navigation et de parcours.
SHOULD-06 Permettre l’impression ou l’export du diagnostic pour les usages professionnels. Facilite l’intégration au dossier patient.
SHOULD-07 Adapter les formulations selon public_destination (general, patient, professional). Améliore la compréhension selon le public.
SHOULD-08 Afficher knowledge_base_references > description quand le champ est disponible, selon la langue de l’interface avec fallback explicite. Améliore la compréhension des versions affichées sans bloquer le parcours si la description est absente.

Gestion des erreurs et cas limites

Erreurs de validation

  • En cas de 400, afficher un message clair sur les champs invalides et proposer une correction immédiate.
  • Toujours journaliser error > code côté technique pour le support.

Valeurs nulles ou absentes

  • targeted_date et limit_date peuvent être null et ne doivent pas bloquer l’affichage du reste de la recommandation.
  • Quand un champ optionnel patient est inconnu (birthplace, area_of_residency, journey), l’interface doit rester fonctionnelle avec les seules données obligatoires.

Cas non standards

  • Les conclusions exception, unmanaged ou complete_scheme doivent être rendues explicitement avec un libellé non ambigu.
  • Les éléments messages de type alert doivent être priorisés visuellement sur les messages de type informatif.

Tableaux de correspondance OpenAPI <-> Interface

Entrée patient (requêtes)

Champ JSON Type OpenAPI Requis Niveau Validation UI attendue
patient > birthdate string (date) Oui MUST Format approprié au contexte de l’utilisateur, date réelle, pas de valeur vide.
patient > gender string (m ou f) Oui MUST Sélecteur explicite, pas de valeur implicite.
patient > prevention_acts[] > date string Non MUST si acte saisi Date contrôlée, cohérence temporelle.
patient > prevention_acts[] > prevention_method_id string ou integer Non MUST si acte saisi Identifiant valide NUVA/acte de prévention.
patient > prevention_acts[] > booster boolean Non MUST si acte saisi Toujours envoyer true ou false.
patient > conditions[] > id string Non MUST si condition saisie Identifiant présent dans le questionnaire chargé.
patient > conditions[] > value typé selon condition Non MUST si condition saisie Type compatible (boolean, integer, date, float).
patient > area_of_residency > zipcode string Non SHOULD Validation locale du code postal.
patient > birthplace > countrycode string Non SHOULD Code pays structuré.
patient > journey > staying_conditions string Non SHOULD Champ renseigné si module voyage activé.
patient > journey > legs[] > countrycode string Non SHOULD Pays valide par segment.
patient > journey > legs[] > start_date string (date) Non SHOULD Date de début valide.
patient > journey > legs[] > end_date string (date) Non SHOULD Date de fin valide, postérieure ou égale à début.
requested_by_professional boolean Non SHOULD Indiquer explicitement le contexte d’usage professionnel/grand public.

Sortie diagnostic (réponse)

Champ JSON Type OpenAPI Priorité d’affichage Règle d’interface
conclusion enum Haute Afficher un statut global compréhensible dès le début.
diagnostic_per_disease[] tableau Haute Présenter une carte ou section par maladie.
diagnostic_per_disease[] > disease > name string Haute Afficher le nom de la maladie cible en en-tête de section.
diagnostic_per_disease[] > advice > conclusion enum Haute Afficher un statut local avec code couleur explicite.
diagnostic_per_disease[] > advice > targeted_date date ou null Moyenne Afficher uniquement si non nul.
diagnostic_per_disease[] > advice > limit_date date ou null Moyenne Afficher uniquement si non nul.
diagnostic_per_disease[] > advice > messages[] tableau Haute Trier par criticité (alert en premier).
diagnostic_per_disease[] > advice > documents[] tableau Moyenne Afficher les références officielles disponibles.
diagnostic_per_disease[] > advice > matching_conditions[] tableau Moyenne Montrer les conditions ayant influencé le résultat.
diagnostic_per_disease[] > prevention_acts_count integer Basse Affichage utile en contexte professionnel.
knowledge_base_references > recommendation_rules > version_id string Haute Afficher la version du jeu de règles dans la restitution des recommandations.
knowledge_base_references > nuva_vaccine_nomenclature > version_id string Haute Afficher la version de la nomenclature NUVA dans la restitution des recommandations.
knowledge_base_references > condition_nomenclature > version_id string Haute Afficher la version de la nomenclature des conditions dans la restitution des recommandations.
knowledge_base_references > * > generated_at date-time Moyenne Afficher l’horodatage de génération ou le conserver accessible pour traçabilité technique.
knowledge_base_references > * > description objet multilingue Moyenne Afficher la description quand disponible dans la langue de l’interface ; sinon utiliser un fallback documenté.

Mapping des conclusions vers libellés UI

Enum API Libellé UI recommandé Niveau de priorité
late Action en retard Critique
todo Action à faire prochainement Haute
up_to_date Vaccination à jour Standard
no_action Aucune action à prévoir Standard
contraindicated Vaccination contre-indiquée Critique
suggested Action suggérée Moyenne
complete_scheme Schéma complet Standard
unmanaged Cas non géré Haute
exception Situation exceptionnelle à analyser Haute

Règles de rendu des messages (message_type, public_destination)

Champ Valeurs Règle de rendu
message_type alert Affichage prioritaire, style d’avertissement, jamais masqué par défaut.
message_type summary, details, justification, comments, other Affichage structuré avec ordre stable et lisibilité clinique.
public_destination professional Message à afficher uniquement en contexte professionnel.
public_destination patient Message à afficher uniquement en contexte grand public.
public_destination general Affichage dans tous les contextes.

Règles de rendu des références de base de connaissances (knowledge_base_references)

Champ Valeurs Règle de rendu
knowledge_base_references > recommendation_rules > version_id string Afficher le libellé Jeu de règles de recommandation et la version associée.
knowledge_base_references > nuva_vaccine_nomenclature > version_id string Afficher le libellé Nomenclature NUVA et la version associée.
knowledge_base_references > condition_nomenclature > version_id string Afficher le libellé Nomenclature des conditions et la version associée.
knowledge_base_references > * > description objet multilingue ou absent Si présent, afficher la description dans la langue active de l’interface, sinon fallback fr, sinon première valeur disponible ; si absent, ne rien afficher.
knowledge_base_references > * > generated_at date-time Afficher une date lisible par l’utilisateur ou rendre l’information accessible dans un panneau de traçabilité.

Checklist de conformité intégrateur

  • L’interface collecte et valide birthdate et gender avant diagnostic.
  • Le format date est contrôlé et un mécanisme anti-erreur âge/date est visible.
  • La saisie du profil santé repose sur l’arborescence /questionnaire.
  • La recherche de conditions est disponible dans le profil santé.
  • Les actes vaccinaux incluent toujours date, prevention_method_id et booster.
  • Le payload est validé avant POST /diagnostic_for_patient.
  • Les erreurs 400 sont compréhensibles et exploitables.
  • Le client vérifie le certificat TLS avant toute communication HTTPS (chaîne de confiance, période de validité, nom de domaine) et rejette la connexion en cas d’échec.
  • La restitution affiche conclusion, dates, messages, documents et données ayant influencé la décision.
  • La restitution des recommandations affiche les versions des bases de connaissances (recommendation_rules, nuva_vaccine_nomenclature, condition_nomenclature).
  • La description des bases de connaissances est affichée lorsqu’elle est disponible, avec fallback de langue documenté.
  • Les messages critiques et contre-indications sont visuellement prioritaires.
  • Les enums techniques sont traduits en libellés métier compréhensibles.
  • Le parcours professionnel rappelle la responsabilité finale de prescription.

Références

Étape suivante

Passez à un exemple complet d’appel API, de la constitution du dossier patient à l’interprétation du diagnostic.