Demander un accès

Documentation développeur · API partenaire v1

Brancher votre logiciel sur le moteur de parcours Medicapp

Quatre étapes : créer ou retrouver le patient, déclencher le parcours, récupérer le lien sécurisé patient, suivre l'avancement. Votre application reste le point d'entrée de l'utilisateur ; Medicapp Pro orchestre le parcours médical.

Voir le Quickstart Comprendre les intégrations

L'API partenaire est ouverte progressivement à des partenaires identifiés. L'adresse de base et les codes d'accès sont communiqués à l'activation de l'accès.

Accès partenaire

Les accès à l'API partenaire Medicapp Pro sont délivrés après validation de l'organisation, du projet d'intégration et du périmètre nécessaire. Chaque partenaire dispose ensuite de credentials qui lui sont propres.

  1. Vous décrivez votre organisation, votre processus et le parcours à déclencher Partenaire
  2. Medicapp Connect valide l'organisation, le cas d'usage et le périmètre Medicapp
  3. Des credentials dédiés sont générés pour votre environnement Medicapp
  4. L'accès à l'environnement partenaire est activé, vous pouvez tester Partenaire

Cette validation préalable est la règle pour un traitement de données de santé : elle établit qui appelle l'API, pour quel usage et sur quel périmètre. Il n'y a pas de clé anonyme ni d'environnement de test ouvert en libre-service.

Demander un accès partenaire Vue d'ensemble des intégrations

Authentification

Chaque appel porte les codes d'accès (credentials) de votre environnement partenaire dans l'en-tête Authorization. Les accès partenaires sont authentifiés, isolés et tracés : un partenaire n'atteint que les dossiers et parcours relevant du périmètre validé pour lui.

En-tête requis 
Authorization: Bearer $MEDICAPP_PARTNER_TOKEN
Content-Type: application/json

L'adresse de base de l'API partenaire est communiquée avec vos codes d'accès. Dans les exemples ci-dessous, elle est notée $MEDICAPP_API.

Quickstart

Le scénario complet tient en quatre opérations. Votre application conserve son processus : elle ouvre le parcours au bon moment, présente le lien à l'utilisateur, puis suit son avancement.

Essayer ces appels · Accès partenaire requis

Pour exécuter ces appels, utilisez les credentials de votre environnement partenaire. Les requêtes et réponses présentées sur cette page sont des exemples de contrat d'API : elles ne sont pas exécutées depuis cette page.

Demander un accès

Ce que vous transmettez, ce que nous complétons

Votre plateforme connaît un adhérent : un nom d'usage, un e-mail, parfois un mobile. Nous collectons les informations nécessaires pour compléter son dossier médical (nom de naissance, prénoms d'état civil, commune de naissance, antécédants médicaux, documents justificatifs tels que ECG, prescription médicale...).

Le dossier créé par l'API entre donc au statut PENDING_COMPLETION. L'identité qualifiée se complète ensuite, soit par le patient lui-même dans le questionnaire d'admission, soit par le praticien dans Medicapp Pro.

Vous apportez l'identifiant et le lien. Nous qualifions l'identité.

Si vous disposez déjà de ces informations, un bloc facultatif (birthName, legalGivenNames, birthPlace, multipleBirth) évite une reprise manuelle côté praticien.

Opération 1 Périmètre v1

Créer ou retrouver le patient

Comment mes utilisateurs entrent-ils dans Medicapp sans double saisie ?

POST/partner/v1/patients 
curl -X POST "$MEDICAPP_API/partner/v1/patients" \
  -H "Authorization: Bearer $MEDICAPP_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trustSpaceId": "ts_8bb407fd-a943-40d5-882b-30d11ecb1b87",
    "externalId": {
      "issuer": "partner",
      "value": "PARTNER-84723",
      "label": "N° adhérent"
    },
    "identity": {
      "firstName": "Marie",
      "usedName": "Martin",
      "birthDate": "1985-03-12",
      "sex": "FEMALE"
    },
    "contact": {
      "email": "marie.martin@example.com",
      "mobilePhone": "+33612345678"
    }
  }'
200Exemple de réponse
{
  "patientId": "pat_63e2b4dd-06a8-4a12-1b75-f3a6976e97ee",
  "externalId": { "issuer": "partner",
                   "value": "PARTNER-84723" },
  "status": "PENDING_COMPLETION",
  "trustSpaceId": "ts_8bb407fd-…",
  "warnings": []
}

externalId : identifiant du patient ou participant dans votre système, associé à son émetteur. Il permet de conserver le lien entre les deux applications sans double saisie, et de retrouver le dossier sans stocker nos identifiants.

Idempotence. Un appel rejoué avec le même externalId renvoie 200 et le dossier existant — jamais une erreur. Un délai réseau suivi d'un rejeu ne crée donc pas de doublon et ne laisse pas votre système dans l'incertitude. Si le même identifiant est déjà porté par un autre dossier chez le même émetteur, il est signalé dans warnings sans bloquer la création : c'est un signal de doublon, arbitré par un humain.

mobilePhone : nécessaire si le protocole est configuré pour joindre le patient par SMS. Au moins un canal de contact est requis.

Opération 2 Périmètre v1

Déclencher le parcours

Comment lancer un parcours médical depuis mon application ?

POST/partner/v1/patients/{patientId}/protocols 
curl -X POST "$MEDICAPP_API/partner/v1/patients/pat_63e2b4dd-…/protocols" \
  -H "Authorization: Bearer $MEDICAPP_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "protocolId": "prot_a3f91c27-4b8e-4d12-9f03-77c5e1a2b8d4",
       "linkExpiresAt": "2026-10-17T23:59:59+02:00" }'
200Exemple de réponse
{
  "instanceId": "pri_c7b21e50-9a4f-4c33-bd18-2e5f6a9d0c11",
  "status": "PENDING",
  "links": [
    { "linkId": "lnk_e50268f0-…",
      "questionnaireShortTitle": "HADS",
      "title": "Échelle HADS",
      "protocolScheduleNumber": 1,
      "url": "https://…/medicappsurvey/form/e50268f0-…",
      "status": "PENDING",
      "expiresAt": "2026-10-17T23:59:59+02:00" },
    { "linkId": "lnk_a7f3c210-…",
      "questionnaireShortTitle": "EVA",
      "title": "Échelle visuelle analogique",
      "protocolScheduleNumber": 2,
      "url": "https://…/medicappsurvey/form/a7f3c210-…",
      "status": "PENDING",
      "expiresAt": "2026-10-17T23:59:59+02:00" }
  ],
  "skipped": []
}

Medicapp instancie le parcours et génère les étapes nécessaires. L'application partenaire récupère les liens sécurisés destinés au patient et les présente dans sa propre interface.

Un protocole produit un lien par questionnaire, pas un lien unique. protocolScheduleNumber donne l'ordre d'affichage attendu.

skipped : les questionnaires écartés et leur motif — déjà instancié pour ce patient, patient non éligible, protocole inactif. Ce n'est pas une erreur, mais un cas nominal : les autres questionnaires du protocole sont instanciés normalement. Ce retour vous permet de distinguer « rien à faire » d'un dysfonctionnement.

Opération 3 Périmètre v1

Présenter le lien au patient

Comment amener la personne à son étape sans la sortir de mon parcours utilisateur ?

  1. Votre application récupère le lien sécurisé patient Votre logiciel
  2. Elle l'affiche, par exemple « Compléter mon parcours médical » Votre logiciel
  3. Le patient accède à l'étape Medicapp qui le concerne Patient
  4. Il la complète depuis son mobile, sans créer de compte Patient

L'application partenaire reste le point d'entrée de l'utilisateur : le lien s'insère dans son espace, son courriel ou son message, sous sa propre formulation.

Opération 4 Périmètre v1

Suivre l'avancement

Où en est ce parcours, sans ouvrir Medicapp ?

GET/partner/v1/protocols/{instanceId} 
curl "$MEDICAPP_API/partner/v1/protocols/pri_c7b21e50-…" \
  -H "Authorization: Bearer $MEDICAPP_PARTNER_TOKEN"
200Exemple de réponse
{
  "instanceId": "pri_c7b21e50-…",
  "status": "OPENED",
  "links": [
    { "linkId": "lnk_e50268f0-…",
      "questionnaireShortTitle": "HADS",
      "status": "OPENED",
      "openedAt": "2026-09-17T09:12:04Z",
      "respondedAt": null },
    { "linkId": "lnk_a7f3c210-…",
      "questionnaireShortTitle": "EVA",
      "status": "PENDING",
      "openedAt": null,
      "respondedAt": null }
  ]
}
Statut Signification
PENDING Le parcours est instancié, l'étape attend la personne.
OPENED La personne a ouvert son étape.
COMPLETED Les étapes attendues ont été réalisées.
EXPIRED L'échéance est passée sans réalisation.

Ces statuts s'appliquent à chaque questionnaire. Le statut du parcours est agrégé : COMPLETED quand tous les questionnaires attendus sont terminés, EXPIRED si l'échéance est passée avec au moins un questionnaire non rempli, OPENED dès qu'un questionnaire a été ouvert, PENDING sinon. Le détail par questionnaire reste disponible dans links, c'est lui qui vous permet de relancer.

Suivez l'avancement du parcours sans avoir à manipuler les données médicales collectées.

Périmètre de la v1

L'API partenaire v1 permet de piloter et de suivre un parcours : créer ou retrouver le patient, déclencher le parcours, obtenir le lien sécurisé patient, consulter l'état et la complétude.

Les réponses aux questionnaires, les scores, les pièces et les documents médicaux ne sont pas restitués par l'API partenaire dans cette version : ils restent dans Medicapp Pro, consultés par les professionnels habilités, sur une infrastructure certifiée HDS. Votre application n'a donc pas à héberger ni transporter de contenu médical pour conduire son processus.

Après la v1

Campagnes Après la v1

Ouvrir en un appel un ensemble de parcours rattachés à un même protocole, avec une échéance commune, et suivre l'avancement du lot. Aujourd'hui, cette opération se fait par import de liste depuis l'application.

Événements Après la v1

Notification vers une adresse de votre choix lorsqu'un parcours change d'état. En attendant, l'interrogation périodique du statut couvre l'essentiel des besoins.

Nous n'annonçons pas de date tant que nous ne pouvons pas la tenir. Si l'une de ces capacités conditionne votre projet, écrivez-nous : cela pèse dans nos priorités.

Erreurs

Code Signification Ce qu'il faut vérifier
401 Credentials absents ou invalides En-tête Authorization: Bearer … présent, credentials non révoqués.
403 Hors périmètre L'appel porte sur une ressource ou une opération qui ne relève pas du périmètre validé pour votre accès.
404 Ressource introuvable Identifiant erroné, ou ressource hors du périmètre accessible à votre accès.
400 Requête invalide Champ obligatoire manquant, valeur non reconnue, ou identifiant mal formé — le champ fautif est nommé dans la réponse.
429 Trop d'appels Respecter l'en-tête Retry-After.

Pas de conflit, par conception. Créer un patient déjà connu n'est pas une erreur : l'appel est idempotent et renvoie le dossier existant. Déclencher un parcours dont une partie est déjà instanciée n'en est pas une non plus : les questionnaires concernés apparaissent dans skipped et les autres sont instanciés. Vous pouvez donc rejouer un appel après un délai réseau sans risque de doublon.

Interopérabilité HL7 / FHIR

Les besoins HL7/FHIR sont étudiés selon le contexte d'intégration, les systèmes concernés et le périmètre de données nécessaire. Décrivez votre contexte pour que nous examinions ce qui est pertinent.

Passer en production

Le passage à la production s'appuie sur quatre éléments, qui encadrent le traitement des données de santé. Ils se préparent en parallèle de votre intégration technique.

  1. Un cadre contractuel entre votre organisation et Medicapp Connect
  2. Le périmètre d'intégration arrêté : parcours concernés, volumétrie, durée
  3. Un engagement de sécurité sur les données échangées et leur conservation
  4. Des credentials de production, distincts de ceux de votre environnement de recette
Parler de votre projet d'intégration Documentation de conformité