# Gérer les coffres

> Créez des coffres patient, structure, recherche ou temporaires, listez-les, modifiez-les et supprimez-les par l'API.

Le coffre est le point d'entrée de toute donnée de santé. Ce guide couvre son cycle complet : création, consultation, modification et suppression.

Tous les appels partent du serveur de votre wakapp, avec le jeton d'accès de l'utilisateur connecté :

```bash
export HDS_API="https://api.wakastart.app/api/hds"
export USER_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.exemple"
```

## Avant de commencer

- L'espace HDS du client est actif. Voir [Activer le module](/v1.0/hds/activer-le-module).
- L'utilisateur porte un rôle qui permet l'opération (voir chaque section).

## Créer un coffre

Rôles : `HDS_HEALTHCARE`, `HDS_STORAGE` ou `HDS_ADMIN`. Le créateur devient propriétaire du coffre.

::::tabs{sync="lang"}
:::tab{label="cURL"}
```bash
curl -X POST "$HDS_API/vaults" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STRUCTURAL",
    "label": "Protocoles du service de cardiologie",
    "ownerTeamId": "team-cardio",
    "metadata": { "service": "cardiologie" },
    "defaultFolders": ["Protocoles", "Formations"]
  }'
```
:::
:::tab{label="TypeScript"}
```typescript
const HDS_API = "https://api.wakastart.app/api/hds";

export async function createVault(userToken: string) {
  const response = await fetch(`${HDS_API}/vaults`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${userToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "STRUCTURAL",
      label: "Protocoles du service de cardiologie",
      ownerTeamId: "team-cardio",
      metadata: { service: "cardiologie" },
      defaultFolders: ["Protocoles", "Formations"],
    }),
  });
  if (response.status !== 201) throw new Error(await response.text());
  return (await response.json()) as { vaultId: string; status: string };
}
```
:::
::::

Réponse attendue (`201 Created`) :

```json
{
  "vaultId": "vlt_K9m3Np7Q",
  "type": "STRUCTURAL",
  "status": "ACTIVE",
  "label": "Protocoles du service de cardiologie",
  "ownerId": "8f14e45f-ceea-467f-a0e6-2d2d3a7c1b11",
  "ownerTeamId": "team-cardio",
  "pseudonymizedPatientId": null,
  "metadata": { "service": "cardiologie" },
  "storageUsedBytes": 0,
  "documentCount": 0,
  "retentionPolicy": "STANDARD",
  "expiresAt": null,
  "createdAt": "2026-10-23T10:20:00.000Z",
  "updatedAt": "2026-10-23T10:20:00.000Z"
}
```

Champs du corps :

| Champ | Obligatoire | Description |
|---|---|---|
| `type` | Oui | `PATIENT`, `STRUCTURAL`, `RESEARCH` ou `TEMPORARY`. |
| `label` | Oui | Libellé, 255 caractères au plus. |
| `patient` | Si `PATIENT` | `externalId`, `firstName`, `lastName`, `birthDate` (ISO 8601), `ins` facultatif. Interdit pour `RESEARCH`. |
| `ownerTeamId` | Si `STRUCTURAL` | Identifiant de l'équipe propriétaire. |
| `expiresAt` | Si `TEMPORARY` | Date de fin, entre 24 heures et 90 jours. |
| `metadata` | Non | Paires clé-valeur libres. |
| `retentionPolicy` | Non | `STANDARD` (défaut), `EXTENDED`, `LEGAL_HOLD` ou `CUSTOM`, enregistré sur le coffre. |
| `defaultFolders` | Non | Noms des dossiers à créer à la racine. |

## Lister et lire les coffres

Rôle : tout rôle HDS sauf `HDS_DELETE` seul. La liste contient les coffres dont l'utilisateur est propriétaire et ceux qui lui sont partagés ; les coffres `DELETED` en sont exclus par défaut.

```bash
curl "$HDS_API/vaults?type=PATIENT&limit=50" \
  -H "Authorization: Bearer $USER_TOKEN"
```

| Paramètre | Description |
|---|---|
| `type` | Filtre par type de coffre. |
| `status` | Filtre par statut ; `DELETED` pour retrouver les coffres supprimés. |
| `limit` | Nombre de résultats, 20 par défaut, 100 au plus. |

La réponse a la forme `{ "data": [ … ], "meta": { "limit": 50, "hasMore": false } }`.

Pour lire un coffre : `GET /api/hds/vaults/{vaultId}`. Un coffre inexistant, ou auquel l'utilisateur n'a pas accès, renvoie `404` `Vault not found: vlt_…`.

## Modifier un coffre

Rôle : `HDS_ADMIN`, propriétaire du coffre. On peut changer le libellé, les métadonnées et le statut.

```bash
curl -X PATCH "$HDS_API/vaults/vlt_K9m3Np7Q" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Protocoles de cardiologie 2026", "status": "ARCHIVED" }'
```

La réponse renvoie le coffre modifié. Un coffre `ARCHIVED` n'accepte plus de nouveaux documents.

## Supprimer un coffre

Rôle : `HDS_DELETE` ou `HDS_ADMIN`, propriétaire du coffre.

```bash
curl -X DELETE "$HDS_API/vaults/vlt_K9m3Np7Q" \
  -H "Authorization: Bearer $USER_TOKEN"
```

Réponse attendue :

```json
{ "deleted": true, "vaultId": "vlt_K9m3Np7Q" }
```

Le coffre passe au statut `DELETED` et disparaît des listes par défaut. Il reste lisible avec `status=DELETED`.

## Vérifier le résultat

- Le coffre créé apparaît dans `GET /api/hds/vaults`.
- Le journal d'audit contient un événement `VAULT_CREATED`, puis `VAULT_UPDATED` ou `VAULT_DELETED`.

## Dépannage

- `400` `HDS network not provisioned or not active` : l'espace du client n'est pas actif.
- `400` `Vault quota exceeded: 1000/1000` : le quota de coffres est atteint.
- `400` `Patient information is required for PATIENT vault type` : renseignez `patient`.
- `403` `Insufficient HDS permissions for this operation` : le rôle de l'utilisateur ne permet pas l'opération.

## Voir aussi

- [Déposer un document](/v1.0/hds/deposer-un-document)
- [Partager un coffre](/v1.0/hds/partager-un-coffre)
