Um pipeline em Python para auditoria de comprovantes de abastecimento deve receber o documento, extrair campos com rastreabilidade, validar valores e confrontá-los com os registros da frota. O resultado útil é uma fila de documentos consistentes e pendências explicadas, com evidências para revisão humana. Uma divergência é um sinal a investigar, não uma prova de fraude.
Separe o texto lido da interpretação do sistema. Preserve o arquivo original, mantenha o valor extraído e registre a versão normalizada usada nos cálculos. Use Decimal para quantias e quantidades, políticas explícitas de arredondamento e regras configuráveis por operação. A IA ajuda na leitura; a decisão financeira precisa de controles adicionais.
Resumo rápido
- Guarde o original e um identificador calculado a partir do arquivo.
- Extraia campos com localização da evidência e indicação de incerteza.
- Valide datas, veículo, litros, preço unitário e total antes da conciliação.
- Use números decimais a partir de texto, sem converter primeiro para ponto flutuante.
- Encaminhe dúvidas para revisão humana com motivo claro e histórico de correções.
1. Defina os documentos e o esquema de dados
Comece delimitando quais documentos o processo aceita: fotografia de comprovante, PDF digital, relatório do cartão de combustível ou arquivo estruturado do sistema de despesas. Esses materiais têm funções diferentes. Um comprovante de pagamento pode não discriminar combustível, litros ou veículo; campos ausentes não devem ser preenchidos por suposição.
Crie um esquema com identificador do documento, origem, data de recebimento, data e hora da transação, estabelecimento, identificação do veículo quando disponível, combustível, litros, preço unitário e total. Acrescente moeda, referência ao arquivo, versão do extrator e lista de pendências. Mantenha um campo separado para informações fornecidas pelo motorista.
Para cada dado, preserve três elementos: texto original, valor normalizado e evidência. A placa informada no formulário pode ajudar a localizar o veículo, mas não deve aparecer como se estivesse impressa no comprovante. Essa separação permite entender o que o documento demonstra e o que veio de outro sistema.
Defina ainda o significado da ausência: não encontrado, ilegível ou não aplicável. Uma string vazia mistura situações diferentes. Quando a imagem estiver cortada e o total não aparecer, o resultado correto é solicitar complementação. Não estime o valor usando outro abastecimento parecido.
2. Organize recebimento, extração e rastreabilidade
No recebimento, atribua um identificador interno e calcule um resumo criptográfico do arquivo. A biblioteca hashlib do Python fornece funções de hash; no projeto, esse recurso pode ajudar a reconhecer o reenvio dos mesmos bytes. Ele não comprova a autenticidade do comprovante nem identifica sozinho duas fotografias diferentes do mesmo papel.
Valide o tipo real do arquivo, imponha limites de tamanho e trate documentos que não possam ser processados como pendências operacionais. Separe a pasta de entrada da área de arquivos aprovados. O documento deve continuar disponível mesmo se o serviço de extração falhar, permitindo reprocessamento sem pedir novo envio ao motorista.
Quando usar OCR, o reconhecimento óptico de caracteres, preserve a referência ao trecho que originou cada campo. A documentação do Google Document AI descreve a resposta estruturada e as referências ao texto e à página. Essa estrutura pode apoiar uma tela de revisão que mostra a imagem ao lado do valor extraído, em vez de apresentar apenas uma planilha sem contexto.
Se esse fornecedor fizer parte da solução, registre-o no inventário de ferramentas e confira o catálogo de integrações de IA do Google para distinguir as camadas do projeto. Document AI e Gemini não devem ser tratados como o mesmo serviço. A contratação e o tratamento de dados precisam ser avaliados para a implementação específica.
Fotos giradas, reflexos e impressão apagada exigem uma etapa de qualidade. O guia sobre orientação de imagens antes do OCR ajuda a organizar esse preparo. Uma nova tentativa de leitura pode ser útil, mas o sistema deve manter a imagem recebida e registrar a transformação aplicada.
3. Valide campos e faça os cálculos com Decimal
A validação deve ocorrer antes de qualquer comparação de consumo. Confira campos obrigatórios, tipo de combustível permitido pelo cadastro, veículo existente e valores positivos. Datas futuras, horários ambíguos e identificadores truncados merecem uma pendência específica. Não transforme automaticamente o número zero em ausência nem descarte zeros relevantes de identificadores.
A documentação do Python recomenda considerar as propriedades da aritmética decimal em aplicações que exigem esse controle. Construa Decimal diretamente de strings normalizadas. Converter para float antes pode trazer uma aproximação binária para o cálculo. O guia de valores monetários extraídos por IA aprofunda a diferença entre leitura, moeda e arredondamento.
O exemplo abaixo valida um subconjunto da etapa numérica. Ele aceita apenas um formato brasileiro delimitado, recusa sinais, valores não finitos e entradas ambíguas. A tolerância é ilustrativa e precisa ser aprovada pela operação. O código não verifica documento fiscal nem substitui a conciliação.
import re
from decimal import Decimal, ROUND_HALF_UP
PADRAO = re.compile(r"(?:[0-9]+|[0-9]{1,3}(?:\.[0-9]{3})+)(?:,[0-9]{1,3})?")
def numero_br(texto):
texto = texto.strip()
if not PADRAO.fullmatch(texto):
raise ValueError("formato numérico não aceito")
valor = Decimal(texto.replace(".", "").replace(",", "."))
if not valor.is_finite() or valor <= 0:
raise ValueError("valor deve ser positivo e finito")
return valor
def conferir_total(litros_txt, preco_txt, total_txt, tolerancia):
litros = numero_br(litros_txt)
preco = numero_br(preco_txt)
total = numero_br(total_txt)
calculado = (litros * preco).quantize(
Decimal("0.01"), rounding=ROUND_HALF_UP
)
diferenca = abs(calculado - total)
return {"calculado": str(calculado),
"diferenca": str(diferenca),
"revisar": diferenca > tolerancia}
resultado = conferir_total("40,000", "6,000", "240,00", Decimal("0.01"))
O exemplo usa uma política única de casas decimais para simplificar a demonstração. Em produção, limite precisão por campo e valide a origem do formato. Um arquivo que usa ponto decimal deve ter outro adaptador. Entradas como “1.234” são perigosas quando o contrato de dados não deixa claro se representam mil duzentos e trinta e quatro ou uma quantidade fracionária.
Para datas, a biblioteca datetime oferece interpretação por formato e objetos com informação de fuso. Exija um formato conhecido para cada origem e não troque dia e mês por tentativa. Quando o documento tiver apenas uma data, preserve essa granularidade, em vez de inventar um horário de abastecimento.
4. Concilie com frota, pagamentos e histórico
Depois de validar a extração, compare o documento com os cadastros e movimentos autorizados. Use uma combinação de veículo, estabelecimento, data, valor e referência da transação. Registre quais campos sustentaram o vínculo. Um pareamento aproximado deve aparecer como sugestão até ser confirmado.
| Verificação | O que pode indicar | Tratamento recomendado |
|---|---|---|
| Mesmo hash de arquivo | Reenvio dos mesmos bytes | Relacionar ao recebimento anterior |
| Total diferente do produto | Erro de leitura, desconto ou diferença de cálculo | Mostrar campos e conferir o documento |
| Veículo ausente no cadastro | Cadastro incompleto ou informação incorreta | Pedir identificação válida |
| Hodômetro inferior ao anterior | Leitura incorreta, troca de painel ou associação errada | Solicitar justificativa e evidência |
| Pagamento sem correspondência | Atraso de integração ou transação diferente | Reconciliar antes de concluir |
O consumo por distância exige cuidado com abastecimentos parciais, troca de motorista, manutenção e combustível usado em outras finalidades autorizadas. Não compare diretamente veículos e rotas diferentes com uma média única. Primeiro confira a qualidade do histórico e a comparabilidade dos registros.
Preço fora de uma referência também não prova irregularidade. Pode haver diferença de local, produto, data ou condição comercial. Mantenha a referência identificada e apresente a comparação como pergunta de auditoria. O sistema deve explicar o motivo da sinalização, sem atribuir intenção à pessoa envolvida.
Exemplo: distribuidora com frota em Ribeirão Preto
Imagine uma distribuidora de Ribeirão Preto que recebe fotos de comprovantes e um relatório do cartão corporativo. Este é um exemplo explicitamente ilustrativo, com valores sintéticos e sem resultados medidos. O objetivo é mostrar como uma pendência pode chegar ao revisor com contexto suficiente.
Um motorista envia um comprovante com 40 litros, preço unitário de R$ 6,00 e total de R$ 240,00. O pipeline registra esses valores como texto e depois como decimais. O cálculo confere, mas a identificação do veículo veio do formulário. O registro deixa essa origem explícita.
Na conciliação, há um pagamento compatível no relatório. O vínculo recebe a referência da transação e os campos utilizados no pareamento. O sistema ainda verifica se o abastecimento já havia sido associado a outro documento. Uma segunda fotografia do mesmo comprovante precisa de comparação por conteúdo, pois seu hash pode ser diferente.
Em outro documento, a leitura encontra “8” onde o papel pode mostrar “3”. A rotina numérica identifica diferença no total, mas não escolhe silenciosamente uma versão. A tela exibe o recorte, o valor lido e o cálculo. O revisor corrige o campo ou solicita nova foto, deixando um motivo registrado.
Somente depois dessas etapas a despesa segue para o sistema financeiro conforme a política da empresa. Se a documentação continuar insuficiente, o item permanece pendente com responsável e próxima ação. O fluxo evita que uma falha técnica de leitura seja apresentada como acusação contra o motorista.
6. Monte revisão humana, testes e operação
Entregue uma fila com motivos legíveis: documento cortado, total divergente, veículo não identificado ou pareamento inconclusivo. O revisor precisa abrir a evidência, corrigir o campo e registrar sua decisão. A orientação sobre coordenadas de trechos para revisão humana ajuda a desenhar essa interação.
Mantenha o valor anterior, o valor corrigido, a pessoa responsável e a justificativa. Uma correção humana não deve apagar a saída original do extrator. Esse histórico permite avaliar padrões de erro e reprocessar o lote quando houver alteração de regras ou de ferramenta.
Teste com documentos sintéticos e amostras autorizadas que representem fotos ruins, separadores diferentes, valores ilegíveis e comprovantes repetidos. Inclua indisponibilidade do OCR e falhas de integração. Verifique que uma retomada não cria duas despesas e que o item preserva sua posição na fila.
Meça erros por campo, documentos devolvidos e motivos de revisão. Compare o valor extraído com uma referência revisada, sem usar apenas o total de arquivos processados como sinal de qualidade. Uma esteira que termina rapidamente, mas perde comprovantes ou libera valores incorretos, não atende ao objetivo da auditoria.
Erros comuns
Um erro frequente é usar a confiança do OCR como autorização financeira. Esse sinal pode ajudar a priorizar revisão, mas não substitui a checagem de contexto. Outro é transformar qualquer diferença em fraude. Classifique a pendência e investigue causas alternativas antes de qualquer conclusão.
Também é arriscado normalizar números removendo toda pontuação sem conhecer o formato de origem. Guarde o texto e rejeite entradas ambíguas. Não arredonde litros e preço unitário prematuramente: aplique a precisão definida em cada etapa e registre a regra utilizada.
Por fim, evite acumular documentos e dados pessoais sem finalidade operacional. Controle acesso, retenção e descarte conforme a política aplicável. Logs técnicos devem usar identificadores internos sempre que a imagem completa ou o nome do motorista não forem necessários.
Perguntas frequentes
O pipeline consegue provar fraude?
Não pelo simples aparecimento de uma divergência. Ele reúne evidências e identifica inconsistências para análise. Conclusões sobre conduta exigem investigação e procedimentos apropriados, com possibilidade de corrigir erros de leitura e de cadastro.
Preciso usar um modelo de linguagem?
Não. Documentos padronizados podem ser tratados com OCR e regras. Um modelo pode ajudar a interpretar layouts variados, desde que a saída passe por validação e mantenha referência ao documento.
Por que não usar float?
Quantias precisam de controle explícito de representação e arredondamento. Decimal a partir de strings ajuda a trabalhar com os valores decimais informados. Ainda é necessário definir precisão, tolerância e regras de negócio.
O que fazer quando falta a placa?
Registre a ausência e procure uma associação autorizada em outra fonte. Preserve a origem dessa informação. Se o vínculo continuar incerto, peça confirmação em vez de atribuir o gasto automaticamente a um veículo.
