# Suivre une analyse par interrogation

> Interrogez le statut d'un scan jusqu'à son verdict, puis lisez son détail, avec un exemple d'attente complet en TypeScript.

Sans webhook, votre serveur demande lui-même le statut du scan jusqu'à obtenir un statut final. L'interrogation sert aussi de filet de sécurité avec un webhook : un scan terminé en `ERROR` ne déclenche aucune notification.

## Avant de commencer

- L'identifiant d'un scan, obtenu à l'[envoi du fichier](/v1.0/antivirus/envoyer-un-fichier).
- Une clé API, ou un jeton, dotée du droit **Voir le module antivirus**, rattachée au même client que le scan.

## Lire le statut

`GET /api/antivirus/scans/{id}/status` est la requête légère prévue pour l'interrogation.

::::tabs{sync="lang"}
:::tab{label="cURL"}
```bash
curl "https://api.wakastart.app/api/antivirus/scans/7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42/status" \
  -H "x-api-key: sk_test_exemple"
```
:::
:::tab{label="TypeScript"}
```typescript
const API_URL = "https://api.wakastart.app/api";
const API_KEY = process.env.WAKASTART_API_KEY!;

type ScanStatus = "PENDING" | "SCANNING" | "CLEAN" | "INFECTED" | "ERROR";

export async function getStatus(scanId: string) {
  const response = await fetch(`${API_URL}/antivirus/scans/${scanId}/status`, {
    headers: { "x-api-key": API_KEY },
  });
  if (!response.ok) throw new Error(`Statut illisible : ${response.status}`);
  return (await response.json()) as {
    id: string;
    status: ScanStatus;
    filename: string;
    completedAt: string | null;
  };
}
```
:::
::::

Réponse attendue :

```json
{
  "id": "7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42",
  "status": "SCANNING",
  "filename": "justificatif-domicile.pdf",
  "completedAt": null
}
```

## Attendre le verdict

1. Interrogez le statut toutes les deux secondes.
2. Arrêtez-vous sur `CLEAN` ou `INFECTED`.
3. Sur `ERROR`, continuez d'interroger pendant une minute : Wakastart relance l'analyse jusqu'à trois fois et le statut peut repasser à `SCANNING`.
4. Au-delà, considérez l'analyse comme échouée et ne libérez pas le fichier.

```typescript
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function waitForVerdict(scanId: string, timeoutMs = 120_000) {
  const deadline = Date.now() + timeoutMs;
  let lastErrorAt: number | null = null;

  while (Date.now() < deadline) {
    const { status } = await getStatus(scanId);
    if (status === "CLEAN" || status === "INFECTED") return status;
    if (status === "ERROR") {
      lastErrorAt ??= Date.now();
      if (Date.now() - lastErrorAt > 60_000) return "ERROR";
    } else {
      lastErrorAt = null;
    }
    await sleep(2_000);
  }
  throw new Error(`Aucun verdict pour ${scanId} après ${timeoutMs} ms`);
}

waitForVerdict("7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42").then(console.log);
```

:::tip
Respectez les limites de débit de l'API publique : 10 requêtes par seconde et 100 par minute par adresse IP. Pour suivre beaucoup de scans à la fois, préférez le [webhook](/v1.0/antivirus/recevoir-le-resultat-par-webhook).
:::

## Lire le détail

Une fois le statut final atteint, `GET /api/antivirus/scans/{id}` donne le résultat complet :

```bash
curl "https://api.wakastart.app/api/antivirus/scans/7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42" \
  -H "x-api-key: sk_test_exemple"
```

Extrait de la réponse pour un fichier infecté :

```json
{
  "id": "7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42",
  "filename": "justificatif-domicile.pdf",
  "status": "INFECTED",
  "fileHash": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
  "threatName": "Win.Test.EICAR_HDB-1",
  "threatSeverity": "HIGH",
  "scanEngine": "ClamAV 1.4.3",
  "signatureVersion": "27801",
  "scanDurationMs": 412,
  "completedAt": "2026-10-23T09:30:12.016Z"
}
```

Tous les champs sont décrits dans la [référence](/v1.0/antivirus/reference#objet-scan).

## Vérifier le résultat

- Votre code s'arrête sur un statut final et n'accepte le fichier que sur `CLEAN`.
- Un identifiant inconnu, ou appartenant à un autre client, renvoie `404`.

## Voir aussi

- [Cycle de vie d'une analyse](/v1.0/antivirus/cycle-de-vie-d-une-analyse)
- [Résoudre les problèmes d'analyse](/v1.0/antivirus/depannage)
