API & Dev — Documentation de l'API partenaire Medicapp Pro

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.

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

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

Authentification et sécurité

L'API partenaire repose sur OAuth 2.0 : votre plateforme s'authentifie de machine à machine avec des codes d'accès qui lui sont propres, et obtient un jeton à durée de vie limitée qui accompagne chaque appel.

POST/partner/v1/oauth/token

curl -X POST "$MEDICAPP_API/partner/v1/oauth/token" \
  -u "$MEDICAPP_CLIENT_ID:$MEDICAPP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

200Exemple de réponse

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "patient:write patient:read protocol:read protocol:start protocol:track"
}

En-têtes des appels métier

Authorization: Bearer $MEDICAPP_PARTNER_TOKEN
Content-Type: application/json

Un périmètre par contexte. Vos droits sont accordés contexte par contexte — un client, un établissement, un programme — et opération par opération. Un appel hors de ce périmètre n'atteint rien.
Des accès isolés et tracés. Chaque appel est journalisé et rattaché à votre accès.
Révocation immédiate. Un accès révoqué ou suspendu cesse d'être accepté sans attendre l'expiration des jetons déjà émis ; la rotation des identifiants se fait sans coupure.

Quickstart

Une intégration complète tient en quelques appels.

S'authentifier
Obtenir un jeton avec vos codes d'accès.
Créer ou retrouver le patient
À partir de votre propre identifiant.
Choisir le protocole
Parmi ceux que votre client a ouverts à l'intégration.
Déclencher le parcours
Et récupérer les liens sécurisés destinés au patient.
Suivre l'avancement
Questionnaire par questionnaire.

Documentation complète · Accès partenaire requis

Le guide d'intégration détaillé — requêtes, réponses, codes d'erreur — et la spécification OpenAPI sont remis avec votre accès partenaire.

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édents médicaux, documents justificatifs tels que ECG, prescription médicale…).

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

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": {
      "value": "AB-84723",
      "label": "N° adhérent"
    },
    "identity": {
      "firstName": "Marie",
      "usedName": "Martin",
      "birthDate": "1985-03-12",
      "sex": "FEMALE"
    },
    "contact": {
      "email": "marie.martin@example.com",
      "mobilePhone": "+33612345678"
    }
  }'

201Exemple de réponse

{
  "patientId": "pat_63e2b4dd-06a8-4a12-1b75-f3a6976e97ee",
  "externalId": { "issuer": "ACME",
                   "value": "AB-84723" },
  "recordStatus": "REVIEW_REQUIRED",
  "trustSpaceId": "ts_8bb407fd-a943-40d5-882b-30d11ecb1b87",
  "workflowStatuses": [],
  "warnings": []
}

Vous transmettez votre propre identifiant de la personne, son identité et au moins un moyen de contact. Medicapp crée le dossier, ou retrouve celui qui existe déjà : vous n'avez pas à stocker nos identifiants pour retrouver un patient.

Rejouer sans crainte. L'appel est idempotent : après un délai réseau, le rejouer ne crée pas de doublon. Une même personne présente dans plusieurs contextes d'un même client garde un seul dossier.

Opération 2 Périmètre v1

Déclencher le parcours

Comment lancer un parcours médical depuis mon application ?

GET/partner/v1/protocols?trustSpaceId=…

curl "$MEDICAPP_API/partner/v1/protocols?trustSpaceId=ts_8bb407fd-…" \
  -H "Authorization: Bearer $MEDICAPP_PARTNER_TOKEN"

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 '{ "trustSpaceId": "ts_8bb407fd-a943-40d5-882b-30d11ecb1b87",
       "protocolId": "prot_a3f91c27-4b8e-4d12-9f03-77c5e1a2b8d4" }'

201Exemple de réponse

{
  "instanceId": "pri_c7b21e50-9a4f-4c33-bd18-2e5f6a9d0c11",
  "patientId": "pat_63e2b4dd-…",
  "protocolId": "prot_a3f91c27-…",
  "progressStatus": "PENDING",
  "instantiatedAt": "2026-10-02T10:15:00+02:00",
  "links": [
    { "linkId": "lnk_e50268f0-…",
      "questionnaireShortTitle": "HADS",
      "title": "Échelle HADS",
      "protocolScheduleNumber": 1,
      "groupId": "…",
      "url": "https://…/medicappsurvey/form/e50268f0-…",
      "progressStatus": "PENDING",
      "respondedAt": null },
    { "linkId": "lnk_a7f3c210-…",
      "questionnaireShortTitle": "EVA",
      "title": "Échelle visuelle analogique",
      "protocolScheduleNumber": 2,
      "groupId": "…",
      "url": "https://…/medicappsurvey/form/a7f3c210-…",
      "progressStatus": "PENDING",
      "respondedAt": null }
  ],
  "skipped": [],
  "workflowStatuses": [],
  "warnings": []
}

Votre application désigne le protocole à suivre — celui que votre client a paramétré dans Medicapp Pro. Medicapp instancie le parcours et rend un lien sécurisé par questionnaire, avec l'ordre d'affichage attendu.

Medicapp n'envoie rien au patient sur ce chemin : c'est votre application qui présente les liens, sauf si votre client a activé un rappel par e-mail. Comme la création du patient, le déclenchement peut être rejoué sans créer de doublon.

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 ?

Votre application récupère le lien sécurisé patient Votre logiciel
Elle l'affiche, par exemple « Compléter mon parcours médical » Votre logiciel
Le patient accède à l'étape Medicapp qui le concerne Patient
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}?trustSpaceId=…

curl "$MEDICAPP_API/partner/v1/protocols/pri_c7b21e50-…?trustSpaceId=ts_8bb407fd-…" \
  -H "Authorization: Bearer $MEDICAPP_PARTNER_TOKEN"

200Exemple de réponse

{
  "instanceId": "pri_c7b21e50-…",
  "patientId": "pat_63e2b4dd-…",
  "protocolId": "prot_a3f91c27-…",
  "progressStatus": "OPENED",
  "links": [
    { "linkId": "lnk_e50268f0-…",
      "questionnaireShortTitle": "HADS",
      "progressStatus": "COMPLETED",
      "respondedAt": "2026-10-03T09:12:04+02:00" },
    { "linkId": "lnk_a7f3c210-…",
      "questionnaireShortTitle": "EVA",
      "progressStatus": "PENDING",
      "respondedAt": null }
  ],
  "workflowStatuses": [
    { "code": "st_01_adm", "label": "Admission", "value": "À valider" }
  ],
  "warnings": []
}

Statut	Signification
`PENDING`	Le parcours est instancié, l'étape attend la personne.
`OPENED`	La personne a ouvert son étape.
`COMPLETED`	Le questionnaire a été rempli.
`EXPIRED`	L'échéance est passée sans réponse.

Ces statuts sont rendus pour chaque questionnaire et pour le parcours dans son ensemble : vous savez qui relancer, et quand. Les étapes métier définies par votre client (admission validée, dossier complet…) sont restituées à côté, telles qu'il les a paramétrées.

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

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.

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

Parler de votre projet d'intégration Documentation de conformité

Brancher votre logiciel sur le moteur de parcours Medicapp