Aller au contenu

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

RéférenceDéveloppeur
Voir en Markdown

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émentValeur
En-têteAuthorization: Bearer <jeton d'accès Keycloak de l'utilisateur, émis pour l'application>
Rôle minimalau moins un rôle HDS ; sinon 403
Clés API sk_…non acceptées : elles ne portent pas de rôle HDS
Espacecelui du client de l'utilisateur, déduit du jeton
Format des corpsJSON, ou multipart/form-data pour les fichiers

Permissions par rôle

OpérationADMINHEALTHCAREMEDICALPATIENTSTORAGEDELETE
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

ChampDescription
networkWidWID du client.
statusPROVISIONING, ACTIVE, DECOMMISSIONING, DECOMMISSIONED.
storageQuotaBytesQuota de stockage, 10 737 418 240 (10 Go) par défaut.
maxVaultsNombre maximal de coffres, 1 000 par défaut.
maxDocumentsNombre maximal de documents, 50 000 par défaut.
provisionedAtDate d'activation.

Coffre

ChampDescription
vaultIdIdentifiant vlt_….
typePATIENT, STRUCTURAL, RESEARCH, TEMPORARY.
statusACTIVE, ARCHIVED, SUSPENDED, DELETED.
labelLibellé, 255 caractères au plus.
ownerIdIdentifiant Keycloak du propriétaire.
ownerTeamIdÉquipe propriétaire (STRUCTURAL).
patientexternalId, ins, firstName, lastName, birthDate (PATIENT).
pseudonymizedPatientIdRéférence pseudonymisée, ou null.
metadataPaires clé-valeur libres.
storageUsedBytes, documentCountVolume et nombre de documents du coffre.
retentionPolicySTANDARD, EXTENDED, LEGAL_HOLD, CUSTOM.
expiresAtDate de fin (TEMPORARY), ou null.
createdAt, updatedAtDates.

Document

ChampDescription
docIdIdentifiant doc_….
vaultId, folderIdCoffre et dossier (null à la racine).
originalFilename, mimeType, sizeBytesNom, type et taille du fichier d'origine.
statusVoir statuts d'un document.
currentVersionNuméro de la version courante.
versionsHistorique : version, sizeBytes, uploadedAt, uploadedBy, comment (et hashSha256 dans l'historique dédié).
hashSha256Empreinte SHA-256 du fichier d'origine (détail).
antivirusStatusRésultat du contrôle antivirus au dépôt.
tags, medicalMetadata, customMetadataMétadonnées.
uploadedByIdentifiant Keycloak de l'auteur du dépôt.
legalHoldtrue si le document est sous conservation légale.
deduplicatedtrue si le dépôt a renvoyé un document existant (réponse de dépôt uniquement).

Dossier

ChampDescription
folderIdIdentifiant fld_….
vaultId, parentFolderIdCoffre et dossier parent (null à la racine).
name, sortOrderNom (255 caractères) et ordre d'affichage.
createdBy, createdAt, updatedAtAuteur et dates.

Partage

ChampDescription
shareIdIdentifiant shr_….
vaultIdCoffre partagé.
targetUserIdIdentifiant Keycloak du destinataire.
levelREAD, READ_WRITE, FULL_CONTROL.
grantedByAuteur du partage ; BREAK_GLASS_SYSTEM pour un accès d'urgence.
activefalse après révocation.
revokedAt, revokedByRévocation.

Consentement

ChampDescription
consentIdIdentifiant cst_….
vaultId, patientIdCoffre et patient.
purpose, scope, scopeDetailFinalité et périmètre.
collectionMethod, collectedAt, collectedByRecueil.
statusACTIVE, WITHDRAWN, EXPIRED.
expiresAtFin de validité convenue, ou null.
withdrawnAt, withdrawnBy, withdrawalConsequenceRetrait.

Accès d'urgence

ChampDescription
breakGlassIdIdentifiant bg_….
vaultId, shareIdCoffre ouvert et partage créé.
requestedBy, requestedByEmail, justificationDemandeur et justification.
statusACTIVE, EXPIRED, REVOKED, PENDING_REVIEW.
grantedAt, expiresAtActivation, et date indicative fixée 24 h plus tard. L'accès prend fin à sa révocation.
revokedAt, revokedByRévocation.

Entrée du journal d'audit

ChampDescription
auditId, timestampIdentifiant aud_… et horodatage.
userId, sourceIp, userAgent, correlationIdOrigine.
eventType, eventCategory, actionNature de l'événement.
resourceType, resourceIdRessource concernée.
result, failureReasonSUCCESS, FAILURE ou DENIED, et cause d'échec.
detailsDonnées propres à l'événement.
accessContextactorType, hdsRoles, superAdminBypass, customerWid.
previousHash, entryHashChaînage HMAC-SHA256.

Rapport de conformité

ChampDescription
reportIdIdentifiant rpt_….
typeRGPD_COMPLIANCE, NIS2_INCIDENTS ; HDS_AUDIT pour un PDF de type hdsAudit.
statusGENERATING, COMPLETED, FAILED.
periodFrom, periodToPériode.
generatedByAuteur.
dataContenu du rapport.

Revue d'accès

ChampDescription
reviewIdIdentifiant rev_….
name, descriptionLibellé.
statusPENDING, COMPLETED.
scopevaultIds, userIds.
findingsPartages examinés : shareId, vaultId, recommendation (KEEP, REVOKE, DOWNGRADE), reviewedBy, reviewedAt.
createdBy, completedAt, completedByAuteur et clôture.

Statuts d'un document

StatutSignification
ACTIVEDocument stocké, disponible.
QUARANTINEDDocument stocké chiffré, que le contrôle antivirus n'a pas confirmé sain.
SEALEDDocument figé.
DELETEDDocument supprimé, purgé 30 jours plus tard.
SOFT_DELETEDDocument 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

POST/api/hds/vaults
GET/api/hds/vaults

Filtres type, status, limit (20 par défaut, 100 au plus).

GET/api/hds/vaults/{vaultId}
PATCH/api/hds/vaults/{vaultId}

Corps : label, metadata, status.

DELETE/api/hds/vaults/{vaultId}

Réponse : { "deleted": true, "vaultId": "vlt_…" }.

Exporter un coffre

GET/api/hds/vaults/{vaultId}/export

Réponse : exportVersion, exportedAt, vault, documents, consents, shares (métadonnées uniquement).

Documents

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

Multipart : file (obligatoire, 100 Mo), folderId, comment. Réponse 201.

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

Filtres folderId, limit.

GET/api/hds/vaults/{vaultId}/documents/{docId}
GET/api/hds/vaults/{vaultId}/documents/{docId}/versions
DELETE/api/hds/vaults/{vaultId}/documents/{docId}

Réponse : { "deleted": true, "docId", "hardDeleteScheduledAt" }.

Dossiers

POST/api/hds/vaults/{vaultId}/folders
GET/api/hds/vaults/{vaultId}/folders

Filtre parentFolderId. Réponse : tableau de dossiers.

GET/api/hds/vaults/{vaultId}/folders/{folderId}
PATCH/api/hds/vaults/{vaultId}/folders/{folderId}
DELETE/api/hds/vaults/{vaultId}/folders/{folderId}
POST/api/hds/vaults/{vaultId}/folders/{folderId}/move-document

Corps : docId, targetFolderId.

Partages

POST/api/hds/shares

Corps : vaultId, targetUserId, level.

GET/api/hds/shares

Filtres vaultId, targetUserId, active, limit.

GET/api/hds/shares/{shareId}
DELETE/api/hds/shares/{shareId}

Consentements

POST/api/hds/vaults/{vaultId}/consents
GET/api/hds/vaults/{vaultId}/consents

Filtres patientId, status, limit.

GET/api/hds/vaults/{vaultId}/consents/{consentId}

Accès d'urgence

POST/api/hds/break-glass/vaults/{vaultId}

Corps : justification (20 caractères au moins).

GET/api/hds/break-glass

Filtres vaultId, status, limit (50 par défaut, 200 au plus).

GET/api/hds/break-glass/{breakGlassId}
DELETE/api/hds/break-glass/{breakGlassId}

Journal d'audit

GET/api/hds/audit-logs

Filtres eventType, eventCategory, from, to, limit (50 par défaut, 200 au plus).

GET/api/hds/audit-logs/integrity-check

Réponse : valid, totalEntries, checkTimestamp, et en cas de rupture firstInvalidAt, details.

Conformité

GET/api/hds/compliance/rgpd
GET/api/hds/compliance/nis2
POST/api/hds/compliance/reports

Corps : type (RGPD_COMPLIANCE ou NIS2_INCIDENTS), periodFrom, periodTo.

GET/api/hds/compliance/reports
GET/api/hds/compliance/reports/{reportId}
POST/api/hds/admin/compliance/reports

Paramètres d'URL : type (hdsAudit, rgpd, nis2), from, to. Produit un PDF.

GET/api/hds/admin/compliance/reports/{reportId}/download

Réponse : reportId, url, expiresInSeconds (600).

Revues d'accès

POST/api/hds/access-reviews
GET/api/hds/access-reviews
GET/api/hds/access-reviews/{reviewId}
POST/api/hds/access-reviews/{reviewId}/findings
POST/api/hds/access-reviews/{reviewId}/complete

Alertes

GET/api/hds/admin/alerts
POST/api/hds/admin/alerts/check
POST/api/hds/admin/alerts/{alertId}/acknowledge

Sauvegardes

POST/api/hds/admin/backup
GET/api/hds/admin/backup

Paramètres limit (20 par défaut, 100 au plus), cursor.

GET/api/hds/admin/backup/{backupId}
POST/api/hds/admin/backup/{backupId}/restore

Paramètre dryRun=true pour un essai à blanc.

Espace

GET/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" }.

CodemessageCause
400tableau de messages de validationChamp manquant, inconnu ou mal typé.
400HDS network not provisioned or not activeEspace du client inactif.
400Vault quota exceeded: … / Document quota exceeded: …Quota atteint.
400Patient information is required for PATIENT vault typeIdentité du patient manquante.
400TEMPORARY vault expiresAt must be between 24 hours and 90 days from nowDate de fin hors bornes.
401Authentification requise: …Jeton absent ou invalide.
403Rôle(s) HDS requis: HDS_ADMIN, HDS_HEALTHCARE, HDS_MEDICAL, HDS_PATIENT, HDS_STORAGE, HDS_DELETE (mode: any)Aucun rôle HDS.
403Insufficient HDS permissions for this operationLe rôle ne permet pas l'opération.
403HDS path not allowedChemin inconnu de l'API.
403Access denied to this networkEspace d'un autre client.
404Vault not found: vlt_…Coffre inexistant ou inaccessible.
408Request timed outTraitement de plus de 30 s.
413Storage quota exceededQuota de stockage atteint.
413File too largeFichier de plus de 100 Mo.
429—Limite de débit atteinte.
503Auth check unavailableVérification de révocation du jeton momentanément indisponible.
503HDS service unavailableModule momentanément injoignable.

Limites

ÉlémentValeur
Taille d'un document100 Mo
Stockage par espace10 Go par défaut
Coffres par espace1 000 par défaut
Documents par espace50 000 par défaut
Coffre TEMPORARYfin entre 24 h et 90 jours
Justification d'accès d'urgence20 caractères au moins
Purge d'un document supprimé30 jours
Délai de traitement30 s par opération
Lien de téléchargement d'un rapport PDF600 s
Alertesconservé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