Aller au contenu

Référence de l'antivirus

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

RéférenceDéveloppeur
Voir en Markdown

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émentValeur
Authentificationx-api-key: sk_…, ou Authorization: Bearer <jeton Keycloak émis pour l'application>
Contexte obligatoireun client et une application (portés par la clé ou le jeton)
Envoidroit Lancer un scan antivirus (antivirus.scan)
Lecturedroit Voir le module antivirus (antivirus.read)
Coût1 crédit par envoi, débité sur le solde du client à la réception

Objet scan

ChampTypeDescription
idUUIDIdentifiant du scan.
customerWidchaîne (6)WID du client propriétaire.
appWidchaîne (6)WID de l'application.
userIdUUID ou nullIdentifiant de l'utilisateur ou de la clé à l'origine de l'envoi.
filenamechaîneNom d'origine du fichier.
fileSizeentierTaille en octets.
mimeTypechaîneType MIME déclaré à l'envoi.
fileHashchaîne ou nullEmpreinte SHA-256 en hexadécimal, renseignée pendant l'analyse.
s3KeychaîneEmplacement interne du fichier chez Wakastart. Information technique, sans usage pour vous.
statusénumérationPENDING, SCANNING, CLEAN, INFECTED ou ERROR.
priorityentier1 (la plus haute) à 10. 5 par défaut.
callbackUrlchaîne ou nullURL du webhook.
threatNamechaîne ou nullNom de la menace détectée.
threatSeveritychaîne ou nullHIGH pour tout fichier infecté.
scanEnginechaîne ou nullMoteur et version, par exemple ClamAV 1.4.3.
signatureVersionchaîne ou nullVersion de la base de signatures utilisée.
scanDurationMsentier ou nullDurée de l'analyse en millisecondes.
errorMessagechaîne ou nullCause de l'échec, pour un scan en ERROR.
queuedAtdate ISO 8601Mise en file d'attente.
startedAtdate ou nullDébut de la dernière tentative d'analyse.
completedAtdate ou nullFin de l'analyse.
createdAt, updatedAtdateCréation et dernière modification de l'enregistrement.

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

Statuts

StatutFinalDéclenche le webhook
PENDINGNonNon
SCANNINGNonNon
CLEANOuiOui
INFECTEDOuiOui
ERRORAprès 3 tentativesNon

Envoyer un fichier

POST/api/antivirus/scans

Corps multipart/form-data :

ChampTypeObligatoireContraintes
filefichierOui100 Mo au plus à l'envoi ; 50 Mo au plus pour que l'analyse aboutisse
callbackUrlchaîneNonHTTPS, hôte public (ni localhost, ni IP privée ou de lien local), 500 caractères au plus
callbackSecretchaîneNon64 caractères au plus ; requis pour recevoir le webhook
priorityentierNon1 à 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

GET/api/antivirus/scans/{id}/status
ParamètreEmplacementDescription
idcheminUUID 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

GET/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émentValeur
MéthodePOST
En-têtesContent-Type: application/json, X-Webhook-Signature, X-Webhook-Timestamp
SignatureHMAC-SHA256 du corps brut avec callbackSecret, en hexadécimal minuscule
Succèstoute réponse 2xx
Délai10 s par tentative
Tentatives3 (immédiate, puis après 1 s, puis après 4 s)
Champ du corpsDescription
scanIdIdentifiant du scan
statusCLEAN ou INFECTED
filenameNom d'origine du fichier
threatNameNom de la menace ; absent si CLEAN
fileHashEmpreinte SHA-256
completedAtFin 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.

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

Limites

ÉlémentValeur
Taille acceptée à l'envoi100 Mo
Taille analysable50 Mo
Taille maximale d'une politique d'analyse100 Mo par défaut
Délai d'analyse par tentative30 s
Tentatives d'analyse3, à 5 s puis 10 s d'intervalle
Analyses simultanées3
callbackUrl500 caractères, HTTPS
callbackSecret64 caractères
Limites de débit (API publique, par IP)10 req/s, 100 req/min, 1 000 req/h