SADV - Système d'Aide à la Décision Vaccinale

Introduction

L’outil SADV, développé par la société Syadem, offre un service de recommandations vaccinales personnalisées basé sur des données médicales. Il est conçu pour être utilisé par les professionnels de santé ainsi que par les patients, agissant comme un guide dans le parcours vaccinal.

L’exclusivité du SADV réside dans sa capacité à optimiser et à maintenir à jour le parcours vaccinal de chaque patient. L’objectif premier de cet outil est de garantir la sécurité et l’efficacité des vaccinations, en stricte conformité avec les recommandations officielles en vigueur.

En France, le SADV s’appuie sur des directives officielles provenant de la Haute Autorité de Santé (HAS) ou du Ministère de la Santé. De plus, il utilise également les informations contenues dans les dossiers d’autorisation de mise sur le marché.

SADV respecte scrupuleusement la confidentialité des patients. Le système n’a pas la capacité de stocker des données personnelles ; il reçoit entrée des données patients anonymes et renvoie en sortie des recommandations vaccinales personnalisées, sans persister aucune donnée.

Concepts

Le SADV repose sur les concepts suivants :

Diagnostic vaccinal: Il s'agit d'un ensemble de recommandations vaccinales pour un patient donné.
Recommandation vaccinale: Une recommandation porte sur un patient donné et une maladie cible donnée,. La recommandation porte des informations telle que le statut vaccinal (le patient est-il en retard ou à jour ?) et l'action suggérée (par exemple, vacciner le patient à une certaine date).
Condition: Il s'agit d'une condition de vie pouvant impact les recommandations vaccinales (par exemple être enceinte ou avoir une maladie chronique). Chaque condition est d'un type particulier (par exemple, "grossesse" est une condition de valeur booléenne, tandis que "dernier antécédent de covid 19" est une condition de valeur de type date).
Profil santé: Il s'agit d'un ensemble de valeurs de conditions associé à un patient donné. Il prend la forme d'un ensemble de paires clé-valeurs où la clé est un identifiant de condition et la valeur est conforme au type attendu pour la condition.

Nomenclatures

SADV repose sur deux nomenclatures :

NUVA : cette nomenclature représente de manière structurée les vaccins et les maladies cibles ; elle permet d’encoder les historiques vaccinaux ;
VaccinationProfile : cette nomenclature décrit toutes les conditions possibles dans le profil santé d’un patient (grossesse, antécédents, résultats d’examen).

Intégration

L’outil SADV est accessible via une API Rest. Cette API est utilisable via des librairies documentées ci-dessous. Ces librairies vous permettront en tant qu’éditeur de logiciel métier d’intégrer des recommandations vaccinales dans votre logiciel.

Pré-requis

L’intégration de l’outil SADV repose sur trois librairies.

Librairie	Langages	Description
`sadv-client`	Documentation du client PHP Documentation du client Java	Permet d'interroger l'API REST de SADV.
`nuva`	Documentation (Ruby, Python, Typescript, PHP)	Permet de récupérer les données de la nomenclature NUVA, afin de structurer et d'afficher les données de l'historique vaccinal du patient dans votre logiciel.
`vaccination-profile`	Documentation du client PHP	Permet de récupérer les données de la nomenclature VaccinationProfile, afin de structurer et d'afficher les données du profil santé du patient dans votre logiciel.

Aperçu de l’API

L’API de SADV est disponible sous la forme d’une API REST.

L’accès à cette API est restreint et repose sur les protocoles d’authentification OAuth 2.0 et OpenID Connect 1.0. Pour obtenir un accès, veuillez contacter l’équipe de Syadem.

L’API expose 2 points d’appel, dont les spécifications sont disponibles dans la documentation swagger.

/questionnaire : permet de récupérer les informations du formulaire de personnalisation des recommandations vaccinales ;
/diagnostic_for_patient : permet de récupérer les recommandations vaccinales personnalisées.

Note : en utilisant la librairie sadv-client, vous n’avez pas besoin de construire les requêtes HTTP et de parser les réponses JSON. La librairie s’occupe de tout cela pour vous.

Modes d’authentification

Authentification en mode “logiciel client”

L’API SADV utilise OAuth 2.0, le protocole de référence de l’industrie pour l’autorisation. Plus précisément, l’autorisation d’accès à l’API de SADV repose sur le mécanisme d’autorisation (authorization grant) “client credentials authentication grant”.

Concrètement, vous devez obtenir un jeton d’accès auprès de notre serveur d’authentification (en s’identifiant avec vos identifiants clients), avant d’inclure ce jeton dans les requêtes envoyées à l’API SADV. Il est recommandé d’utiliser une librairie OAuth (librairies suggérées).

Note : Le jeton d’accès obtenu avec mode d’authentification est associé l’identifiant unique de votre logiciel en tant que système client du SADV.

Voici un exemple d’obtention du jeton d’accès (pré-requis : les outils curl et jq doivent être installés) :

# paramètres variant selon l’environnement
CLIENT_ID=...
CLIENT_SECRET=...
AUTH_ROOT_URL=https://auth.integration.mesvaccins.net

ACCESS_TOKEN=$(curl -s -X POST -u $CLIENT_ID:$CLIENT_SECRET -d 'grant_type=client_credentials' \
$AUTH_ROOT_URL/realms/professional/protocol/openid-connect/token | \
jq -r '.access_token')

echo $ACCESS_TOKEN

Exemple d’utilisation

Dans cette partie, nous allons détailler toutes les étapes nécessaires pour obtenir des recommandations vaccinales personnalisées pour un patient.

Le contexte d’utilisation est le suivant :

L’utilisateur final (un professionnel de santé) a ouvert un dossier patient dans son logiciel métier ;
Le professionnel de santé souhaite obtenir des recommandations vaccinales personnalisées pour ce patient.

Avant de lire les étapes qui suivent, nous vous conseillons d’expérimenter avec notre outil en ligne d’aide à la décision, Mentor, dont le fonctionnement est similaire à celui de l’intégration de SADV dans un logiciel métier.

Les étapes de l’obtention des recommandations vaccinales sont les suivantes :

Récupération des informations de base du patient
Récupération du questionnaire du profil santé
Saisie du questionnaire du profil santé
Constitution du dossier patient à envoyer
Récupération des recommandations vaccinales
Affichage des recommandations vaccinales

Les étapes 1 et 2 sont optionnelles. Elle ont pour but de récupérer des informations supplémentaires sur le patient, qui permettront d’affiner les recommandations vaccinales. Ces informations supplémentaires constituent le profil santé du patient.

Nous supposons ici que vous disposez déjà d’un accès à la NUVA pour encoder l’historique vaccinal du patient ainsi que d’un accès a la librairie VaccinationProfile.

Étape 1 : Récupération des informations de base

On suppose que le logiciel métier du professionnel de santé a déjà récupéré les informations de base suivantes : date de naissance, sexe du patient et optionnellement, son code postal de résidence.

Étape 2 : Récupération du questionnaire du profil santé

Pour récupérer le questionnaire du profil santé, le logiciel client doit envoyer une requête HTTP POST à l’URL /questionnaire de l’API SADV.

Par exemple, pour un patient né le 1er janvier 2000 et de sexe masculin, la requête est la suivante (on ne précise pas le code postal):

# paramètre variant selon l’environnement
SADV_ROOT_URL=https://api.fr.sad.mesvaccins.net

# informations du patient
BIRTHDATE="2000-01-01"
GENDER="m"

curl -X POST "${SADV_ROOT_URL}/questionnaire" \
-H "Content-Type: application/json" \
-d '{
  "patient": {
    "birthdate": "'"${BIRTHDATE}"'",
    "gender": "'"${GENDER}"'"
  },
  "requested_by_professional": true
}'

Pour plus de détails concernant cette requête, vous pouvez consulter :

Documentation du point d’appel REST

Étape 3 : Saisie du questionnaire du profil santé

Le point d’appel précédent renvoie sous la forme d’un arbre les question hiérarchisées du questionnaire du profil santé.

Chaque noeud de l’arbre est une section comportant un titre et une liste de conditions à saisir par l’utilisateur.

Pour chaque condition, on précise son type (booléen, liste de choix, date, etc.) et son libellé.

Le logiciel client doit afficher le questionnaire arborescent à l’utilisateur, et récupérer ses réponses. Les informations collectées constituent le profil santé. Le logiciel client peut persister ces informations pour éviter de les redemander à l’utilisateur à chaque fois.

Pour implémenter l’interface du questionnaire du profil santé, nous vous suggérons de suivre le fonctionnement du questionnaire santé dans notre outil Mentor.

Voici un exemple de réponse du questionnaire:

[
  {
    "alert": {},
    "description": {},
    "help": {},
    "question": {
      "en": "General information",
      "fr": "Informations générales"
    },
    "title": {
      "en": "General information",
      "fr": "Informations générales"
    },
    "id": "c396ad68-b41a-4712-9627-655de08541a2",
    "sections": [
      {
        "alert": {},
        "description": {},
        "help": {},
        "question": {
          "en": "Other",
          "fr": "IDR - BCG"
        },
        "title": {
          "en": "Other",
          "fr": "IDR - BCG"
        },
        "id": "4c39da47-6db7-41ee-84a5-6ecdd2144703",
        "sections": [],
        "conditions": [
          {
            "id": "ba606ef4-9ebb-41b2-a81f-56a36bf8897e",
            "label": {
              "en": "IDR (mm)",
              "fr": "IDR (mm)"
            },
            "condition_type": "integer",
            "help": {
              "en": "Intradermal tuberculin test",
              "fr": "Intradermoréaction à la tuberculine"
            },
            "position": 1
          },
          {
            "id": "ad7d3400-7c63-4581-ba87-5688fba50fae",
            "label": {
              "en": "BCG vaccine scar",
              "fr": "Cicatrice vaccinale du BCG"
            },
            "condition_type": "boolean",
            "help": {
              "en": "This scar is usually located behind the deltoid muscle, the usual site of the intradermal injection of BCG. It shows that this vaccine, which allows the development of an immune response against the Koch's bacillus (the bacillus responsible for tuberculosis), has been administered. Consult your doctor for more information.",
              "fr": "Cette cicatrice est généralement située en retard du deltoïde, lieu habituel de l'injection par voie intradermique du BCG. Elle montre que ce vaccin, qui permet le développement d'une réponse immunitaire contre le bacille de Koch (le bacille responsable de la tuberculose), a été administré. Consultez votre médecin pour plus d'information à ce sujet."
            },
            "position": 2
          }
        ]
      }
    ],
    "conditions": []
  }
]

Un questionnaire est composé de sections qui sont elles-mêmes composées de sections ou alors de conditions. Voici le détail d’un object Section:

alert: Une alerte avec les traductions dans différentes langues.
description: Une description avec les traductions dans différentes langues.
help: Une aide avec les traductions dans différentes langues.
question: Une question avec les traductions dans différentes langues.
title: Un titre avec les traductions dans différentes langues.
id: L’identifiant de la section. Exemple : “4c39da47-6db7-41ee-84a5-6ecdd2144703”.
sections (tableau) : Un tableau de sous sections.
conditions (tableau) : Un tableau de conditions.

Une section ne peut contenir que d’autres sections ou des conditions, mais jamais les 2.

Voici le détail d’un objet Condition:

id: Identifiant de la condition.
label: Libellé de la condition dans différentes langues.
condition_type: Type de condition. (“boolean”, “integer”, “date”, “float”)
help: Aide ou description de la conditiondans différentes langues.
position (nombre entier) : Position de la condition dans la section.

Étape 4 : Constitution du dossier patient à envoyer

Le logiciel client doit constituer un dossier patient à envoyer à l’API SADV. Ce dossier patient est un objet JSON qui contient :

Les informations de base du patient (date de naissance, sexe, code postal de résidence)
Le profil santé du patient (informations optionnelles)
L’historique vaccinal.

Voici la liste des paramètres possibles:

patient:
- birthdate: Date de naissance du patient au format “AAAA-MM-JJ”. Exemple : “1988-01-30”.
- gender: Genre du patient. Les valeurs possibles sont “m” pour masculin et “f” pour féminin.
- prevention_acts: Tableau représentant la liste des actes de vaccination du patient. Si le patient n’en posséde pas il sufit d’envoyer un tableau vide.
  - date: Date de la vaccination au format “AAAA-MM-JJ”. Exemple : “2019-01-01”.
  - prevention_method_id: Identifiant NUVA correspondant au vaccin administré.
  - booster: Booléen afin de définir un vaccin comme rappel.
- conditions (Optionnel) : La liste des éléments du profil santé du patient correspondant au questionnaire complété.
  - id: L’identifiant de la condition
  - value: La valeur correspondant à son type
- area_of_residency (Optionnel) : Zone de résidence du patient.
  - zipcode: Code postal de la zone de résidence du patient. Exemple : “33000”.
- birthplace (Optionnel) : Lieu de naissance du patient.
  - countrycode: Code du pays de naissance du patient. Exemple : “FRA”.
requested_by_professional (booléen) : Indicateur indiquant si la demande est faite par un professionnel. Les valeurs possibles sont “true” (vrai) ou “false” (faux).

Voici un exemple de dossier patient pour un homme né le 30 janvier 1988, en France, résident à Bordeaux et ayant reçu un vaccin boostrixtetra le 1er janvier 2019:

{
  "patient": {
    "birthdate": "1988-01-30",
    "gender": "m",
    "prevention_acts": [
      {
        "date": "2019-01-01",
        "prevention_method_id": "384198db-b13c-4e08-b7a1-9311809a21b9"
      }
    ],
    "conditions": [
      {
        "id": "3e76320a-0b4d-4cb2-8095-764b19b08017",
        "value": true
      }
    ],
    "area_of_residency": {
      "zipcode": "33000"
    },
    "birthplace": {
      "countrycode": "FRA"
    }
  },
  "requested_by_professional": true
}

Étape 5 : Récupération des recommandations vaccinales

La récupération des recommandation vaccinales se fait en envoyant une requête HTTP POST à l’URL /diagnostic_for_patient de l’API SADV.

# paramètre variant selon l’environnement
SADV_ROOT_URL=https://api.fr.sad.mesvaccins.net

curl -X POST "${SADV_ROOT_URL}/diagnostic_for_patient" \
-H "Content-Type: application/json" \
-d '{
  "patient": {
    "birthdate": "1988-01-30",
    "gender": "m",
    "prevention_acts": [
      {
        "date": "2019-01-01",
        "prevention_method_id": "384198db-b13c-4e08-b7a1-9311809a21b9",
        "booster": false
      }
    ],
    "area_of_residency": {
      "zipcode": "33000"
    },
    "birthplace": {
      "countrycode": "FRA"
    }
  },
  "requested_by_professional": true
}'

Le retour de la requête est un objet JSON contenant les recommandations vaccinales pour le patient.

Étape 6 : Affichage des recommandations vaccinales

Le logiciel client doit afficher les recommandations vaccinales au professionnel de santé. Le rendu graphique des recommandations vaccinales est laissé à la discrétion du logiciel client.

L’objet JSON retourné par l’API SADV contient les informations suivantes :

Une conclusion globale sur l’état vaccinal du patient
Une liste de recommandations vaccinales, classées par maladies

Exemple de retour de l’api :

{
  "conclusion": "late",
  "diagnostic_per_disease": [
    {
      "disease": {
        "id": "47cac099-7918-4329-9079-bdeb057957f0",
        "name": "Diphtérie",
        "translations": {
          "en": "Diphtheria",
          "fr": "Diphtérie"
        }
      },
      "prevention_acts_count": 1,
      "advice": {
        "conclusion": "late",
        "messages": [
          {
            "id": "badbce0e-3674-491b-8c29-d73e45736ce5",
            "message_type": "summary",
            "public_destination": "general",
            "contents": {
              "en": "Second dose at least 2 months after the first dose.",
              "fr": "Deuxième dose au moins 2 mois après la première dose."
            }
          }
        ],
        "targeted_date": "2019-03-01",
        "limit_date": "2019-03-31",
        "matching_conditions": ["3e76320a-0b4d-4cb2-8095-764b19b08017"],
        "documents": [
          {
            "id": "8c7a7a9d-536a-4560-b5b6-0993e2fbf880",
            "title": "Vaccination contre la diphtérie, le tétanos et la poliomyélite (dTP ou DTP) - Calendrier vaccinal 2023",
            "url": "",
            "file": {
              "filename": "2023-dtp.pdf",
              "url": "https://ged.mesvaccins.net/r9kh69n7bxvwgnvvv2hd0ahb4fh8"
            },
            "organization": "Ministère de la santé",
            "language": "fr",
            "target_audience": "health_professional",
            "publication_date": "2023-04-12"
          }
        ]
      }
    }
  ]
}

Un diagnostic posséde une conclusion globale afin de savoir rapidement l’éventuelle action à apporter. Cette conclusion est déterminé selon la priorité du status d’une maladie par rapports aux autres maladies. Voici la liste:

“late”
“todo”
“up_to_date”
“no_action”

Dans l’exemple donné, le patient présente un retard dans ses vaccinations. Voici les autres conclusions possibles :

“no_action” : Aucune action à prévoir.
“up_to_date” : Aucune action à prévoir, le patient est à jour dans ses vaccinations.
“late” : Action en retard.
“todo” : Action à faire prochainement.
“unmanaged” : Cas non géré, mais des données sont disponibles.
“suggested” : Action suggérée, mais non obligatoire.
“exception” : Cas non géré.
“contraindicated” : Action non recommandée.

Le détail par maladie comprend la maladie cible et le nombre d’actes de prévention effectués. Dans cet exemple, il s’agit de la diphtérie, pour laquelle 1 acte de prévention a été réalisé. Le champ “advice” contient tous les messages liés à la maladie, avec une conclusion indiquant que le patient est en retard (“late”) pour cette maladie. La “target_date” indique que le vaccin doit être réalisé à partir du 1er mars 2019, et la “limit_date” indique qu’il doit être réalisé avant le 31 mars 2019.

Le champ “messages” contient des indications supplémentaires pouvant être affichées aux professionnels de santé ou aux patients. Dans cet exemple, le message est destiné aux professionnels de santé et aux patients. Le champ “documents” contient des fichiers décrivant les recommandations officielles associées à la maladie.

Enfin le champ matching_conditions est un tableau d’ids de condition qui correspondent aux conditions qui ont eu un impact sur le résultat.