Aller au contenu

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.

GuideDéveloppeur
Accès requis
Droit « Voir le module antivirus »
Durée
10 min
Voir en Markdown

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

Bash
curl "https://api.wakastart.app/api/antivirus/scans/7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42/status" \
  -H "x-api-key: sk_test_exemple"
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);

Conseil

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.

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.

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