Référence du module HDS
Authentification, permissions par rôle, objets, statuts, opérations, erreurs et limites du module de données de santé.
Toutes les opérations passent par l'API publique, sous le préfixe https://api.wakastart.app/api/hds. Les endpoints sont aussi décrits dans la référence API — HDS.
Authentification
| Élément | Valeur |
|---|---|
| En-tête | Authorization: Bearer <jeton d'accès Keycloak de l'utilisateur, émis pour l'application> |
| Rôle minimal | au moins un rôle HDS ; sinon 403 |
Clés API sk_… | non acceptées : elles ne portent pas de rôle HDS |
| Espace | celui du client de l'utilisateur, déduit du jeton |
| Format des corps | JSON, ou multipart/form-data pour les fichiers |
Permissions par rôle
| Opération | ADMIN | HEALTHCARE | MEDICAL | PATIENT | STORAGE | DELETE |
|---|---|---|---|---|---|---|
| Lire coffres, documents, dossiers | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Créer un coffre | ✓ | ✓ | ✓ | |||
| Modifier un coffre (propriétaire) | ✓ | |||||
| Supprimer un coffre (propriétaire) | ✓ | ✓ | ||||
| Exporter un coffre | ✓ | ✓ | ||||
| Déposer un document | ✓ | ✓ | ✓ | ✓ | ||
| Supprimer un document | ✓ | ✓ | ||||
| Créer, renommer un dossier, y ranger un document | ✓ | ✓ | ✓ | |||
| Supprimer un dossier | ✓ | ✓ | ||||
| Lire les partages | ✓ | ✓ | ✓ | |||
| Créer un partage | ✓ | ✓ | ||||
| Révoquer un partage (auteur) | ✓ | ✓ | ||||
| Lire les consentements | ✓ | ✓ | ✓ | ✓ | ||
| Enregistrer un consentement | ✓ | ✓ | ||||
| Activer un accès d'urgence | ✓ | ✓ | ||||
| Lire, révoquer les accès d'urgence | ✓ | |||||
| Journal d'audit, intégrité, rapports, revues, alertes, sauvegardes, espace | ✓ |
En plus du rôle, toute opération sur un coffre exige d'en être propriétaire ou destinataire d'un partage actif.
Objets
Espace
| Champ | Description |
|---|---|
networkWid | WID du client. |
status | PROVISIONING, ACTIVE, DECOMMISSIONING, DECOMMISSIONED. |
storageQuotaBytes | Quota de stockage, 10 737 418 240 (10 Go) par défaut. |
maxVaults | Nombre maximal de coffres, 1 000 par défaut. |
maxDocuments | Nombre maximal de documents, 50 000 par défaut. |
provisionedAt | Date d'activation. |
Coffre
| Champ | Description |
|---|---|
vaultId | Identifiant vlt_…. |
type | PATIENT, STRUCTURAL, RESEARCH, TEMPORARY. |
status | ACTIVE, ARCHIVED, SUSPENDED, DELETED. |
label | Libellé, 255 caractères au plus. |
ownerId | Identifiant Keycloak du propriétaire. |
ownerTeamId | Équipe propriétaire (STRUCTURAL). |
patient | externalId, ins, firstName, lastName, birthDate (PATIENT). |
pseudonymizedPatientId | Référence pseudonymisée, ou null. |
metadata | Paires clé-valeur libres. |
storageUsedBytes, documentCount | Volume et nombre de documents du coffre. |
retentionPolicy | STANDARD, EXTENDED, LEGAL_HOLD, CUSTOM. |
expiresAt | Date de fin (TEMPORARY), ou null. |
createdAt, updatedAt | Dates. |
Document
| Champ | Description |
|---|---|
docId | Identifiant doc_…. |
vaultId, folderId | Coffre et dossier (null à la racine). |
originalFilename, mimeType, sizeBytes | Nom, type et taille du fichier d'origine. |
status | Voir statuts d'un document. |
currentVersion | Numéro de la version courante. |
versions | Historique : version, sizeBytes, uploadedAt, uploadedBy, comment (et hashSha256 dans l'historique dédié). |
hashSha256 | Empreinte SHA-256 du fichier d'origine (détail). |
antivirusStatus | Résultat du contrôle antivirus au dépôt. |
tags, medicalMetadata, customMetadata | Métadonnées. |
uploadedBy | Identifiant Keycloak de l'auteur du dépôt. |
legalHold | true si le document est sous conservation légale. |
deduplicated | true si le dépôt a renvoyé un document existant (réponse de dépôt uniquement). |
Dossier
| Champ | Description |
|---|---|
folderId | Identifiant fld_…. |
vaultId, parentFolderId | Coffre et dossier parent (null à la racine). |
name, sortOrder | Nom (255 caractères) et ordre d'affichage. |
createdBy, createdAt, updatedAt | Auteur et dates. |
Partage
| Champ | Description |
|---|---|
shareId | Identifiant shr_…. |
vaultId | Coffre partagé. |
targetUserId | Identifiant Keycloak du destinataire. |
level | READ, READ_WRITE, FULL_CONTROL. |
grantedBy | Auteur du partage ; BREAK_GLASS_SYSTEM pour un accès d'urgence. |
active | false après révocation. |
revokedAt, revokedBy | Révocation. |
Consentement
| Champ | Description |
|---|---|
consentId | Identifiant cst_…. |
vaultId, patientId | Coffre et patient. |
purpose, scope, scopeDetail | Finalité et périmètre. |
collectionMethod, collectedAt, collectedBy | Recueil. |
status | ACTIVE, WITHDRAWN, EXPIRED. |
expiresAt | Fin de validité convenue, ou null. |
withdrawnAt, withdrawnBy, withdrawalConsequence | Retrait. |
Accès d'urgence
| Champ | Description |
|---|---|
breakGlassId | Identifiant bg_…. |
vaultId, shareId | Coffre ouvert et partage créé. |
requestedBy, requestedByEmail, justification | Demandeur et justification. |
status | ACTIVE, EXPIRED, REVOKED, PENDING_REVIEW. |
grantedAt, expiresAt | Activation, et date indicative fixée 24 h plus tard. L'accès prend fin à sa révocation. |
revokedAt, revokedBy | Révocation. |
Entrée du journal d'audit
| Champ | Description |
|---|---|
auditId, timestamp | Identifiant aud_… et horodatage. |
userId, sourceIp, userAgent, correlationId | Origine. |
eventType, eventCategory, action | Nature de l'événement. |
resourceType, resourceId | Ressource concernée. |
result, failureReason | SUCCESS, FAILURE ou DENIED, et cause d'échec. |
details | Données propres à l'événement. |
accessContext | actorType, hdsRoles, superAdminBypass, customerWid. |
previousHash, entryHash | Chaînage HMAC-SHA256. |
Rapport de conformité
| Champ | Description |
|---|---|
reportId | Identifiant rpt_…. |
type | RGPD_COMPLIANCE, NIS2_INCIDENTS ; HDS_AUDIT pour un PDF de type hdsAudit. |
status | GENERATING, COMPLETED, FAILED. |
periodFrom, periodTo | Période. |
generatedBy | Auteur. |
data | Contenu du rapport. |
Revue d'accès
| Champ | Description |
|---|---|
reviewId | Identifiant rev_…. |
name, description | Libellé. |
status | PENDING, COMPLETED. |
scope | vaultIds, userIds. |
findings | Partages examinés : shareId, vaultId, recommendation (KEEP, REVOKE, DOWNGRADE), reviewedBy, reviewedAt. |
createdBy, completedAt, completedBy | Auteur et clôture. |
Statuts d'un document
| Statut | Signification |
|---|---|
ACTIVE | Document stocké, disponible. |
QUARANTINED | Document stocké chiffré, que le contrôle antivirus n'a pas confirmé sain. |
SEALED | Document figé. |
DELETED | Document supprimé, purgé 30 jours plus tard. |
SOFT_DELETED | Document supprimé avec son coffre, purgé 30 jours plus tard. |
antivirusStatus vaut CLEAN ou QUARANTINED.
Opérations
Les listes renvoient { "data": [ … ], "meta": { "limit", "hasMore" } }, sauf mention contraire.
Coffres
/api/hds/vaults/api/hds/vaultsFiltres type, status, limit (20 par défaut, 100 au plus).
/api/hds/vaults/{vaultId}/api/hds/vaults/{vaultId}Corps : label, metadata, status.
/api/hds/vaults/{vaultId}Réponse : { "deleted": true, "vaultId": "vlt_…" }.
Exporter un coffre
/api/hds/vaults/{vaultId}/exportRéponse : exportVersion, exportedAt, vault, documents, consents, shares (métadonnées uniquement).
Documents
/api/hds/vaults/{vaultId}/documentsMultipart : file (obligatoire, 100 Mo), folderId, comment. Réponse 201.
/api/hds/vaults/{vaultId}/documentsFiltres folderId, limit.
/api/hds/vaults/{vaultId}/documents/{docId}/api/hds/vaults/{vaultId}/documents/{docId}/versions/api/hds/vaults/{vaultId}/documents/{docId}Réponse : { "deleted": true, "docId", "hardDeleteScheduledAt" }.
Dossiers
/api/hds/vaults/{vaultId}/folders/api/hds/vaults/{vaultId}/foldersFiltre parentFolderId. Réponse : tableau de dossiers.
/api/hds/vaults/{vaultId}/folders/{folderId}/api/hds/vaults/{vaultId}/folders/{folderId}/api/hds/vaults/{vaultId}/folders/{folderId}/api/hds/vaults/{vaultId}/folders/{folderId}/move-documentCorps : docId, targetFolderId.
Partages
/api/hds/sharesCorps : vaultId, targetUserId, level.
/api/hds/sharesFiltres vaultId, targetUserId, active, limit.
/api/hds/shares/{shareId}/api/hds/shares/{shareId}Consentements
/api/hds/vaults/{vaultId}/consents/api/hds/vaults/{vaultId}/consentsFiltres patientId, status, limit.
/api/hds/vaults/{vaultId}/consents/{consentId}Accès d'urgence
/api/hds/break-glass/vaults/{vaultId}Corps : justification (20 caractères au moins).
/api/hds/break-glassFiltres vaultId, status, limit (50 par défaut, 200 au plus).
/api/hds/break-glass/{breakGlassId}/api/hds/break-glass/{breakGlassId}Journal d'audit
/api/hds/audit-logsFiltres eventType, eventCategory, from, to, limit (50 par défaut, 200 au plus).
/api/hds/audit-logs/integrity-checkRéponse : valid, totalEntries, checkTimestamp, et en cas de rupture firstInvalidAt, details.
Conformité
/api/hds/compliance/rgpd/api/hds/compliance/nis2/api/hds/compliance/reportsCorps : type (RGPD_COMPLIANCE ou NIS2_INCIDENTS), periodFrom, periodTo.
/api/hds/compliance/reports/api/hds/compliance/reports/{reportId}/api/hds/admin/compliance/reportsParamètres d'URL : type (hdsAudit, rgpd, nis2), from, to. Produit un PDF.
/api/hds/admin/compliance/reports/{reportId}/downloadRéponse : reportId, url, expiresInSeconds (600).
Revues d'accès
/api/hds/access-reviews/api/hds/access-reviews/api/hds/access-reviews/{reviewId}/api/hds/access-reviews/{reviewId}/findings/api/hds/access-reviews/{reviewId}/completeAlertes
/api/hds/admin/alerts/api/hds/admin/alerts/check/api/hds/admin/alerts/{alertId}/acknowledgeSauvegardes
/api/hds/admin/backup/api/hds/admin/backupParamètres limit (20 par défaut, 100 au plus), cursor.
/api/hds/admin/backup/{backupId}/api/hds/admin/backup/{backupId}/restoreParamètre dryRun=true pour un essai à blanc.
Espace
/api/hds/networks/{networkWid}Erreurs
Deux formats coexistent. Les refus prononcés à l'entrée de l'API publique suivent son format { "statusCode", "message", "error", "timestamp", "path" }. Les erreurs du module HDS sont relayées telles quelles, au format { "statusCode", "message", "error" }.
| Code | message | Cause |
|---|---|---|
400 | tableau de messages de validation | Champ manquant, inconnu ou mal typé. |
400 | HDS network not provisioned or not active | Espace du client inactif. |
400 | Vault quota exceeded: … / Document quota exceeded: … | Quota atteint. |
400 | Patient information is required for PATIENT vault type | Identité du patient manquante. |
400 | TEMPORARY vault expiresAt must be between 24 hours and 90 days from now | Date de fin hors bornes. |
401 | Authentification requise: … | Jeton absent ou invalide. |
403 | Rôle(s) HDS requis: HDS_ADMIN, HDS_HEALTHCARE, HDS_MEDICAL, HDS_PATIENT, HDS_STORAGE, HDS_DELETE (mode: any) | Aucun rôle HDS. |
403 | Insufficient HDS permissions for this operation | Le rôle ne permet pas l'opération. |
403 | HDS path not allowed | Chemin inconnu de l'API. |
403 | Access denied to this network | Espace d'un autre client. |
404 | Vault not found: vlt_… | Coffre inexistant ou inaccessible. |
408 | Request timed out | Traitement de plus de 30 s. |
413 | Storage quota exceeded | Quota de stockage atteint. |
413 | File too large | Fichier de plus de 100 Mo. |
429 | — | Limite de débit atteinte. |
503 | Auth check unavailable | Vérification de révocation du jeton momentanément indisponible. |
503 | HDS service unavailable | Module momentanément injoignable. |
Limites
| Élément | Valeur |
|---|---|
| Taille d'un document | 100 Mo |
| Stockage par espace | 10 Go par défaut |
| Coffres par espace | 1 000 par défaut |
| Documents par espace | 50 000 par défaut |
Coffre TEMPORARY | fin entre 24 h et 90 jours |
| Justification d'accès d'urgence | 20 caractères au moins |
| Purge d'un document supprimé | 30 jours |
| Délai de traitement | 30 s par opération |
| Lien de téléchargement d'un rapport PDF | 600 s |
| Alertes | conservées 24 h, dédoublonnées sur 1 h |
| Limites de débit (API publique, par IP) | 10 req/s, 100 req/min, 1 000 req/h |