PagoMovilOCR
Librairie npm qui extrait, normalise et valide les reçus de Pago Móvil vénézuéliens par OCR.
Le Problème
Au Venezuela, confirmer un paiement Pago Móvil implique souvent de demander une capture d'écran au client et de la lire à la main (montant, référence, date, banque), ce qui est lent, source d'erreurs humaines, et ne passe pas à l'échelle pour une entreprise traitant beaucoup de paiements par jour.
La Solution
PagoMovilOCR automatise cette lecture : elle reçoit l'image du reçu et retourne des données structurées accompagnées d'un ensemble de validations de cohérence, sans backend propre et sans jamais envoyer l'image à un serveur.
Architecture / Engineering
- J'ai conçu un pipeline en 4 étapes indépendantes et testables séparément : OCR → normalisation → parsing → validation.
- J'ai implémenté un moteur OCR interchangeable (Tesseract.js par défaut, exécuté à 100 % côté client/local via WebAssembly).
- J'ai construit un système de profils bancaires enregistrables (`registerBankProfile`) pour détecter, et quand c'est fiable, parser le format de chaque banque.
- J'ai développé un module de conversion USD/VES utilisant le taux officiel de la BCV (via pydolarve.org), avec cache en mémoire configurable et gestion explicite des données `stale`.
- J'ai couvert toute la logique avec des tests unitaires et d'intégration Vitest : normalisation, parsers, validateurs individuels, module de devise avec providers simulés, et `verifyPayment` de bout en bout avec un OCR simulé.
Fonctionnalités Clés
- `verifyPayment()` : pipeline complet image → résultat structuré avec validations.
- Validation du montant, de la référence, de la date, de l'heure et de la banque par rapport à des valeurs attendues optionnelles.
- Conversion USD/VES à la demande avec le taux officiel de la BCV et cache configurable.
- Système de profils bancaires extensible sans toucher au cœur de la librairie.
- Fonctionne dans le navigateur (OCR via WASM, l'image ne quitte jamais le client) et sous Node.js 18+.
- Distribuée en ESM, CJS et IIFE pour CDN (unpkg/jsDelivr), avec types TypeScript inclus.
Défis Techniques
- Concevoir des validations honnêtes : la librairie ne produit jamais de champ `fraud: true` et ne promet aucune vérification bancaire, elle ne fait que signaler des incohérences observables dans le texte extrait, à un humain de décider.
- Séparer les erreurs d'exécution (image corrompue, réseau coupé) des erreurs de validation d'un reçu, pour qu'un reçu invalide ne soit jamais traité comme une panne du programme.
- Garder l'extraction et les validations déterministes et testables avec Vitest sans dépendre d'un moteur OCR réel en CI.
Résultat / État Actuel
Pipeline complet fonctionnel de bout en bout, avec une suite de tests Vitest couvrant normalisation, parsing, validateurs et l'orchestrateur `verifyPayment`. Documentée avec un README complet, des exemples exécutables et une architecture en couches.
Limitation connue
Les profils bancaires (hormis le générique) ne fournissent qu'une détection par nom ; aucun `parse` spécifique par banque n'a été inclus car un format unique et stable n'a pas pu être vérifié de façon fiable pour chacune — le parser générique couvre le format commun.