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.
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_STORAGEetHDS_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ôle | Ce qu'il permet |
|---|---|
HDS_ADMIN | Toutes les opérations, y compris l'administration et le journal d'audit |
HDS_HEALTHCARE | Créer et lire des coffres, déposer et lire des documents, partager, recueillir un consentement, accès d'urgence, recherche, export FHIR |
HDS_MEDICAL | Lire coffres, documents, dossiers et consentements ; liens de téléchargement ; recherche ; export FHIR |
HDS_PATIENT | Lire ses coffres et les exporter, déposer et lire des documents, recherche |
HDS_STORAGE | Créer et lire des coffres, gérer documents et dossiers, lire les partages, recherche |
HDS_DELETE | Supprimer documents, coffres et dossiers ; révoquer des partages |
Conventions propres au module
| Sujet | Règle |
|---|---|
| Préfixe | https://api.wakastart.app/api/hds/… |
| Chemins | Les 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 erreurs | Le corps d'erreur du module est renvoyé tel quel : { "statusCode", "message", "error" } |
| Pagination | Par curseur : limit (défaut 20, 100 au plus) et cursor |
| Idempotence | En-tête Idempotency-Key sur POST, PUT et PATCH ; réponse rejouée 24 heures avec X-Idempotency-Replayed: true |
| Fichiers | multipart/form-data, champ file, 100 Mo au plus |
| Délai | 30 secondes de traitement (408 Request timed out au-delà) |
| Débit | 100 requêtes par minute |
L'objet Coffre
| Champ | Type | Description |
|---|---|---|
id | chaîne | Identifiant, préfixé vlt_ |
type | chaîne | PATIENT (dossier d'un patient), STRUCTURAL (d'une équipe), RESEARCH (étude, sans patient) ou TEMPORARY |
label | chaîne (255) | Libellé |
status | chaîne | ACTIVE, ARCHIVED, SUSPENDED ou DELETED |
ownerId, ownerTeamId | chaîne | Propriétaire ; équipe propriétaire pour un coffre STRUCTURAL |
patient | objet | externalId, ins, firstName, lastName, birthDate, pour un coffre PATIENT |
retentionPolicy | chaîne | STANDARD, EXTENDED, LEGAL_HOLD ou CUSTOM |
storageUsedBytes, documentCount | entier | Occupation |
expiresAt | chaîne ISO 8601 ou null | Échéance, obligatoire pour TEMPORARY |
L'objet Document
| Champ | Type | Description |
|---|---|---|
id | chaîne | Identifiant, préfixé doc_ |
status | chaîne | ACTIVE, ARCHIVED, SOFT_DELETED, QUARANTINED, SEALED ou DELETED |
currentVersion | entier | Version courante |
versions | tableau | { version, sizeBytes, hashSha256, uploadedAt, uploadedBy, comment } |
antivirusStatus | chaîne | PENDING, CLEAN, INFECTED ou QUARANTINED |
legalHold | booléen | Conservation légale : le document ne peut pas être supprimé |
Créer un coffre
/api/hds/vaultsPermission : création de coffre (HDS_HEALTHCARE, HDS_STORAGE, HDS_ADMIN).
| Champ | Type | Obligatoire | Règle |
|---|---|---|---|
type | chaîne | oui | PATIENT, STRUCTURAL, RESEARCH, TEMPORARY |
label | chaîne | oui | 255 caractères au plus |
patient | objet | pour PATIENT | Interdit pour RESEARCH |
ownerTeamId | chaîne | pour STRUCTURAL | — |
expiresAt | chaîne ISO 8601 | pour TEMPORARY | Entre 24 heures et 90 jours |
retentionPolicy | chaîne | non | — |
defaultFolders | tableau de chaînes | non | Dossiers créés d'office |
metadata | objet | non | — |
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
/api/hds/vaults/{vaultId}/documentsPermission : dépôt (HDS_HEALTHCARE, HDS_PATIENT, HDS_STORAGE, HDS_ADMIN). Corps multipart/form-data : file (100 Mo au plus), comment et folderId facultatifs.
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ération | Mé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 coffre | GET /vaults/{id}, PATCH /vaults/{id} (label, metadata, status) | Lecture ; propriétaire pour modifier |
| Sceller un coffre | POST /vaults/{id}/seal | Propriétaire |
| Exporter les métadonnées d'un coffre | GET /vaults/{id}/export | HDS_PATIENT, HDS_ADMIN |
| Supprimer un coffre | DELETE /vaults/{id} | HDS_DELETE, HDS_ADMIN |
| Lister, lire, supprimer des documents | GET /vaults/{vaultId}/documents, GET …/documents/{id}, DELETE …/documents/{id} | Lecture ; suppression |
| Gérer les versions | POST …/documents/{id}/versions, GET …/documents/{id}/versions, POST …/documents/{id}/versions/{v}/rollback | Dépôt ; lecture |
| Lien de téléchargement | POST …/documents/{id}/presign (expiresInSeconds de 60 à 3 600, défaut 300 ; version) | Lien de téléchargement |
| Vignette | GET …/documents/{id}/thumbnail | Lien de téléchargement |
| Dossiers | GET, POST, PATCH, DELETE /vaults/{vaultId}/folders… | Dossiers |
| Partages | POST /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 |
| Consentements | POST, GET, DELETE /vaults/{vaultId}/consents | HDS_HEALTHCARE pour recueillir |
| Accès d'urgence | POST /break-glass (justification de 20 caractères au moins) | HDS_HEALTHCARE |
| Recherche | GET /search/documents, GET /search/vaults (q, limit, cursor…) | Recherche |
| Export FHIR | GET /fhir/… | Export FHIR |
| Journal d'audit HDS | GET /audit-logs, GET /audit-logs/integrity-check | HDS_ADMIN |
| Rapports de conformité | GET /compliance/rgpd, /compliance/hds, /compliance/nis2 ; POST /compliance/reports | Conformité |
| Revues d'accès | /access-reviews | Revue 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
| Statut | Message | Cause |
|---|---|---|
403 | Rô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 |
403 | HDS path not allowed | Chemin hors liste |
503 | HDS service unavailable | Module momentanément indisponible |
503 | Auth check unavailable | Vérification de révocation indisponible ; réessayez |