# Référence de l'antivirus

> Objet scan, statuts, opérations de l'API publique, format du webhook, erreurs et limites du module Antivirus.

Toutes les opérations passent par l'API publique `https://api.wakastart.app/api`. Les endpoints sont aussi décrits dans la [référence API — Antivirus](/v1.0/reference-api/antivirus).

## Authentification et droits

| Élément | Valeur |
|---|---|
| Authentification | `x-api-key: sk_…`, ou `Authorization: Bearer <jeton Keycloak émis pour l'application>` |
| Contexte obligatoire | un client et une application (portés par la clé ou le jeton) |
| Envoi | droit **Lancer un scan antivirus** (`antivirus.scan`) |
| Lecture | droit **Voir le module antivirus** (`antivirus.read`) |
| Coût | 1 crédit par envoi, débité sur le solde du client à la réception |

## Objet scan

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant du scan. |
| `customerWid` | chaîne (6) | [WID](/v1.0/glossaire#wid) du client propriétaire. |
| `appWid` | chaîne (6) | WID de l'application. |
| `userId` | UUID ou `null` | Identifiant de l'utilisateur ou de la clé à l'origine de l'envoi. |
| `filename` | chaîne | Nom d'origine du fichier. |
| `fileSize` | entier | Taille en octets. |
| `mimeType` | chaîne | Type MIME déclaré à l'envoi. |
| `fileHash` | chaîne ou `null` | Empreinte SHA-256 en hexadécimal, renseignée pendant l'analyse. |
| `s3Key` | chaîne | Emplacement interne du fichier chez Wakastart. Information technique, sans usage pour vous. |
| `status` | énumération | `PENDING`, `SCANNING`, `CLEAN`, `INFECTED` ou `ERROR`. |
| `priority` | entier | 1 (la plus haute) à 10. 5 par défaut. |
| `callbackUrl` | chaîne ou `null` | URL du webhook. |
| `threatName` | chaîne ou `null` | Nom de la menace détectée. |
| `threatSeverity` | chaîne ou `null` | `HIGH` pour tout fichier infecté. |
| `scanEngine` | chaîne ou `null` | Moteur et version, par exemple `ClamAV 1.4.3`. |
| `signatureVersion` | chaîne ou `null` | Version de la base de signatures utilisée. |
| `scanDurationMs` | entier ou `null` | Durée de l'analyse en millisecondes. |
| `errorMessage` | chaîne ou `null` | Cause de l'échec, pour un scan en `ERROR`. |
| `queuedAt` | date ISO 8601 | Mise en file d'attente. |
| `startedAt` | date ou `null` | Début de la dernière tentative d'analyse. |
| `completedAt` | date ou `null` | Fin de l'analyse. |
| `createdAt`, `updatedAt` | date | Création et dernière modification de l'enregistrement. |

Le secret du webhook n'est jamais renvoyé par les lectures.

## Statuts

| Statut | Final | Déclenche le webhook |
|---|---|---|
| `PENDING` | Non | Non |
| `SCANNING` | Non | Non |
| `CLEAN` | Oui | Oui |
| `INFECTED` | Oui | Oui |
| `ERROR` | Après 3 tentatives | Non |

## Envoyer un fichier

::endpoint{method="POST" path="/api/antivirus/scans"}

Corps `multipart/form-data` :

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `file` | fichier | Oui | 100 Mo au plus à l'envoi ; 50 Mo au plus pour que l'analyse aboutisse |
| `callbackUrl` | chaîne | Non | HTTPS, hôte public (ni `localhost`, ni IP privée ou de lien local), 500 caractères au plus |
| `callbackSecret` | chaîne | Non | 64 caractères au plus ; requis pour recevoir le webhook |
| `priority` | entier | Non | 1 à 10, défaut 5 |

```bash
curl -X POST "https://api.wakastart.app/api/antivirus/scans" \
  -H "x-api-key: sk_test_exemple" \
  -F "file=@facture-2026-10.pdf" \
  -F "priority=5"
```

Réponse `201 Created` : l'objet scan, au statut `PENDING`.

## Lire le statut d'un scan

::endpoint{method="GET" path="/api/antivirus/scans/{id}/status"}

| Paramètre | Emplacement | Description |
|---|---|---|
| `id` | chemin | UUID du scan |

```bash
curl "https://api.wakastart.app/api/antivirus/scans/3f6c1a52-8d4e-4b7a-9c21-5e0f7b2d9a10/status" \
  -H "x-api-key: sk_test_exemple"
```

Réponse `200` :

```json
{
  "id": "3f6c1a52-8d4e-4b7a-9c21-5e0f7b2d9a10",
  "status": "CLEAN",
  "filename": "facture-2026-10.pdf",
  "completedAt": "2026-10-23T09:12:05.931Z"
}
```

## Lire le détail d'un scan

::endpoint{method="GET" path="/api/antivirus/scans/{id}"}

```bash
curl "https://api.wakastart.app/api/antivirus/scans/3f6c1a52-8d4e-4b7a-9c21-5e0f7b2d9a10" \
  -H "x-api-key: sk_test_exemple"
```

Réponse `200` : l'objet scan complet. Un scan d'un autre client, ou inexistant, renvoie `404`.

## Webhook

Requête envoyée par Wakastart à `callbackUrl` à la fin d'une analyse `CLEAN` ou `INFECTED`.

| Élément | Valeur |
|---|---|
| Méthode | `POST` |
| En-têtes | `Content-Type: application/json`, `X-Webhook-Signature`, `X-Webhook-Timestamp` |
| Signature | HMAC-SHA256 du corps brut avec `callbackSecret`, en hexadécimal minuscule |
| Succès | toute réponse `2xx` |
| Délai | 10 s par tentative |
| Tentatives | 3 (immédiate, puis après 1 s, puis après 4 s) |

| Champ du corps | Description |
|---|---|
| `scanId` | Identifiant du scan |
| `status` | `CLEAN` ou `INFECTED` |
| `filename` | Nom d'origine du fichier |
| `threatName` | Nom de la menace ; absent si `CLEAN` |
| `fileHash` | Empreinte SHA-256 |
| `completedAt` | Fin de l'analyse, ISO 8601 |

## Erreurs

Les erreurs suivent le format de l'API publique : `{ "statusCode", "message", "error", "timestamp", "path" }`. Pour les refus prononcés par le service d'analyse lui-même, `message` vaut `Antivirus service error` et seul le code HTTP distingue la cause.

| Code | `message` | Cause |
|---|---|---|
| `400` | `Fichier requis` | Champ `file` absent. |
| `400` | tableau de messages de validation | `callbackUrl` invalide ou privée, `priority` hors bornes. |
| `400` | `Antivirus service error` | `callbackUrl` non HTTPS, `callbackSecret` de plus de 64 caractères, clé sans application rattachée, ou fichier refusé par la politique d'analyse. |
| `400` | `Validation failed (uuid is expected)` | Identifiant de scan mal formé. |
| `401` | `Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)` | Ni jeton ni clé valides. |
| `402` | `Antivirus service error` | Solde de crédits insuffisant ou inexistant. |
| `403` | `Droit applicatif requis : antivirus.scan` (ou `antivirus.read`) | Le profil n'a pas le droit. |
| `403` | `Access denied: token authorized party does not match the target application` | Jeton émis pour une autre application. |
| `404` | `Antivirus service error` | Scan inexistant ou d'un autre client. |
| `413` | `File too large` | Fichier de plus de 100 Mo. |
| `429` | — | Limite de débit de l'API publique atteinte. |
| `503` | `Antivirus service unavailable` ou `Antivirus service error` | Service d'analyse ou de crédits momentanément indisponible. |

## Limites

| Élément | Valeur |
|---|---|
| Taille acceptée à l'envoi | 100 Mo |
| Taille analysable | 50 Mo |
| Taille maximale d'une politique d'analyse | 100 Mo par défaut |
| Délai d'analyse par tentative | 30 s |
| Tentatives d'analyse | 3, à 5 s puis 10 s d'intervalle |
| Analyses simultanées | 3 |
| `callbackUrl` | 500 caractères, HTTPS |
| `callbackSecret` | 64 caractères |
| Limites de débit (API publique, par IP) | 10 req/s, 100 req/min, 1 000 req/h |
