docs/API.md

API (app/main.py)

POST /analyze

Requête (multipart/form-data)

Champ	Type	Requis	Description
image	fichier	oui	photo du terminal de pompe (jpeg/png/bmp/webp/tiff)
fuel_price	float	non	prix du litre configuré côté YELY — fait autorité sur celui lu à l'écran
driver_id	string	non	identifiant chauffeur (issu du scan QR côté YELY)
pompiste_id	string	non	identifiant pompiste
station_id	string	non	identifiant station

Volontairement pas de paramètres techniques (seuil de confiance OCR, activer/désactiver la détection d'écran...) — contrairement au prototype précédent, ce endpoint n'expose que les champs métier attendus par le cahier des charges.

Réponse (200)

Voir README.md pour un exemple complet. Tous les champs correspondent au §13 du cahier des charges — voir docs/POSTPROCESS_RULES.md pour le détail du calcul de chaque valeur, docs/ARCHITECTURE.md pour le pipeline complet.

Erreurs

Statut	Cas
400	type d'image non supporté, ou fichier illisible
500	erreur interne inattendue pendant le traitement (journalisée dans logs/api.log avec la stack trace complète)

Chargement du modèle

Le CRNN est chargé une seule fois au premier appel (singleton _get_model()), pas à chaque requête — le chargement prend 30-90s sur CPU. Conséquence pratique : ne pas lancer uvicorn --reload en usage normal, chaque rechargement de code redémarre le worker et donc le modèle.

CORS

ALLOWED_ORIGINS (variable d'environnement, origines séparées par des virgules) contrôle quels domaines peuvent appeler l'API depuis un navigateur — nécessaire car le frontend (Vercel) et l'API (Hugging Face Spaces) sont sur des domaines différents. Par défaut "*" (permissif, adapté à une démo) ; à restreindre au domaine Vercel réel en production.

Journalisation

Chaque appel écrit une ligne JSON dans logs/api.log : requête (sans l'image elle-même) + réponse complète. C'est la base du suivi de performance — voir docs/MONITORING.md.

Traçabilité

Chaque photo reçue est sauvegardée dans photos/<transaction_id>.jpg et référencée dans la réponse (photo_reference) — nécessaire pour qu'un contrôle a posteriori (station, YELY) puisse revérifier une transaction contestée, et c'est aussi la matière première de la boucle d'apprentissage continu (docs/MONITORING.md).