Aller au contenu

HDS

Appeler le module de données de santé par l'API publique, rôles HDS requis, chemins disponibles et principaux endpoints des coffres et documents.

RéférenceDéveloppeur
Voir en Markdown

Le module HDS stocke et partage des données de santé dans un cadre certifié : des coffres contiennent des documents chiffrés et versionnés, partagés avec des utilisateurs, des équipes ou des rôles. Toutes ses opérations passent par l'API publique sous le préfixe /api/hds. Le fonctionnement du module et ses guides sont dans Données de santé (HDS).

Conditions d'accès

  • L'application doit être déclarée HDS, ce qui se fait depuis la console.
  • L'appelant doit porter au moins un rôle HDS parmi HDS_ADMIN, HDS_HEALTHCARE, HDS_MEDICAL, HDS_PATIENT, HDS_STORAGE et HDS_DELETE. Chaque opération exige ensuite une permission précise, indiquée avec elle.
  • Authentifiez l'appel avec le jeton Keycloak de l'utilisateur, dans Authorization : le jeton enrichi ne porte pas les rôles HDS.

Les données sont cloisonnées par client : un utilisateur ne voit que les coffres de son client.

Rôles HDS

RôleCe qu'il permet
HDS_ADMINToutes les opérations, y compris l'administration et le journal d'audit
HDS_HEALTHCARECréer et lire des coffres, déposer et lire des documents, partager, recueillir un consentement, accès d'urgence, recherche, export FHIR
HDS_MEDICALLire coffres, documents, dossiers et consentements ; liens de téléchargement ; recherche ; export FHIR
HDS_PATIENTLire ses coffres et les exporter, déposer et lire des documents, recherche
HDS_STORAGECréer et lire des coffres, gérer documents et dossiers, lire les partages, recherche
HDS_DELETESupprimer documents, coffres et dossiers ; révoquer des partages

Conventions propres au module

SujetRègle
Préfixehttps://api.wakastart.app/api/hds/…
CheminsLes chemins décrits sur cette page, sous /vaults, /shares, /break-glass, /audit-logs, /compliance, /access-reviews, /search et /fhir. Un chemin non autorisé, ou contenant .., donne 403 HDS path not allowed
Format des erreursLe corps d'erreur du module est renvoyé tel quel : { "statusCode", "message", "error" }
PaginationPar curseur : limit (défaut 20, 100 au plus) et cursor
IdempotenceEn-tête Idempotency-Key sur POST, PUT et PATCH ; réponse rejouée 24 heures avec X-Idempotency-Replayed: true
Fichiersmultipart/form-data, champ file, 100 Mo au plus
Délai30 secondes de traitement (408 Request timed out au-delà)
Débit100 requêtes par minute

L'objet Coffre

ChampTypeDescription
idchaîneIdentifiant, préfixé vlt_
typechaînePATIENT (dossier d'un patient), STRUCTURAL (d'une équipe), RESEARCH (étude, sans patient) ou TEMPORARY
labelchaîne (255)Libellé
statuschaîneACTIVE, ARCHIVED, SUSPENDED ou DELETED
ownerId, ownerTeamIdchaînePropriétaire ; équipe propriétaire pour un coffre STRUCTURAL
patientobjetexternalId, ins, firstName, lastName, birthDate, pour un coffre PATIENT
retentionPolicychaîneSTANDARD, EXTENDED, LEGAL_HOLD ou CUSTOM
storageUsedBytes, documentCountentierOccupation
expiresAtchaîne ISO 8601 ou nullÉchéance, obligatoire pour TEMPORARY

L'objet Document

ChampTypeDescription
idchaîneIdentifiant, préfixé doc_
statuschaîneACTIVE, ARCHIVED, SOFT_DELETED, QUARANTINED, SEALED ou DELETED
currentVersionentierVersion courante
versionstableau{ version, sizeBytes, hashSha256, uploadedAt, uploadedBy, comment }
antivirusStatuschaînePENDING, CLEAN, INFECTED ou QUARANTINED
legalHoldbooléenConservation légale : le document ne peut pas être supprimé

Créer un coffre

POST/api/hds/vaults

Permission : création de coffre (HDS_HEALTHCARE, HDS_STORAGE, HDS_ADMIN).

ChampTypeObligatoireRègle
typechaîneouiPATIENT, STRUCTURAL, RESEARCH, TEMPORARY
labelchaîneoui255 caractères au plus
patientobjetpour PATIENTInterdit pour RESEARCH
ownerTeamIdchaînepour STRUCTURAL—
expiresAtchaîne ISO 8601pour TEMPORARYEntre 24 heures et 90 jours
retentionPolicychaînenon—
defaultFolderstableau de chaînesnonDossiers créés d'office
metadataobjetnon—
Bash
curl -s -X POST https://api.wakastart.app/api/hds/vaults \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f1c9b2e-0d4a-4c7e-9b1a-5e6f7a8b9c0d" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PATIENT",
    "label": "Dossier de Jeanne Exemple",
    "patient": { "externalId": "PAT-0042", "firstName": "Jeanne", "lastName": "Exemple", "birthDate": "1980-04-12" },
    "defaultFolders": ["Ordonnances", "Comptes rendus"]
  }'

Réponse 201 : l'objet Coffre, au statut ACTIVE, dont l'appelant est propriétaire.

Erreurs : 400 Vault quota exceeded: <n>/<max> ; 403 Insufficient HDS permissions for this operation.

Déposer un document

POST/api/hds/vaults/{vaultId}/documents

Permission : dépôt (HDS_HEALTHCARE, HDS_PATIENT, HDS_STORAGE, HDS_ADMIN). Corps multipart/form-data : file (100 Mo au plus), comment et folderId facultatifs.

Bash
curl -s -X POST https://api.wakastart.app/api/hds/vaults/vlt_8f2a1c/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@compte-rendu.pdf" \
  -F "comment=Consultation du 23 octobre"

Le fichier est analysé par l'antivirus puis chiffré. Un fichier déjà présent dans le coffre (même empreinte) n'est pas dupliqué : la réponse renvoie le document existant avec deduplicated: true. Si l'analyse n'est pas terminée, le document est créé au statut QUARANTINED.

Erreurs : 400 Infected file detected — upload denied ; 400 Document quota exceeded: <n>/<max> ; 413 Storage quota exceeded.

Autres opérations

OpérationMéthode et chemin (sous /api/hds)Permission principale
Lister ses coffres (possédés et partagés)GET /vaults (type, status, search, limit, cursor)Lecture de coffre
Lire, modifier un coffreGET /vaults/{id}, PATCH /vaults/{id} (label, metadata, status)Lecture ; propriétaire pour modifier
Sceller un coffrePOST /vaults/{id}/sealPropriétaire
Exporter les métadonnées d'un coffreGET /vaults/{id}/exportHDS_PATIENT, HDS_ADMIN
Supprimer un coffreDELETE /vaults/{id}HDS_DELETE, HDS_ADMIN
Lister, lire, supprimer des documentsGET /vaults/{vaultId}/documents, GET …/documents/{id}, DELETE …/documents/{id}Lecture ; suppression
Gérer les versionsPOST …/documents/{id}/versions, GET …/documents/{id}/versions, POST …/documents/{id}/versions/{v}/rollbackDépôt ; lecture
Lien de téléchargementPOST …/documents/{id}/presign (expiresInSeconds de 60 à 3 600, défaut 300 ; version)Lien de téléchargement
VignetteGET …/documents/{id}/thumbnailLien de téléchargement
DossiersGET, POST, PATCH, DELETE /vaults/{vaultId}/folders…Dossiers
PartagesPOST /shares (vaultId, cible utilisateur, équipe ou rôle, level READ, READ_WRITE ou FULL_CONTROL, expiresAt), GET /shares, DELETE /shares/{id}Propriétaire, HDS_HEALTHCARE, HDS_ADMIN
ConsentementsPOST, GET, DELETE /vaults/{vaultId}/consentsHDS_HEALTHCARE pour recueillir
Accès d'urgencePOST /break-glass (justification de 20 caractères au moins)HDS_HEALTHCARE
RechercheGET /search/documents, GET /search/vaults (q, limit, cursor…)Recherche
Export FHIRGET /fhir/…Export FHIR
Journal d'audit HDSGET /audit-logs, GET /audit-logs/integrity-checkHDS_ADMIN
Rapports de conformitéGET /compliance/rgpd, /compliance/hds, /compliance/nis2 ; POST /compliance/reportsConformité
Revues d'accès/access-reviewsRevue d'accès

Un document supprimé passe en DELETED et est purgé définitivement 30 jours plus tard, à la date hardDeleteScheduledAt. Un document sous conservation légale ou scellé ne peut pas être supprimé : 403 Cannot delete document under legal hold ou Cannot delete sealed document.

Erreurs propres au relais

StatutMessageCause
403Rôle(s) HDS requis: HDS_ADMIN, HDS_HEALTHCARE, HDS_MEDICAL, HDS_PATIENT, HDS_STORAGE, HDS_DELETE (mode: any)L'appelant ne porte aucun rôle HDS, ou s'est authentifié avec le seul jeton enrichi
403HDS path not allowedChemin hors liste
503HDS service unavailableModule momentanément indisponible
503Auth check unavailableVérification de révocation indisponible ; réessayez