# Sauvegarder et restaurer les métadonnées HDS

> Consultez les sauvegardes quotidiennes de votre espace HDS, déclenchez-en une et restaurez les métadonnées, avec un essai à blanc préalable.

Le module sauvegarde chaque nuit à 2 h les métadonnées de votre espace : coffres, documents, dossiers, partages et consentements. La sauvegarde est chiffrée et stockée dans l'espace du client. Les fichiers chiffrés eux-mêmes ne sont pas concernés : ils restent dans le stockage objet.

## Avant de commencer

- Vous portez le rôle `HDS_ADMIN`.

## Consulter les sauvegardes

```bash
curl "https://api.wakastart.app/api/hds/admin/backup?limit=10" \
  -H "Authorization: Bearer $USER_TOKEN"
```

Réponse attendue (extrait) :

```json
{
  "data": [
    {
      "backupId": "bkp_Lk9Jh8GfD4sA",
      "status": "COMPLETED",
      "startedAt": "2026-10-23T02:00:00.120Z",
      "completedAt": "2026-10-23T02:00:04.870Z",
      "initiatedBy": "system",
      "stats": { "vaultCount": 430, "documentCount": 2187, "totalStorageBytes": 734003200, "backupSizeBytes": 1843200 },
      "error": null
    }
  ],
  "meta": { "limit": 10, "hasMore": true, "nextCursor": "6718a0f2c9e77b0012345678" }
}
```

Pour la page suivante, passez `cursor` avec la valeur de `nextCursor`. Détail d'une sauvegarde : `GET /api/hds/admin/backup/{backupId}`.

## Déclencher une sauvegarde

Faites-le avant une opération de masse (import, nettoyage).

```bash
curl -X POST "https://api.wakastart.app/api/hds/admin/backup" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Avant import des dossiers du cabinet Exemple" }'
```

La réponse renvoie `backupId`, `"status": "COMPLETED"` et les statistiques de la sauvegarde.

## Restaurer

La restauration réécrit, à partir de la sauvegarde, chaque coffre, document, dossier, partage et consentement qu'elle contient, en se fondant sur son identifiant. Les objets créés après la sauvegarde ne sont pas supprimés.

1. Faites un essai à blanc, qui ne modifie rien :

```bash
curl -X POST "https://api.wakastart.app/api/hds/admin/backup/bkp_Lk9Jh8GfD4sA/restore?dryRun=true" \
  -H "Authorization: Bearer $USER_TOKEN"
```

```json
{
  "mode": "DRY_RUN",
  "backupId": "bkp_Lk9Jh8GfD4sA",
  "networkWid": "EXCLI1",
  "diff": {
    "vaults": { "existing": 431, "fromBackup": 430, "toUpsert": 430 },
    "documents": { "existing": 2190, "fromBackup": 2187, "toUpsert": 2187 },
    "folders": { "existing": 1290, "fromBackup": 1290, "toUpsert": 1290 },
    "shares": { "existing": 612, "fromBackup": 610, "toUpsert": 610 },
    "consents": { "existing": 413, "fromBackup": 412, "toUpsert": 412 }
  },
  "message": "Dry run completed. No data was modified."
}
```

2. Vérifiez les volumes de `diff`.
3. Lancez la restauration réelle, sans `dryRun` :

```bash
curl -X POST "https://api.wakastart.app/api/hds/admin/backup/bkp_Lk9Jh8GfD4sA/restore" \
  -H "Authorization: Bearer $USER_TOKEN"
```

La réponse indique `"mode": "APPLIED"` et `"message": "Restore completed successfully."`.

:::warning
La restauration remplace l'état actuel des objets présents dans la sauvegarde par leur état sauvegardé : un partage révoqué depuis redevient actif s'il l'était au moment de la sauvegarde. Faites toujours l'essai à blanc, puis repassez une revue des accès après restauration.
:::

## Vérifier le résultat

- Le journal d'audit contient `BACKUP_RESTORE_COMPLETED`, avec le `diff` appliqué.
- Les coffres attendus réapparaissent dans `GET /api/hds/vaults`.

## Dépannage

- `400` `Cannot restore backup with status: FAILED` : choisissez une sauvegarde `COMPLETED`.
- `404` `Backup not found: …` : vérifiez l'identifiant.

## Voir aussi

- [Chiffrement et traçabilité](/v1.0/hds/chiffrement-et-tracabilite)
- [Mener une revue des accès](/v1.0/hds/mener-une-revue-des-acces)
