Exemple d’appel

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 Mentor, l’interface de référence du SADV. Elle est accessible publiquement via un navigateur web, sans création de compte ni authentification. Elle sert à démontrer et évaluer le parcours utilisateur attendu et les bonnes pratiques d’intégration, dans un fonctionnement proche de celui d’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. Elles 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 à la librairie VaccinationProfile (Bibliothèque PHP).

É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
ACCESS_TOKEN=...

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

curl -X POST "${SADV_ROOT_URL}/questionnaire" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-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 questions 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, l’interface de référence accessible publiquement sans authentification.

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 objet 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 condition dans 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 suffit 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 obligatoire pour chaque acte afin de définir s’il s’agit d’un 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",
        "booster": false
      }
    ],
    "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
ACCESS_TOKEN=...

curl -X POST "${SADV_ROOT_URL}/diagnostic_for_patient" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-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": [
          {
            "id": "3e76320a-0b4d-4cb2-8095-764b19b08017",
            "label": {
              "en": "Pregnancy",
              "fr": "Grossesse"
            },
            "position": 1,
            "condition_type": "boolean",
            "help": {
              "en": "Influencing condition",
              "fr": "Condition influente"
            }
          }
        ],
        "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ée selon la priorité du statut d’une maladie par rapport 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 un 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 “targeted_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’objets Condition correspondant aux conditions ayant eu un impact sur le résultat.

Étape suivante

Consultez la spécification OpenAPI pour les endpoints, schémas JSON et statuts d’erreur.

Spécification OpenAPI