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.
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 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
/api/antivirus/scansCorps 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 |
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
/api/antivirus/scans/{id}/status| Paramètre | Emplacement | Description |
|---|---|---|
id | chemin | UUID du scan |
curl "https://api.wakastart.app/api/antivirus/scans/3f6c1a52-8d4e-4b7a-9c21-5e0f7b2d9a10/status" \
-H "x-api-key: sk_test_exemple"Réponse 200 :
{
"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
/api/antivirus/scans/{id}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 |