API d’inspection de fichiers : SHA-256, MIME réel, signal antivirus et métadonnées en un seul appel REST

API d’inspection de fichiers : SHA-256, MIME réel, signal antivirus et métadonnées en un seul appel REST

Les applications qui reçoivent des fichiers doivent souvent effectuer un contrôle technique avant de transmettre une pièce jointe à un parseur, un workflow ou un stockage. Une marketplace reçoit des documents de vendeurs, un SaaS accepte des pièces jointes client et une plateforme de partage doit savoir ce qui entre dans son système. Chaque équipe peut développer sa propre détection MIME, son calcul de hash, son extraction de métadonnées et son triage initial, mais maintenir ces contrôles de façon homogène demande du temps. FileInspection rassemble ces vérifications dans un contrat REST asynchrone et renvoie un rapport JSON unique.

Le modèle de requête multipart

Un client authentifié envoie une requête multipart à POST /api/files/start-process. Il indique actionName=FileInspection, place un seul fichier dans le champ file, transmet parameters=[] et définit async=true. Un fichier non vide de 50 Mo maximum est accepté par appel, sans liste d’extensions autorisées. La validation reste effectuée côté serveur : un attribut HTML, un nom de fichier ou un type MIME déclaré par le navigateur ne constitue pas une preuve de sécurité.

La première réponse confirme la création d’une action, pas la disponibilité du rapport. L’intégrateur conserve l’identifiant et l’URL trackingUrl, puis interroge /api/actions/get-action-infos/{id} avec le même contexte authentifié. Ce traitement asynchrone évite de garder la requête d’upload ouverte pendant la détection MIME, le triage moteur antivirus, l’extraction de métadonnées ou l’analyse des caractéristiques média.

Le contenu du rapport JSON

Un résultat FileInspection réussi est un fichier JSON unique. Il contient le nom original et la taille, un hash SHA-256 et le type MIME réel détecté. Cette valeur est déterminée à partir du contenu, et non acceptée comme vérité à partir du navigateur. L’application dispose ainsi d’une base plus solide pour journaliser, orienter un fichier vers un traitement ou décider si un parseur en aval doit être appelé.

Lorsque le format s’y prête, ExifTool fournit des métadonnées EXIF filtrées. Pour les fichiers audio et vidéo, FFprobe peut retourner le codec, la résolution, la durée et le débit. Les images et les PDF peuvent également recevoir un aperçu OCR limité à 500 caractères. Ces informations dépendent du format : l’intégration doit accepter qu’un champ soit absent, vide ou indisponible, sans conclure qu’une absence signifie que l’upload a échoué.

Des signaux de triage, pas une certification

La partie antivirus expose un statut moteur antivirus parmi clean, infected et error. Il s’agit d’un signal préliminaire de triage, jamais d’une garantie antivirus. En particulier, clean signifie uniquement que cette inspection n’a pas signalé de détection. Il ne faut pas le transformer dans l’interface en « fichier certifié sain ». Un statut error doit rester différent de clean afin que l’application puisse adopter une politique prudente.

La partie jeu de règles de détection indique clean, matched ou not_run. Le jeu de règles de démarrage est minimal et ne constitue pas une base de détection exhaustive. Une correspondance peut justifier une revue complémentaire, tandis que clean ou not_run ne prouve pas l’absence de menace. Cette nuance doit rester présente dans la documentation, les logs et les messages destinés aux utilisateurs.

Prévoir une intégration robuste

Conservez l’identifiant de l’action comme référence durable du traitement asynchrone. Distinguez au minimum une validation refusée, un traitement en cours, un échec et un résultat disponible. Si un appel de suivi expire, retrouvez d’abord l’action existante avant d’en créer une autre. Relancer une inspection parce qu’une requête de polling n’a pas répondu peut produire un travail en double et consommer inutilement des tokens.

Après succès, utilisez le parcours authentifié et la référence de résultat fournie par le serveur pour télécharger le JSON. Ne construisez pas une URL de résultat à partir d’un simple identifiant et ne considérez jamais un ID envoyé par un client comme une autorisation. Dans votre propre application, contrôlez aussi la propriété lorsque le rapport est associé à un enregistrement d’upload. Un hash facilite la déduplication et la traçabilité ; il ne donne aucun accès au fichier sous-jacent.

Documentation, prix et périmètre

Les exemples de requêtes et le contrat de réponse figurent dans la documentation API de FileInspection. Une inspection réussie coûte 12 tokens. Les erreurs de validation, comme un fichier vide ou supérieur à 50 Mo, ne sont pas facturées. Le service convient à un contrôle technique initial et borné avant parsing ou revue humaine ; il ne remplace ni une plateforme d’analyse malware complète ni une politique métier spécifique.

Avec un appel REST asynchrone, l’intégrateur obtient une empreinte SHA-256, un MIME réel, un signal antivirus préliminaire, un statut de détection minimal, des métadonnées filtrées et, selon le format, des informations média ou OCR. Le contrat conserve une référence claire et traçable pendant que le système appelant poursuit son propre workflow.