Aller au contenu

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
Voir en Markdown

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 :

ChampObligatoireDescription
fileOuiLe fichier à analyser.
callbackUrlNonURL HTTPS appelée à la fin de l'analyse. Hôte public uniquement : ni localhost, ni adresse IP privée. 500 caractères au plus.
callbackSecretNonSecret qui signe le webhook, 64 caractères au plus. Sans lui, aucun webhook n'est envoyé, même si callbackUrl est renseigné.
priorityNonEntier 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é

  1. Dans votre base, associez l'id du scan à votre copie du fichier.
  2. Marquez le fichier « en cours de vérification » : ne le servez à personne.
  3. 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 201 et status vaut PENDING.
  • GET /api/antivirus/scans/{id}/status renvoie le même identifiant.
  • Le solde de crédits du client a diminué de 1.

Dépannage

  • 400 à l'envoi : fichier absent, callbackUrl non HTTPS ou privée, callbackSecret trop 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.

Voir aussi