Envoyer un fichier à analyser
Soumettez un fichier à l'antivirus depuis votre serveur, avec sa priorité et l'adresse de votre webhook.
GuideDéveloppeur
- Accès requis
- Droit « Lancer un scan antivirus »
- Durée
- 10 min
Envoyez chaque fichier reçu de vos utilisateurs à POST /api/antivirus/scans avant de l'accepter. L'API répond immédiatement avec l'identifiant du scan ; le verdict arrive ensuite, par webhook ou par interrogation.
Avant de commencer
- Une clé API dotée du droit Lancer un scan antivirus, et du crédit sur le solde du client. Voir Autoriser votre serveur.
- Un fichier de 50 Mo au plus. Au-delà, l'analyse se termine en
ERROR. - Optionnel : une URL HTTPS publique pour recevoir le webhook, et un secret de 64 caractères au plus pour le signer.
Préparer la requête
La requête est en multipart/form-data :
| Champ | Obligatoire | Description |
|---|---|---|
file | Oui | Le fichier à analyser. |
callbackUrl | Non | URL HTTPS appelée à la fin de l'analyse. Hôte public uniquement : ni localhost, ni adresse IP privée. 500 caractères au plus. |
callbackSecret | Non | Secret qui signe le webhook, 64 caractères au plus. Sans lui, aucun webhook n'est envoyé, même si callbackUrl est renseigné. |
priority | Non | Entier de 1 à 10, 5 par défaut. 1 est la priorité la plus haute. |
Envoyer le fichier
Bash
curl -X POST "https://api.wakastart.app/api/antivirus/scans" \
-H "x-api-key: sk_test_exemple" \
-F "file=@justificatif-domicile.pdf" \
-F "callbackUrl=https://mon-app.exemple.fr/webhooks/antivirus" \
-F "callbackSecret=8c1f0e5a9b2d4c7e6f3a1b0d9e8c7f6a" \
-F "priority=3"TypeScript
import { readFile } from "node:fs/promises";
const API_URL = "https://api.wakastart.app/api";
const API_KEY = process.env.WAKASTART_API_KEY!; // sk_…
export async function submitScan(path: string, filename: string): Promise<string> {
const form = new FormData();
form.append("file", new Blob([await readFile(path)]), filename);
form.append("callbackUrl", "https://mon-app.exemple.fr/webhooks/antivirus");
form.append("callbackSecret", process.env.ANTIVIRUS_WEBHOOK_SECRET!);
form.append("priority", "3");
const response = await fetch(`${API_URL}/antivirus/scans`, {
method: "POST",
headers: { "x-api-key": API_KEY },
body: form,
});
if (response.status !== 201) {
throw new Error(`Scan refusé : ${response.status} ${await response.text()}`);
}
const scan = (await response.json()) as { id: string; status: string };
return scan.id; // à enregistrer avec votre copie du fichier
}
submitScan("./justificatif-domicile.pdf", "justificatif-domicile.pdf").then(console.log);Réponse attendue (201 Created) :
JSON
{
"id": "7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42",
"customerWid": "EXCLI1",
"appWid": "EXAPP1",
"userId": "b1946ac9-2f3e-4c1d-8f0a-6e2b7c9d1e33",
"filename": "justificatif-domicile.pdf",
"fileSize": 512004,
"mimeType": "application/pdf",
"fileHash": null,
"s3Key": "7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42/justificatif-domicile.pdf",
"status": "PENDING",
"priority": 3,
"callbackUrl": "https://mon-app.exemple.fr/webhooks/antivirus",
"threatName": null,
"threatSeverity": null,
"scanEngine": null,
"signatureVersion": null,
"scanDurationMs": null,
"errorMessage": null,
"queuedAt": "2026-10-23T09:30:11.204Z",
"startedAt": null,
"completedAt": null,
"createdAt": "2026-10-23T09:30:11.204Z",
"updatedAt": "2026-10-23T09:30:11.204Z"
}Enregistrer le scan de votre côté
- Dans votre base, associez l'
iddu scan à votre copie du fichier. - Marquez le fichier « en cours de vérification » : ne le servez à personne.
- Attendez le verdict par webhook ou par interrogation.
Important
Wakastart ne vous renvoie jamais le fichier analysé. Conservez votre copie jusqu'au verdict, libérez-la sur CLEAN, supprimez-la sur INFECTED.
Vérifier le résultat
- La réponse est
201etstatusvautPENDING. GET /api/antivirus/scans/{id}/statusrenvoie le même identifiant.- Le solde de crédits du client a diminué de 1.
Dépannage
400à l'envoi : fichier absent,callbackUrlnon HTTPS ou privée,callbackSecrettrop long, ou fichier refusé par la politique d'analyse.413: fichier de plus de 100 Mo.402: solde de crédits vide.
Voir Résoudre les problèmes d'analyse.