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.
- Accès requis
- Droit « Voir le module antivirus »
- Durée
- 10 min
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.
curl "https://api.wakastart.app/api/antivirus/scans/7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42/status" \
-H "x-api-key: sk_test_exemple"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 :
{
"id": "7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42",
"status": "SCANNING",
"filename": "justificatif-domicile.pdf",
"completedAt": null
}Attendre le verdict
- Interrogez le statut toutes les deux secondes.
- Arrêtez-vous sur
CLEANouINFECTED. - Sur
ERROR, continuez d'interroger pendant une minute : Wakastart relance l'analyse jusqu'à trois fois et le statut peut repasser àSCANNING. - Au-delà, considérez l'analyse comme échouée et ne libérez pas le fichier.
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 :
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é :
{
"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.