API rapports

Le module Rapports expose une API REST complète sous le préfixe /api/reports/ qui permet d'automatiser toutes les opérations réalisables depuis l'interface graphique : création et gestion de templates, génération de PDF, consultation de l'historique, personnalisation du branding, création de blocs Python personnalisés, configuration des règles de matrices. Cette page documente les vingt-trois endpoints disponibles et leurs schémas d'entrée et de sortie.

Vue d'ensemble des endpoints

Les endpoints sont regroupés en sept familles fonctionnelles. Chaque famille correspond à une zone de l'interface et peut être utilisée indépendamment.

Templates

Les cinq endpoints templates forment un CRUD complet. Les templates par défaut (embarqués) sont accessibles en lecture seule ; les modifications portent sur les templates créés par l'utilisateur.

Schéma de création (TemplateCreate) : name, blocks (liste de clés), description, language (défaut 'fr'), mode ('concis' ou 'expert'). La mise à jour (TemplateUpdate) n'accepte que blocks, name et description.

Génération

Deux endpoints partagent la même logique interne. La seule différence est que /preview force le flag is_preview=True, ce qui produit un PDF temporaire non persisté destiné à être ouvert dans un nouvel onglet.

Schéma ReportGenerateRequest

Le schéma d'entrée de la génération est le plus riche de l'API. Il comprend seize champs optionnels qui couvrent à la fois la structure du rapport, les données à inclure et le contexte environnemental.

Consultation et téléchargement

Les rapports générés sont persistés côté serveur avec un identifiant et un chemin de fichier PDF. L'API permet la liste, la récupération des métadonnées, le téléchargement du fichier et la suppression.

Sessions Nexus

Un endpoint dédié liste les sessions Nexus disponibles pour alimenter le formulaire de création de rapport. Il lit directement la base SQLite des sessions et retourne les cinquante plus récentes.

Chaque session retournée contient son identifiant, son nom, le sample_id et sample_name associés, l'élément traité et la date de création. Ces informations servent à proposer un menu déroulant à l'utilisateur dans l'interface.

Branding

Le branding regroupe le nom d'organisation et le chemin vers un logo local qui seront injectés dans l'en-tête et le pied de page des rapports. Il est stocké côté serveur et appliqué automatiquement à chaque génération.

La mise à jour valide que le chemin de logo fourni pointe vers un fichier existant et que son extension est reconnue (PNG, JPG, JPEG ou SVG). Un fichier manquant retourne un 400 avec le message explicite, un format non supporté également.

Blocs personnalisés

Les cinq endpoints blocs personnalisés forment un CRUD complet avec une spécificité importante : la validation syntaxique du code Python côté backend avant acceptation.

Le schéma CustomBlockCreate impose : key, name, code_python. Les autres champs ont des valeurs par défaut : description='', category='custom', nature='I', icon='CB', licence='pro', expert=False, language='fr', api_calls=None.

Groupes et règles de matrices

Les matrices d'échantillonnage (eau, sol, sédiment, etc.) peuvent être regroupées par affinité, et des règles de pertinence peuvent être définies entre groupes. Cette configuration alimente les validations réalisées lors de la comparaison de matrices différentes dans un même rapport.

Un groupe de matrices comporte un identifiant, un nom, une couleur, une liste de matrices concrètes et une note optionnelle. Une règle lie deux groupes (from_group, to_group), porte un flag relevant (booléen) et une note. L'endpoint check retourne relevant (bool ou null) et defined (bool indiquant si la règle existe).

Codes d'erreur standards

Tous les endpoints suivent les mêmes conventions de codes d'erreur HTTP.

Exemple d'usage programmatique

L'exemple suivant illustre un parcours complet en Python avec la bibliothèque requests : sélection d'une session Nexus, génération du rapport, téléchargement du PDF.

import requests

base = 'http://localhost:8000'

# Selection d'une session Nexus
sessions = requests.get(f'{base}/api/reports/nexus-sessions').json()
session_id = sessions['sessions'][0]['id']

# Generation du rapport avec le preset expert
payload = {
    'blocks': ['cover_page', 'executive_summary', 'sample_inventory',
               'nexus_processes', 'nexus_chain', 'limitations',
               'certification'],
    'title': 'Audit automatise -- session Nexus',
    'nexus_session_id': session_id,
    'language': 'fr',
}
resp = requests.post(f'{base}/api/reports/generate', json=payload)
report = resp.json()

# Telechargement du PDF
pdf = requests.get(f'{base}/api/reports/download/{report["id"]}')
with open('rapport.pdf', 'wb') as f:
    f.write(pdf.content)

Cette automatisation est la voie recommandée pour les intégrations d'IsoFind dans un pipeline plus large : surveillance continue, génération périodique de rapports de suivi, production en lot d'attestations pour un portefeuille de sites.

Authentification

L'API est protégée par le même système d'authentification que l'interface graphique. Un token est requis dans l'en-tête HTTP pour les endpoints qui modifient l'état ou accèdent à des données sensibles. Les endpoints en lecture seule sur les templates par défaut sont accessibles sans token.

Les détails d'obtention et d'usage du token sont décrits dans la documentation générale de l'API IsoFind. Pour les intégrations tierces, un token de service peut être généré côté administration et révoqué indépendamment du compte utilisateur.

Pour aller plus loin

• Générer un rapport : parcours équivalent depuis l'interface.
• Blocs personnalisés : schéma complet et contraintes d'un bloc custom.
• API IsoFind : authentification et endpoints des autres modules.
• Intégration Python : usage du package isof côté client.