# Envoyer un fichier à analyser

> Soumettez un fichier à l'antivirus depuis votre serveur, avec sa priorité et l'adresse de votre webhook.

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](/v1.0/antivirus/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

::::tabs{sync="lang"}
:::tab{label="cURL"}
```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"
```
:::
:::tab{label="TypeScript"}
```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](/v1.0/antivirus/recevoir-le-resultat-par-webhook) ou par [interrogation](/v1.0/antivirus/suivre-une-analyse).

:::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](/v1.0/antivirus/depannage).

## Voir aussi

- [Quarantaine et politique d'analyse](/v1.0/antivirus/quarantaine-et-politique)
- [Référence API — Antivirus](/v1.0/reference-api/antivirus)
