Para extrair valores monetários com IA, preserve o texto original, identifique a moeda e normalize o número com regras determinísticas antes de calcular. Um valor como “1.234,56” precisa virar uma representação interna explícita, como a string decimal “1234.56” acompanhada de “BRL”. A IA pode localizar o campo no documento; a aplicação deve decidir se a interpretação é válida.
Vírgula decimal, separador de milhar e arredondamento são problemas diferentes. Misturá-los numa instrução como “corrija os valores” dificulta a conferência. O caminho proposto aqui separa leitura, normalização, cálculo e aprovação para impedir que uma interpretação plausível entre silenciosamente no financeiro.
Resumo rápido
- Guarde o trecho monetário original e a localização no documento.
- Normalize usando a convenção confirmada da origem, sem adivinhar separadores.
- Armazene valor e moeda em campos diferentes.
- Faça cálculos com decimal ou unidades inteiras de escala definida.
- Registre a regra de arredondamento e encaminhe ambiguidades para revisão.
1. Separe o que foi lido do que será contabilizado
Um documento pode apresentar subtotal, desconto, imposto, frete e total. Encontrar uma sequência numérica não informa qual desses papéis ela cumpre. Antes de converter qualquer número, peça à etapa de extração que informe o rótulo próximo e a página. Se houver tabela, preserve também linha e coluna quando sua ferramenta conseguir recuperá-las.
Um registro de trabalho pode conter texto_original, papel, moeda, valor_decimal, origem e estado. O estado distingue pendente, interpretado, validado e revisado. Esses nomes são uma proposta de aplicação, não um formato obrigatório de fornecedor.
Não substitua o original quando uma pessoa corrigir a interpretação. Mantenha a primeira leitura, a correção, o responsável e o motivo. Isso permite distinguir um erro de OCR, que reconhece caracteres em imagens, de uma normalização inadequada ou de uma seleção errada do campo.
Se a empresa já processa demonstrativos, o guia de extração de tabelas de balanços patrimoniais ajuda a organizar a entrada. Aqui, o foco começa depois da localização do valor: como impedir que a representação numérica mude seu significado.
2. Defina uma política para separadores e moeda
A sequência “1,234” é ambígua sem contexto: pode representar um número com três casas decimais ou um inteiro agrupado. O idioma da conversa com a IA não resolve a convenção do documento. Um fornecedor brasileiro pode enviar uma planilha exportada por um sistema configurado em outro idioma.
Cadastre a convenção por origem comprovada, como um layout de exportação homologado. Permita uma exceção por arquivo quando houver evidência. Se o mesmo documento mistura convenções, trate o caso como revisão, sem aplicar uma substituição global.
| Entrada ilustrativa | Interpretação permitida | Condição |
|---|---|---|
| R$ 1.234,56 | BRL e “1234.56” | Convenção brasileira confirmada |
| USD 1,234.56 | USD e “1234.56” | Convenção de separadores confirmada |
| 1,234 | Pendente | Sem informação suficiente |
| (125,40) | Possível valor negativo | Layout documenta parênteses como sinal |
| R$ – | Ausente ou marcador | Não converter automaticamente para zero |
Use códigos de moeda em uma lista controlada do seu negócio. Não deduza reais apenas porque o cliente está no Brasil. O símbolo “$” isolado também não basta. Se a moeda vier do contrato ou do cadastro do fornecedor, registre essa origem separadamente do trecho extraído.
Defina ainda o tratamento de espaços, caracteres invisíveis, sinais e agrupamentos. Remover todo caractere diferente de dígito destrói negativos e separadores. Uma validação deve rejeitar agrupamentos incoerentes antes de produzir a representação interna.
3. Escolha a representação interna antes da integração
O padrão JSON usa ponto na parte fracionária de um número. Portanto, {"valor": 12,34} não representa doze reais e trinta e quatro centavos em JSON. Uma string como "12.34" pode transportar o decimal sem depender da conversão automática do consumidor. A sintaxe é descrita na RFC 8259.
Outra opção é transportar unidades menores como inteiro, com moeda e escala declaradas. Para um fluxo limitado a reais e centavos, “12345” centavos representa “123.45” reais. Não generalize essa escala para todos os produtos: preços unitários, taxas e rateios podem precisar de precisão intermediária maior.
O contrato entre sistemas deve dizer qual representação recebe. Uma API que espera centavos não pode receber um decimal em reais só porque ambos parecem números. Inclua exemplos de entrada e saída na homologação e valide a faixa aceita antes do envio.
No banco, escolha um tipo compatível com esse contrato. O PostgreSQL documenta numeric como tipo exato e explica como precisão e escala influenciam armazenamento e arredondamento. Confira o comportamento na documentação dos tipos numéricos antes de definir a coluna.
Saídas estruturadas ajudam a exigir campos, mas não demonstram que o valor pertence ao total correto. Caso use a OpenAI, consulte o catálogo de integrações OpenAI e ChatGPT e mantenha a validação monetária na aplicação.
4. Calcule e arredonde fora do modelo
Depois da normalização, faça a aritmética em código. Em Python, o módulo decimal permite trabalhar com números decimais e escolher arredondamentos. Construa o objeto a partir da string normalizada para evitar introduzir antes uma aproximação de ponto flutuante binário.
Um exemplo didático é Decimal("10.005").quantize(Decimal("0.01"), rounding=ROUND_HALF_UP), que resulta em 10.01. Com ROUND_HALF_EVEN, esse mesmo empate resulta em 10.00. Esses nomes indicam políticas distintas, descritas na referência oficial de decimal.
A escolha da política depende do contrato operacional e dos requisitos aplicáveis ao processo. O exemplo não define uma regra fiscal. Valide a decisão com o responsável financeiro e registre-a na configuração. Evite deixar a biblioteca, o banco e a planilha aplicarem padrões diferentes sem que ninguém perceba.
Defina também quando arredondar. Arredondar cada item e depois somar pode produzir um total diferente de somar os valores intermediários e arredondar no final. O sistema precisa reproduzir o método esperado pelo documento, preservando valores intermediários suficientes para explicar a diferença.
Quando houver rateio, determine quem recebe o resíduo de centavos e mantenha uma regra reproduzível. Distribuir o restante de forma estável entre itens elegíveis permite refazer a conta. Pedir à IA que “ajuste para bater” esconde a decisão e pode mudar o resultado em uma nova execução.
5. Exemplo: conferência de despesas em Belo Horizonte
Considere uma assistência técnica de Belo Horizonte que recebe notas e recibos de compras de peças. O caso é ilustrativo. A equipe quer preparar lançamentos para revisão, sem autorizar pagamentos automaticamente.
Um recibo contém “R$ 1.250,00” como total, mas a tabela também mostra um código “125000”. A extração devolve ambos como candidatos, cada um com seu rótulo e localização. O validador aceita somente o candidato associado ao total, conforme a política do documento, e mantém o código fora do campo monetário.
Outro arquivo apresenta “1,250” sem moeda e sem cabeçalho legível. A aplicação marca ambiguidade_separador e pede conferência. O revisor abre o documento, consulta a origem e registra a decisão. O sistema não escolhe a interpretação que mais se aproxima do orçamento da compra.
Para uma despesa parcelada, o registro guarda valor total, quantidade de parcelas e valores individuais em campos diferentes. O validador compara a soma das parcelas com o total segundo a tolerância documentada. Uma diferença não vira desconto presumido: permanece uma pendência com evidência acessível.
A tela exibe o texto do recibo ao lado do decimal interpretado e da moeda. O operador confirma o campo antes da exportação. Para conectar essa etapa a extratos, veja o fluxo de conciliação de despesas com IA, mantendo separadas extração, aprovação e conciliação.
6. Teste a política com casos que costumam quebrar
Monte uma coleção pequena de documentos sintéticos e exemplos autorizados. Inclua vírgula decimal, ponto decimal, valores negativos, zeros, ausência de moeda, espaços entre grupos e números com mais casas que o lançamento aceita. Para cada caso, escreva previamente a saída esperada ou a razão para rejeitar.
Adicione casos em que o número está correto, mas o papel está errado: frete interpretado como total, subtotal anterior ao desconto e valor de uma parcela usado como compra inteira. Essa avaliação impede que um teste limitado ao conversor numérico aprove uma extração semanticamente equivocada.
Teste o caminho completo até a exportação. Confira se o CSV mantém a coluna como texto quando necessário, se o banco conserva a escala e se o sistema de destino interpreta a unidade corretamente. Uma tela bem formatada não revela que uma etapa intermediária multiplicou o valor por cem.
Inclua reapresentação do mesmo documento. O identificador do lançamento deve impedir uma segunda inclusão indevida. A verificação de duplicidade não deve depender apenas do valor, porque compras distintas podem ter o mesmo total. Combine referência documental e regras do processo.
Antes de liberar alterações na normalização, execute novamente a coleção de casos. Registre quais resultados mudaram e por quê. Se uma mudança afeta lançamentos já aprovados, não reescreva o histórico silenciosamente; produza uma fila de reconferência com decisão explícita.
Erros comuns
Transformar ausência em zero. Campo vazio, trecho ilegível e valor efetivamente zero são situações diferentes. Use um estado de ausência para que o relatório financeiro não pareça completo quando faltam dados.
Confiar no JSON como prova. Um objeto pode estar bem formado e conter o subtotal errado. A orientação de saídas estruturadas da OpenAI trata o formato; a conferência contra a fonte continua necessária.
Converter moeda implicitamente. Normalizar separadores não é fazer câmbio. Se houver conversão, registre moeda de origem, moeda de destino, taxa utilizada e origem dessa taxa em uma etapa própria.
Arredondar para esconder diferenças. Uma tolerância deve ser definida antes da operação, com justificativa. Não aumente a margem porque determinado arquivo não fechou. Diferenças podem indicar item ausente, duplicado ou incorretamente classificado.
Perguntas frequentes
Posso pedir que a IA devolva tudo em centavos?
Pode usar essa instrução como auxílio, mas valide o resultado com a evidência original e a escala contratada. Um erro de separador também pode produzir um inteiro perfeitamente válido. Para diminuir essa dependência, peça o texto original e faça a conversão em código.
Devo aceitar valores com mais de duas casas?
Depende do campo. Um preço unitário ou uma taxa pode exigir precisão diferente do total liquidado. Defina escala por campo, preserve a precisão intermediária e aplique o arredondamento somente no ponto aprovado pelo processo.
Como lidar com um símbolo de moeda ausente?
Use uma origem externa autorizada, como o contrato daquele fornecedor, quando o processo permitir. Registre que a moeda foi herdada dessa regra. Sem evidência suficiente, mantenha o registro pendente em vez de assumir a moeda mais comum.
Preciso guardar a imagem de cada valor?
O método de evidência depende da política documental. Pode ser o arquivo original com página e coordenadas ou um recorte controlado. Defina acesso e retenção para permitir conferência sem criar cópias desnecessárias de documentos sensíveis.
