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.

Support technique

Le support technique SADV est destiné aux équipes qui intègrent l’API dans un logiciel client.

Pour ouvrir une demande, envoyez un message à developers@syadem.com.

Le support technique couvre l’accès API, l’authentification et l’analyse des erreurs d’intégration.

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

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 le format de date AAAA-MM-JJ 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). Problème majeur identifié en évaluation formative.
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.

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.

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 AAAA-MM-JJ, 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 Requis Priorité d’affichage Règle d’interface
conclusion enum Oui Haute Afficher un statut global compréhensible dès le début.
diagnostic_per_disease[] tableau Oui Haute Présenter une carte ou section par maladie.
diagnostic_per_disease[].disease.name string Oui Haute Afficher le nom de la maladie cible en en-tête de section.
diagnostic_per_disease[].advice.conclusion enum Oui Haute Afficher un statut local avec code couleur explicite.
diagnostic_per_disease[].advice.targeted_date date ou null Oui Moyenne Afficher uniquement si non nul.
diagnostic_per_disease[].advice.limit_date date ou null Oui Moyenne Afficher uniquement si non nul.
diagnostic_per_disease[].advice.messages[] tableau Oui Haute Trier par criticité (alert en premier).
diagnostic_per_disease[].advice.documents[] tableau Oui Moyenne Afficher les références officielles disponibles.
diagnostic_per_disease[].advice.matching_conditions[] tableau Oui Moyenne Montrer les conditions ayant influencé le résultat.
diagnostic_per_disease[].prevention_acts_count integer Oui Basse Affichage utile en contexte professionnel.

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.

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.
  • 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.