API Colibri - Service de recherche de dossier patient

URL racine du service

Le protocole de communication est HTTPS.

Serveur de production
Toutes les URLs commencent par https://colibri.mesvaccins.net/.
Serveur de test
Toutes les URLs commencent par https://test-colibri.mesvaccins.net/

Cas d’usage : liaison d’un logiciel métier vers Colibri

L’utilisateur final est un professionnel de santé connecté dans un logiciel métier différent de Colibri. Il veut passer d’un dossier patient hébergé dans ce logiciel métier, qu’on appellera DPM (Dossier Patient Maître) au dossier du même patient dans Colibri, qu’on appellera DPC (Dossier Patient Colibri).

Pour cela, cet utilisateur doit pouvoir manuellement associer, dans un DPM, le DPC correspondant. Pour trouver le DPC à associer, l’utilisateur doit être en mesure d’interroger, à travers le logiciel métier, le service de recherche de dossiers patient de Colibri qui lui retournera, sur la base du nom, du prénom et de la date de naissance, le ou les dossier(s) patient correspondant(s) dans la base de données de Colibri. Une fois le DPC manuellement sélectionné et confirmé par l’utilisateur, son identifiant et son URL doivent être persistés localement par le logiciel métier.

Notes

  • Aucune trace de cette association n’est persistée dans la base de données de Colibri ;
  • Il est suggéré à l’éditeur du logiciel métier de permettre à l’utilisateur de modifier ou supprimer cette association.

Description

Le service est exposé sous la forme d’un service GET accessible à l’URL relative suivante :

  • GET /api/patients/search retourne les résultats de la recherche

Ce service reçoit en entrée les données suivantes : nom, prénom, date de naissance.

Il retourne en sortie les dossiers patient correspondants ainsi qu’un score de recherche pour chaque dossier.

Format d’entrée

Les paramètres d’entrée sont passés dans la chaîne de requête de l’URL complète. Voici un exemple de requête de recherche :

GET https://test-colibri.mesvaccins.net/api/patients/search?birth_date=1985-12-16&first_name=Archibald&last_name=Haddock

Au moins l’un des paramètres d’entrée doit être présent dans la chaîne de requête.

Le format précis de chaque paramètre dans la chaîne de requête est le suivant :

Paramètre Format
birth_date Date au format ISO 8601
first_name Chaîne unicode
last_name Chaîne unicode

Échappement des paramètres

Les paramètres d’entrée doivent être correctement échappés, par exemple comme suit pour une requête avec le prénom Évrard :

GET https://test-colibri.mesvaccins.net/api/patients/search?first_name=%C3%89vrard

Format de sortie

Le service retourne un objet JSON contenant un tableau de résultats de recherche indexé par la clé search_results. Chaque élément du tableau de résultats de recherche contient un score de recherche numérique et les données de base du dossier patient associé. Le score de recherche est plus ou mois élevé selon la correspondance entre les paramètres de recherche et les données du dossier patient associé.

{
    "search_results": [
        {
            "score": 100,
            "patient": {
                "id": 128,
                "first_name": "Archibald",
                "last_name": "Haddock",
                "birth_date": "1988-12-18"
            }
        },
        {
            "score": 80,
            "patient": {
                "id": 256,
                "first_name": "Archibold",
                "last_name": "Hadduck",
                "birth_date": "1988-05-02"
            }
        }
    ]
}

Chaque dossier patient est représenté par un objet JSON contenant les valeurs de base du dossier, dont l’identifiant numérique (qui permettra de faire le lien entre Atyl et Colibri). Le format exact des données de sortie est à préciser.

Remarque : les résultats de recherche sont triés par score décroissant.

Attribut Description Format
search_results Tableau contenant les résultats de la recherche, tels que décrits dans les lignes suivantes : Tableau
score Entité numérique comprise entre 0 et 100, qui exprime un pourcentage de pertinence du résultat par rapport aux paramètres recherchés Numérique
patient Objet JSON contenant les attributs de base du DPC, décrits dans les lignes suivantes : Objet
id Identifiant numérique du Dossier Patient Colibri Numérique
birth_date Date de naissance Chaîne de caractères au format ISO 8601
first_name Prénom Chaîne de caractères au format unicode
last_name Nom d'usage Chaîne de caractères au format unicode

Conditions d’erreurs

L’absence de résultats se manifeste par le retour d’une réponse où le tableau contenu dans search_results est vide :

{
    "search_results": []
}

En cas d’erreur, le service renvoie un objet tel que décrit dans la rubrique Messages flash.

Les statuts des réponses HTTP signalant une erreur peuvent notamment être :

  • 401 Unauthorized si l’authentification du logiciel client est insuffisante ; se référer à la rubrique Authentification et autorisation

  • 400 Bad request si au moins un des paramètres d’entrée a été transmis selon un format invalide ; se référer à la rubrique Format d’entrée

Authentification et autorisation

Les requêtes envoyées par le logiciel tiers au service de recherche devront être authentifiées à l’aide d’un certificat x509 dit « certificat d’application » spécifique au logiciel tiers.
Du côté de Colibri, le service de recherche de patient aura un périmètre limité aux dossiers de l’utilisateur du logiciel tiers.

Les modalités d’authentification peuvent être amenées à évoluer lors du développement.