PagoMovilOCR
Biblioteca npm que extrai, normaliza e valida comprovantes de Pago Móvil venezuelanos via OCR.
O Problema
Na Venezuela, confirmar um Pago Móvil geralmente significa pedir ao cliente uma captura de tela e ler à mão (valor, referência, data, banco), o que é lento, sujeito a erro humano e não escala para um negócio que processa muitos pagamentos por dia.
A Solução
O PagoMovilOCR automatiza essa leitura: recebe uma imagem do comprovante e devolve dados estruturados junto com um conjunto de validações de consistência, sem depender de backend próprio e sem enviar a imagem a nenhum servidor.
Arquitetura / Engineering
- Projetei um pipeline de 4 etapas independentes e testáveis separadamente: OCR → normalização → parsing → validação.
- Implementei um motor OCR intercambiável (Tesseract.js por padrão, rodando 100% no cliente/processo local via WebAssembly).
- Construí um sistema de perfis de banco registráveis (`registerBankProfile`) para detectar, e quando seguro, fazer o parsing do formato de cada banco.
- Desenvolvi um módulo de conversão USD/VES com a taxa oficial do BCV (via pydolarve.org), cache em memória configurável e tratamento explícito de dados `stale`.
- Cobri toda a lógica com testes unitários e de integração em Vitest: normalização, parsers, validadores individuais, o módulo de câmbio com providers simulados, e `verifyPayment` de ponta a ponta com um OCR simulado.
Funcionalidades Principais
- `verifyPayment()`: pipeline completo de imagem a resultado estruturado com validações.
- Validação de valor, referência, data, hora e banco contra valores esperados opcionais.
- Conversão USD/VES sob demanda com a taxa oficial do BCV e cache configurável.
- Sistema de perfis de banco extensível sem tocar no núcleo da biblioteca.
- Funciona no navegador (OCR via WASM, a imagem nunca sai do cliente) e em Node.js 18+.
- Distribuída como ESM, CJS e IIFE para CDN (unpkg/jsDelivr), com tipos TypeScript incluídos.
Desafios Técnicos
- Projetar validações honestas: a biblioteca nunca produz um campo `fraud: true` nem promete verificação bancária, apenas sinaliza inconsistências observáveis no texto extraído para que um humano decida.
- Separar erros de execução (imagem corrompida, rede fora do ar) de erros de validação de um comprovante, para que um comprovante inválido nunca seja tratado como falha do programa.
- Manter a extração e as validações determinísticas e testáveis com Vitest sem depender de um motor OCR real no CI.
Resultado / Estado Atual
Pipeline completo funcionando de ponta a ponta, com suíte de testes em Vitest cobrindo normalização, parsing, validadores e o orquestrador `verifyPayment`. Documentada com README completo, exemplos executáveis e arquitetura em camadas.
Limitação conhecida
Os perfis de banco (exceto o genérico) só oferecem detecção por nome; não incluem um `parse` específico por banco porque não foi possível verificar de forma confiável um layout único e estável para cada um — o parser genérico cobre o formato comum.