Référence de l'antivirus
Objet scan, statuts, opérations de l'API publique, format du webhook, erreurs et limites du module Antivirus.
This page has not been translated yet and is shown in French.
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 |