Prévisualiser les documents via l'API
Prévisualiser les documents via l'API
Tester vos filtres et templates avant export ou envoi — obtenir des aperçus réalistes sans lancer la génération finale
Utilisez l’appel de prévisualisation pour vérifier rapidement que vos filtres, templates et données produisent le rendu attendu. Idéal pour itérer sur les templates et intégrer des contrôles dans vos pipelines.
Fonctionnalités couvertes
Aperçu rapide
Tester en quelques secondes si un jeu de filtres retourne les documents attendus.
Exemples de résultats
Recevoir un extrait de contenu ou un rendu HTML/Text par document pour valider templates.
Intégration CI/CD
Vérifier automatiquement les changements de templates ou de filtres dans vos pipelines d’intégration.
Filtres avancés
Combiner date, type d’agent, statut, texte libre et autres critères pour cibler précisément les documents.
Batch vs Document unique
Tester une sélection unique ou un lot (batch) pour simuler différents scénarios de génération.
Sécurité & limites
Prévisualisation limitée au contenu retourné ; l’assemblage final et le téléchargement restent côté client.
Rappel important
La prévisualisation fournit un aperçu du contenu généré, mais n’effectue pas l’assemblage final (mise en pages PDF, capture caméra, téléchargement). L’assemblage final et la génération côté client doivent être gérés après réception du contenu d’aperçu.
Flux principal : configurer les filtres et lancer une prévisualisation
1 — Préparer vos filtres
Déterminez les critères que vous voulez tester (p. ex. plage de dates, statut du document, agent générateur, texte dans le titre ou message de commit, batch UUID). Notez précisément les valeurs (format de date ISO ou local attendu par votre UI).
2 — Placer les filtres dans la requête de prévisualisation
Construisez le corps de la requête de prévisualisation avec : identifiant du projet (ou contexte), objets de filtres structurés et, si nécessaire, le batch UUID. Vous pouvez tester un seul document ou une petite sélection pour itérer rapidement.
3 — Lancer la requête de prévisualisation
Envoyez l’appel de prévisualisation depuis votre UI, depuis un outil de requêtes ou depuis un job automatisé. Attendez la réponse qui contient le nombre d’éléments et une liste d’exemples de documents (extraits ou rendu HTML/Text).
4 — Inspecter les résultats
Vérifiez pour chaque exemple : titre, type de contenu (texte, html), extrait/aperçu, statut, batch UUID. Confirmez que les templates ont été appliqués et que les filtres retournent bien ce que vous attendiez.
5 — Affiner et répéter
Ajustez les filtres ou le template et relancez la prévisualisation jusqu’à obtenir des résultats satisfaisants. Limitez la taille des lots pendant les tests pour gagner du temps.
Exemple : corps de la requête de prévisualisation
project_id: 42 filters:
- field: created_at comparator: between value: [“2026-02-01”, “2026-02-28”]
- field: status comparator: = value: “draft”
- field: title comparator: contains value: “report” options: limit: 5 include_generated_html: true
Exemple : format de réponse typique (extrait)
count: 3 documents:
- id: “doc_123”
title: “Weekly report — 2026-02-07”
content_type: “text/html”
preview_snippet: “
Weekly report
Key metrics: …
” batch_uuid: “batch-abc” - id: “doc_124” title: “Weekly report — 2026-02-14” content_type: “text/plain” preview_snippet: “Weekly report — Key metrics: …” batch_uuid: “batch-abc”
- id: “doc_125”
title: “Summary — February”
content_type: “text/html”
preview_snippet: “Summary of February…” batch_uuid: null
Limiter la taille des réponses pendant les tests
Pour itérer vite, demandez un petit nombre d’exemples (limit: 3–5). Cela réduit les temps de réponse et simplifie l’inspection manuelle.
Inclure le rendu HTML pour valider le template
Demandez l’HTML rendu quand votre template génère du HTML. Inspectez dans un navigateur pour vérifier classes CSS, images et structure avant l’assemblage final côté client.
Ce que la prévisualisation ne fait pas
La prévisualisation renvoie le contenu généré (texte ou HTML) mais n’exécute pas l’assemblage final : génération de PDF, capture d’écran, ou bundling d’assets. Ces étapes doivent être effectuées côté client (navigateur ou process d’assemblage) après réception de l’aperçu.
Interpréter et valider les résultats de prévisualisation
1 — Vérifier la conformité du template
Assurez-vous que l’extrait HTML/texte contient les balises et sections attendues (en-tête, pieds de page, variables remplacées). Recherchez placeholders non remplacés.
2 — Contrôler les images et assets
Si le template intègre des images, vérifiez que les URLs ou références sont résolues dans l’aperçu. Si l’aperçu contient URLs temporaires, planifiez l’étape d’inclusion réelle côté client.
3 — Tester cas-limites
Validez les documents très longs, vides ou contenant caractères spéciaux. Demandez des aperçus pour ces cas afin de détecter débordements ou plantages du template.
4 — Considérer la mise en page finale
Rappelez-vous : l’aperçu vous confirme le contenu, pas la pagination finale. Pour checks de pagination/sauts de page, effectuez un assemblage de test côté client (PDF ou rendu navigateur).
5 — Noter les erreurs ou incohérences
Si l’aperçu montre du contenu manquant ou invalide, ajustez le template ou les données d’entrée, puis relancez la prévisualisation.
Intégration dans un pipeline CI/CD — bonnes pratiques
1 — Automatiser les appels de prévisualisation
Ajoutez une étape de test qui exécute une prévisualisation après modification d’un template ou d’un ensemble de filtres. Utilisez des filtres deterministes (ex. un batch UUID de test).
2 — Comparer l'aperçu attendu vs obtenu
Stockez un « golden sample » (ex. un fragment HTML attendu) et comparez automatiquement l’aperçu renvoyé pour détecter régressions (diffs textuels ou tests HTML structurés).
3 — Limiter le scope et la fréquence
Exécutez ces tests sur des commits ou PRs, pas à chaque push massif. Utilisez des quotas pour éviter d’envoyer de gros lots dans les runs CI.
4 — Gérer les erreurs comme échecs de pipeline
Si la prévisualisation renvoie zéro document pour un jeu de filtres test, échouez la build afin d’alerter l’équipe (si c’est un comportement indésirable).
5 — Nettoyer les environnements de test
Utilisez des projets/tests dédiés ou un batch UUID spécifique pour éviter d’impacter données de production dans vos runs automatisés.
Avant : vous exécutez directement des lots d’export et découvrez les erreurs en production (fichiers mal formés, images manquantes).
Après : vous utilisez la prévisualisation pour valider le contenu et les templates, puis vous assemblez localement (ou côté navigateur) un export final propre.
Assembler et exporter côté client (workflow recommandé)
1 — Recevoir l'aperçu validé
Récupérez la liste d’exemples validés (HTML, texte, métadonnées) depuis l’appel de prévisualisation.
2 — Construire la vue d'export côté client
Injectez le HTML/text dans un conteneur de rendu dans le navigateur ou dans votre service d’assemblage pour vérifier la mise en page réelle.
3 — Générer le PDF / image / bundle
Utilisez votre mécanisme client (ex. API de génération PDF côté navigateur, headless browser ou librairie de mise en page) pour produire le fichier final.
4 — Ajouter métadonnées et livraison
Ajoutez métadonnées nécessaires (nom de fichier, auteurs, date) et déclenchez l’envoi (webhook, pièce jointe d’email, stockage).
5 — Archiver les logs et vérifier intégrité
Conservez un log local d’assemblage pour dépannage et comparez taille/sha/aperçu du fichier final aux attentes.
Limites et erreurs fréquentes à surveiller
- Réponses vides : un jeu de filtres trop strict peut renvoyer 0 résultats. Testez avec critères plus larges.
- Placeholders non remplacés : signale un défaut de template ou de mapping des variables.
- Formats d’image non résolus : certaines URLs peuvent nécessiter authentification ou pré-signe ; prévoyez leur résolution côté client avant assemblage.
Utilisé pour itérations rapides. Limitez le paramètre de taille (limit) à 3–5 et vérifiez snippets HTML/texte. Idéal pour changements de templates mineurs.
Tracer les batch UUID pour reproduction
Quand vous lancez une prévisualisation depuis l’interface, notez le batch UUID renvoyé (ou générez-en un vous-même). Réutilisez ce même identifiant pour reproduire exactement la même sélection dans vos tests automatisés.
Dépannage — étapes concrètes en cas de résultat inattendu
1 — Vérifier les filtres appliqués
Relisez chaque filtre : champ, comparateur, format de valeur (dates, nombres, chaînes). Simplifiez pour isoler la condition fautive.
2 — Tester avec un sample connu
Exécutez la prévisualisation sur un document d’exemple dont vous connaissez le contenu exact pour détecter dérive de template.
3 — Inspecter le preview_snippet
Recherchez placeholders non résolus, balises manquantes ou erreurs d’encodage (caractères spéciaux).
4 — Vérifier limites/timeouts
Si la requête met trop de temps ou échoue, réduisez la taille du lot et testez à nouveau. Considérez la charge réseau et les quotas.
5 — Documenter et rerun
Notez le jeu de filtres utilisé (incl. batch UUID) et ré-exécutez après correction du template.
Questions fréquentes — Prévisualisation de documents
Prêt à tester vos templates ?
Utilisez ce flux pour vérifier rapidement vos modifications avant de lancer un export complet. Gardez en tête que l’assemblage final se fait côté client.