# Vigie PDF > SaaS français, conforme RGPD, qui transforme vos PDF en données structurées et accessibles : tagging automatique (opendataloader-pdf), validation multi-profil veraPDF (accessibilité PDF/UA-1/PDF/UA-2/WTPDF, archivage PDF/A-1b/2b/3b, profil détecté ou choisi explicitement), exports structurés et rapports de conformité à la demande. ## URL de base https://vigie-pdf.fr ## Authentification Schéma : Bearer En-tête : `Authorization: Bearer ` Créez une clé depuis l'onglet "Clés API" (/app/api_keys) de votre tableau de bord. Le secret brut n'est affiché qu'une seule fois, immédiatement après sa création -- conservez-le en lieu sûr. Chaque requête vers /api/v1/* doit porter cet en-tête. Une clé absente, invalide, expirée ou révoquée renvoie 401 avec le code invalid_api_key. ## Consommation de crédits La consommation de crédits via l'API est strictement identique à celle de l'interface web -- même vérification de solde avant traitement, même blocage à solde épuisé (crédits pré-payés, aucun dépassement silencieux facturé après coup). - Traitement d'un document (upload, tagging automatique) : 1 crédit(s) - Validation (à la demande, profil auto-détecté ou choisi) : 3 crédit(s), gratuit si le profil exact est déjà validé pour ce document - Correction automatique (plan Pro et supérieur uniquement) : 5 crédit(s) - Génération d'un rapport de conformité : gratuit, aucun crédit consommé ## Points de terminaison ### POST /api/v1/documents Uploade un document PDF et lance le tagging automatique (1 crédit) en arrière-plan. La validation (profil auto-détecté) est une action distincte, optionnelle et payante (3 crédits) -- voir le paramètre run_validation. Coût : 1 crédit(s). Paramètres : - `file` (corps multipart, requis) : Le fichier PDF à uploader (taille maximale : voir DocumentsController::MAX_FILE_SIZE). - `run_validation` (query ou corps, optionnel) : Lance aussi la validation (profil auto-détecté), coût 3 crédits ; défaut selon le réglage du compte (compliance_analysis_default). Réponse : 201 Created -- objet document (id, filename, status, created_at, validation). Erreurs possibles : invalid_api_key, insufficient_credits, file_too_large, invalid_file_type ### POST /api/v1/documents/batch Uploade jusqu'à 20 documents PDF en une seule requête et lance leur tagging automatique groupé (1 crédit par document) -- une seule invocation opendataloader-pdf par groupe compatible (compte, natif/scanné) au lieu d'une par fichier. La validation (profil auto-détecté) est une action distincte, optionnelle et payante (3 crédits par document) -- voir le paramètre run_validation. Coût : 1 crédit(s). Paramètres : - `files[]` (corps multipart, requis) : Les fichiers PDF à uploader (jusqu'à 20 par requête ; taille maximale par fichier : voir DocumentsController::MAX_FILE_SIZE). - `run_validation` (query ou corps, optionnel) : Lance aussi la validation (profil auto-détecté) pour chaque document, coût 3 crédits par document. Réponse : 201 Created -- { documents: [objet document...], rejected: [noms de fichiers trop volumineux ou de type invalide] }. Erreurs possibles : invalid_api_key, insufficient_credits, file_too_large, invalid_file_type, parameter_missing ### GET /api/v1/documents Liste les documents du tenant authentifié, paginés (25 par page, les plus récents d'abord). Paramètres : - `page` (query, optionnel) : Numéro de page (défaut : 1). Réponse : 200 OK -- liste paginée d'objets document. Erreurs possibles : invalid_api_key ### GET /api/v1/documents/:id Statut de traitement/validation d'un document (inclut les compteurs de conformité une fois validé). Paramètres : - `id` (chemin, requis) : Identifiant du document. Réponse : 200 OK -- objet document (avec bloc validation si la validation est terminée, sinon null). Erreurs possibles : invalid_api_key, not_found ### GET /api/v1/documents/:id/export Récupère l'export structuré d'un document déjà taggé, dans le format demandé. Paramètres : - `id` (chemin, requis) : Identifiant du document. - `format` (query, requis) : json, md ou html. Réponse : 200 OK -- corps de l'export dans le format demandé (Content-Type correspondant : application/json, text/markdown ou text/html). Erreurs possibles : invalid_api_key, not_found, document_not_ready, unsupported_format ### GET /api/v1/documents/:id/zones/:zone_id/image Récupère les octets de l'image extraite d'une zone de type image d'un document taggé, servie tenant-scopée -- jamais une URL de stockage signée. Paramètres : - `id` (chemin, requis) : Identifiant du document. - `zone_id` (chemin, requis) : Identifiant de la zone de type image. Réponse : 200 OK -- flux binaire de l'image (Content-Type de l'image : image/png ou image/jpeg), ou 404 si l'image n'est pas disponible. Erreurs possibles : invalid_api_key, not_found ### POST /api/v1/reports Demande la génération d'un rapport de conformité pour un document déjà validé et marqué comme relu. Sans flavour, utilise le dernier profil validé ; avec flavour, génère le rapport pour ce profil précis (erreur si ce document n'a pas été validé sur ce profil). Gratuit -- aucun crédit consommé. Paramètres : - `document_id` (corps, requis) : Identifiant du document. - `flavour` (corps ou query, optionnel) : Profil de validation exact pour lequel générer le rapport (ex. "2b", "ua2", "wt1a"). Sans ce paramètre : dernier profil validé. Réponse : 201 Created -- objet rapport (id, status, document_id, created_at, pdf_available, flavour, profile_name). Erreurs possibles : invalid_api_key, not_found, document_not_validated, document_not_reviewed, invalid_flavour, validation_not_found ### GET /api/v1/reports/:id Statut d'un rapport de conformité, ou téléchargement direct du PDF si déjà généré. Paramètres : - `id` (chemin, requis) : Identifiant du rapport. - `format` (query, optionnel) : pdf pour télécharger le PDF généré (sinon : statut JSON). Réponse : 200 OK -- objet statut JSON (id, status, document_id, created_at, pdf_available), ou flux binaire PDF si ?format=pdf et le PDF est déjà attaché. Erreurs possibles : invalid_api_key, not_found ### POST /api/v1/documents/:id/corrections Applique les correctifs automatiques du moteur déterministe et crée un NOUVEAU document "-corrige" (le document source n'est jamais modifié). Réservé au plan Pro et supérieur -- renvoie 403 plan_upgrade_required sinon. Coût : 5 crédits, tout compris (le pipeline du document corrigé, tagging et validation inclus, n'est jamais refacturé). Coût : 5 crédit(s). Paramètres : - `id` (chemin, requis) : Identifiant du document source (déjà tagged ou validated). Réponse : 201 Created -- objet document corrigé (id, filename, status, source_document_id, url de suivi). Erreurs possibles : invalid_api_key, not_found, document_not_ready, plan_upgrade_required, correction_in_progress, no_correction_available, insufficient_credits ### GET /api/v1/documents/:id/validation Récupère le résultat détaillé de la validation d'un document (profil appliqué, raison de sélection, verdict global, compteurs, liste des critères en échec). Sans flavour, renvoie le dernier profil validé ; avec flavour, cible un profil précis parmi ceux déjà validés pour ce document. Gratuit -- aucun crédit consommé. Paramètres : - `id` (chemin, requis) : Identifiant du document. - `flavour` (query, optionnel) : Profil de validation exact à consulter (ex. "2b", "ua2", "wt1a"). Sans ce paramètre : dernier profil validé. Réponse : 200 OK -- objet validation (flavour, profile_name, detection_reason, compliant, passed, failed, failing_criteria : liste de {label, failed}). Erreurs possibles : invalid_api_key, not_found, document_not_validated, invalid_flavour, validation_not_found ### POST /api/v1/documents/:id/validation Déclenche (ou redéclenche) la validation d'un document déjà taggé pour le profil demandé (défaut : "auto", détection hybride du profil déclaré dans le PDF). Coût : 3 crédits, sauf si ce profil exact a déjà été validé pour ce document (redéclenchement idempotent, gratuit) ou si le document est un document "-corrige" (pipeline déjà payé). Coût : 3 crédit(s). Paramètres : - `id` (chemin, requis) : Identifiant du document (doit déjà être tagged ou validated). - `flavour` (corps ou query, optionnel) : Profil de validation à appliquer (un des 7 profils supportés, ex. "2b"), ou "auto" (défaut) pour la détection hybride. Réponse : 202 Accepted -- { document_id, flavour, status: "queued" }. Erreurs possibles : invalid_api_key, not_found, document_not_ready, invalid_flavour, insufficient_credits ### GET /api/v1/documents/:id/download Télécharge les octets PDF d'un document -- fonctionne aussi bien pour un document original que pour un document "-corrige" (un document corrigé EST un document). Gratuit -- aucun crédit consommé. Paramètres : - `id` (chemin, requis) : Identifiant du document. Réponse : 200 OK -- flux binaire du PDF (Content-Type: application/pdf). Erreurs possibles : invalid_api_key, not_found, document_not_ready, file_purged ### GET /api/v1/documents/:id/correction_report Récupère le rapport de correction structuré d'un document "-corrige" : correctifs appliqués (libellé, valeur posée, compteur exact quand le sidecar le remonte), comparatif avant/après (critères résolus, persistants, nouveaux) et liste des critères non corrigés automatiquement (raison + orientation). Gratuit -- aucun crédit consommé. Paramètres : - `id` (chemin, requis) : Identifiant du document corrigé (celui qui porte source_document_id, PAS le document source). Réponse : 200 OK -- objet rapport de correction (comparison_ready, resolved, persistent, regressions, applied_fixes : liste de {label, fix_kind, computed_value, count}, unresolved : liste de {label, reason, orientation}). Erreurs possibles : invalid_api_key, not_found, not_a_corrected_document ## Codes d'erreur - `401 invalid_api_key` -- Clé API absente, invalide, expirée ou révoquée. - `402 insufficient_credits` -- Solde de crédits insuffisant pour effectuer cette action (achetez des crédits ou changez de forfait). - `422 document_not_ready` -- Le document n'a pas encore terminé son traitement (structure pas encore disponible). - `422 document_not_validated` -- Le document doit d'abord être validé avant de générer un rapport de conformité ou d'en consulter la validation. - `422 document_not_reviewed` -- Le document doit d'abord être marqué comme relu (Studio) avant de générer un rapport de conformité. - `422 unsupported_format` -- Le format d'export demandé n'est pas supporté (json, md ou html uniquement). - `422 file_too_large` -- Le fichier dépasse la taille maximale autorisée. - `422 invalid_file_type` -- Le fichier n'est pas un PDF valide (content_type application/pdf et signature %PDF requis). - `422 parameter_missing` -- Un paramètre requis est manquant dans la requête. - `404 not_found` -- Ressource introuvable, ou n'appartenant pas à votre tenant. - `429 rate_limited` -- Trop de requêtes. Réessayez plus tard (voir Limitation de débit). - `403 plan_upgrade_required` -- Action réservée au plan Pro et supérieur. Passez à un forfait supérieur. - `409 correction_in_progress` -- Une correction est déjà en cours pour ce document. - `422 no_correction_available` -- Aucun correctif automatique applicable à ce document. - `422 not_a_corrected_document` -- Ce document n'est pas un document corrigé -- aucun rapport de correction n'existe pour lui. - `422 invalid_flavour` -- Le profil de validation demandé (paramètre flavour) n'est pas dans la liste blanche des 7 profils supportés. - `404 validation_not_found` -- Aucun résultat de validation pour le profil (flavour) demandé sur ce document. - `410 file_purged` -- Le fichier de ce document a été purgé après la période de rétention de 30 jours (les résultats et rapports de conformité restent disponibles). ## Limitation de débit (rate limiting) - 300 requêtes/minute par clé API (limite identifiée par l'empreinte de la clé, jamais par la clé en clair). - 60 requêtes/minute par adresse IP pour les requêtes sans clé valide (filet anti credential-stuffing). - Au-delà de la limite : 429 Too Many Requests avec le code d'erreur rate_limited.