# Déposer un document

> Déposez un document dans un coffre, retrouvez-le, consultez son historique et supprimez-le par l'API.

Un document est déposé dans un coffre `ACTIVE`, que l'utilisateur possède ou qui lui est partagé. Le module contrôle le fichier, le chiffre et l'inscrit au journal d'audit avant de répondre.

## Avant de commencer

- Un coffre `ACTIVE`. Voir [Gérer les coffres](/v1.0/hds/gerer-les-coffres).
- Un fichier de **100 Mo au plus**.
- Optionnel : l'identifiant du dossier de destination. Voir [Organiser en dossiers](/v1.0/hds/organiser-en-dossiers).

## Déposer le fichier

La requête est en `multipart/form-data` :

| Champ | Obligatoire | Description |
|---|---|---|
| `file` | Oui | Le fichier. |
| `folderId` | Non | Dossier de destination ; racine du coffre par défaut. |
| `comment` | Non | Commentaire attaché à la version 1. |

::::tabs{sync="lang"}
:::tab{label="cURL"}
```bash
curl -X POST "https://api.wakastart.app/api/hds/vaults/vlt_a1B2c3D4/documents" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -F "file=@ordonnance-2026-10-23.pdf" \
  -F "folderId=fld_Lm4Rt8Ws" \
  -F "comment=Ordonnance de sortie"
```
:::
:::tab{label="TypeScript"}
```typescript
import { readFile } from "node:fs/promises";

export async function uploadDocument(userToken: string, vaultId: string, path: string, name: string) {
  const form = new FormData();
  form.append("file", new Blob([await readFile(path)], { type: "application/pdf" }), name);
  form.append("folderId", "fld_Lm4Rt8Ws");
  form.append("comment", "Ordonnance de sortie");

  const response = await fetch(
    `https://api.wakastart.app/api/hds/vaults/${vaultId}/documents`,
    { method: "POST", headers: { Authorization: `Bearer ${userToken}` }, body: form },
  );
  if (response.status !== 201) throw new Error(`${response.status} ${await response.text()}`);
  return (await response.json()) as { docId: string; status: string; deduplicated?: boolean };
}
```
:::
::::

Réponse attendue (`201 Created`) :

```json
{
  "docId": "doc_Pz3Vb6Nc",
  "vaultId": "vlt_a1B2c3D4",
  "originalFilename": "ordonnance-2026-10-23.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 96512,
  "status": "QUARANTINED",
  "currentVersion": 1,
  "antivirusStatus": "QUARANTINED",
  "createdAt": "2026-10-23T10:31:44.120Z"
}
```

Si le même contenu existe déjà dans le coffre, la réponse renvoie le document existant avec `"deduplicated": true`, sans créer de doublon.

## Lister les documents d'un coffre

```bash
curl "https://api.wakastart.app/api/hds/vaults/vlt_a1B2c3D4/documents?folderId=fld_Lm4Rt8Ws" \
  -H "Authorization: Bearer $USER_TOKEN"
```

| Paramètre | Description |
|---|---|
| `folderId` | Documents d'un dossier ; une valeur vide liste ceux de la racine. |
| `limit` | 20 par défaut, 100 au plus. |

La réponse a la forme `{ "data": [ … ], "meta": { "limit": 20, "hasMore": false } }`. Les documents supprimés n'y figurent pas.

## Lire un document et son historique

- `GET /api/hds/vaults/{vaultId}/documents/{docId}` renvoie les métadonnées du document, dont son empreinte `hashSha256` et la liste de ses versions.
- `GET /api/hds/vaults/{vaultId}/documents/{docId}/versions` renvoie l'historique :

```json
{
  "docId": "doc_Pz3Vb6Nc",
  "vaultId": "vlt_a1B2c3D4",
  "currentVersion": 1,
  "versions": [
    {
      "version": 1,
      "sizeBytes": 96512,
      "hashSha256": "e3b98a4da31a127d4bde6e43033f66ba274cab0eb7eb1c70ec41402bf6273dd8",
      "uploadedAt": "2026-10-23T10:31:44.120Z",
      "uploadedBy": "8f14e45f-ceea-467f-a0e6-2d2d3a7c1b11",
      "comment": "Ordonnance de sortie"
    }
  ]
}
```

## Supprimer un document

Rôle : `HDS_DELETE` ou `HDS_ADMIN`, avec accès au coffre.

```bash
curl -X DELETE "https://api.wakastart.app/api/hds/vaults/vlt_a1B2c3D4/documents/doc_Pz3Vb6Nc" \
  -H "Authorization: Bearer $USER_TOKEN"
```

Réponse attendue :

```json
{
  "deleted": true,
  "docId": "doc_Pz3Vb6Nc",
  "hardDeleteScheduledAt": "2026-11-22T10:40:02.511Z"
}
```

Le document passe au statut `DELETED` et son fichier est purgé à la date `hardDeleteScheduledAt`, 30 jours plus tard.

## Vérifier le résultat

- Le document apparaît dans la liste du coffre, dans le bon dossier.
- `storageUsedBytes` et `documentCount` du coffre ont augmenté.
- Le journal d'audit contient `DOCUMENT_UPLOADED`.

## Dépannage

- `404` `Vault not found or not active` : le coffre n'existe pas ou n'est pas `ACTIVE`.
- `413` `Storage quota exceeded` : le quota de stockage de l'espace est atteint.
- `400` `Document quota exceeded: …` : le nombre maximal de documents est atteint.
- `413` `File too large` : le fichier dépasse 100 Mo.

## Voir aussi

- [Chiffrement et traçabilité](/v1.0/hds/chiffrement-et-tracabilite)
- [Référence : statuts d'un document](/v1.0/hds/reference#statuts-dun-document)
