Conciliação Financeira com Python: Guia Prático

Conciliação financeira é uma das automações mais úteis para quem trabalha com Python em empresas brasileiras. O problema aparece em bancos, fintechs, marketplaces, áreas de cobrança, controladoria, operações, e-commerce, contabilidade, seguros e qualquer time que precise conferir se duas fontes de dados contam a mesma história. Um sistema diz que o cliente pagou. O extrato bancário mostra outro valor. A planilha de vendas tem uma data. O gateway de pagamento liquida em outra. Alguém precisa descobrir se está tudo certo, se existe atraso, taxa, duplicidade, estorno ou lançamento faltando.

Python entra bem nesse cenário porque lê arquivos diferentes, aplica regras de negócio, gera evidência e deixa o processo repetível. Em vez de abrir cinco planilhas manualmente, filtrar linhas, copiar fórmulas e torcer para ninguém quebrar uma coluna, você pode criar um fluxo que importa CSV, XLSX, JSON ou dados de API, normaliza nomes, datas e valores, compara registros e produz um relatório de divergências. Para quem busca vaga de analista de dados, automação, operações financeiras, QA de dados ou engenharia de dados júnior, esse é um projeto de portfólio muito mais próximo do trabalho real do que uma calculadora genérica.

Neste guia, vamos montar uma visão prática de conciliação financeira com Python. O foco não é dar orientação contábil, fiscal ou jurídica. O objetivo é mostrar como organizar um projeto técnico seguro, auditável e convincente usando pandas, validação, logs e boas práticas de dados. Se você ainda está consolidando a base, revise também Python para automação de planilhas, Python e Excel com openpyxl, Pandas em Python e testes com pytest.

O que é conciliação financeira

Conciliação financeira é o processo de comparar registros de origens diferentes para confirmar se eles representam a mesma operação. Em uma empresa pequena, isso pode significar comparar vendas de uma loja virtual com depósitos recebidos no banco. Em uma operação maior, pode envolver ERP, adquirente, gateway de pagamento, antifraude, plataforma de assinatura, nota fiscal, contabilidade e data warehouse.

O ponto central é responder perguntas como:

1. todo pagamento esperado foi recebido?
2. todo recebimento bancário tem uma venda correspondente?
3. o valor líquido bate depois de taxas, antecipações e estornos?
4. existem transações duplicadas?
5. há diferença de data por causa de liquidação, fim de semana ou feriado?
6. quais divergências precisam de análise humana?

Esse tipo de trabalho é comum em vagas que citam Python, SQL, Excel, Power BI, ERP, APIs, conciliação, risco, controladoria, tesouraria, cobrança, operações e auditoria. A automação não elimina o julgamento de negócio; ela reduz erro manual, organiza evidências e separa casos simples de casos que exigem investigação.

Exemplo de cenário para portfólio

Um bom projeto de portfólio pode simular uma empresa que vende assinaturas mensais. Você terá três fontes fictícias:

Cada venda tem pedido_id, cliente_id, data_venda, valor_bruto e status. Cada pagamento tem pedido_id, data_pagamento, valor_bruto, taxa, valor_liquido e status_gateway. O extrato tem data_credito, descricao, valor e talvez uma referência parcial ao pedido.

Com dados fictícios, você consegue demonstrar o fluxo completo sem expor informação sensível. Isso é importante: nunca publique extratos reais, CPF, e-mail de cliente, token de API, nota fiscal, boleto, chave Pix ou dados bancários em repositório público. Use dados sintéticos e deixe claro no README que qualquer uso real exigiria revisão de segurança, privacidade e regras internas.

Uma estrutura simples pode começar assim:

conciliacao-financeira-python/
├── README.md
├── pyproject.toml
├── data/
│   ├── vendas.csv
│   ├── pagamentos_gateway.csv
│   └── extrato_bancario.csv
├── src/
│   └── conciliacao/
│       ├── __init__.py
│       ├── carregar.py
│       ├── normalizar.py
│       ├── conciliar.py
│       └── relatorio.py
└── tests/
    └── test_conciliacao.py

O diferencial não está em ter muitos arquivos. Está em mostrar um processo claro: entrada, limpeza, regras, saída e verificação.

Preparando os dados com pandas

Para começar, instale as dependências principais:

python -m venv .venv
source .venv/bin/activate
pip install pandas openpyxl pytest

Se usar uv, o fluxo fica mais moderno:

uv init conciliacao-financeira-python
cd conciliacao-financeira-python
uv add pandas openpyxl
uv add --dev pytest

O primeiro cuidado é padronizar colunas. Em conciliação, pequenas diferenças atrapalham muito: data como texto, vírgula decimal, espaço antes do código, valor negativo para estorno, status escrito de formas diferentes e identificador com zeros à esquerda. Antes de comparar qualquer coisa, normalize.

Um exemplo mínimo:

import pandas as pd


def carregar_vendas(caminho: str) -> pd.DataFrame:
    vendas = pd.read_csv(caminho)
    vendas["pedido_id"] = vendas["pedido_id"].astype(str).str.strip()
    vendas["data_venda"] = pd.to_datetime(vendas["data_venda"], errors="coerce")
    vendas["valor_bruto"] = pd.to_numeric(vendas["valor_bruto"], errors="coerce")
    vendas["status"] = vendas["status"].str.lower().str.strip()
    return vendas

Esse código parece simples, mas resolve uma parte grande do problema. errors="coerce" transforma valores inválidos em NaT ou NaN, permitindo detectar dados ruins em vez de quebrar silenciosamente. Em projeto profissional, você deve registrar quantas linhas vieram com data inválida, valor ausente ou status inesperado.

Criando regras de conciliação

Depois de carregar e normalizar, defina regras explícitas. Não misture regra de negócio no meio de filtros soltos. Uma conciliação básica pode ter três etapas:

1. comparar vendas aprovadas com pagamentos aprovados por pedido_id;
2. verificar se valor_bruto - taxa bate com valor_liquido dentro de uma tolerância;
3. comparar pagamentos liquidados com lançamentos bancários por referência, data e valor.

Um exemplo inicial de batimento entre vendas e pagamentos:

def conciliar_vendas_pagamentos(vendas: pd.DataFrame, pagamentos: pd.DataFrame) -> pd.DataFrame:
    vendas_aprovadas = vendas[vendas["status"] == "aprovado"]
    pagamentos_ok = pagamentos[pagamentos["status_gateway"] == "aprovado"]

    base = vendas_aprovadas.merge(
        pagamentos_ok,
        on="pedido_id",
        how="outer",
        suffixes=("_venda", "_pagamento"),
        indicator=True,
    )

    base["diferenca_bruta"] = base["valor_bruto_venda"] - base["valor_bruto_pagamento"]
    base["situacao"] = "conciliado"
    base.loc[base["_merge"] == "left_only", "situacao"] = "sem_pagamento"
    base.loc[base["_merge"] == "right_only", "situacao"] = "pagamento_sem_venda"
    base.loc[base["diferenca_bruta"].abs() > 0.01, "situacao"] = "valor_divergente"
    return base

Esse relatório já separa casos importantes. sem_pagamento pode indicar inadimplência, atraso ou falha de integração. pagamento_sem_venda pode indicar venda ausente no sistema, importação incompleta ou identificador errado. valor_divergente pode ser desconto, cupom, taxa aplicada em lugar errado ou erro de arredondamento.

Não esconda essas hipóteses. Um bom README deve explicar o que cada situação significa e quais casos exigem revisão humana.

Lidando com datas e tolerâncias

Conciliação real raramente bate apenas por igualdade perfeita. Pagamento em cartão pode liquidar dias depois. Pix pode cair no mesmo dia, mas aparecer com descrição diferente. Boleto pode ter multa ou juros. Estorno pode vir com valor negativo. Marketplace pode descontar comissão antes de repassar.

Por isso, use tolerâncias documentadas. Por exemplo:

Tolerância não pode virar desculpa para aceitar qualquer coisa. Se o projeto permite diferença de R$ 0,01, explique por quê. Se permite janela de três dias, mostre que isso representa liquidação, não um chute. Essa clareza passa maturidade técnica.

Gerando relatório auditável

O resultado da conciliação precisa ser útil para alguém. Não basta imprimir True ou False no terminal. Gere uma saída que uma pessoa de operações consiga abrir, filtrar e discutir.

Você pode criar um arquivo Excel com abas:

1. resumo: contagem por situação e valor total divergente;
2. conciliados: linhas que bateram;
3. divergencias: casos que precisam de revisão;
4. dados_invalidos: datas, valores ou identificadores problemáticos.

Com pandas:

def exportar_relatorio(resultado: pd.DataFrame, caminho_saida: str) -> None:
    resumo = (
        resultado.groupby("situacao", dropna=False)
        .agg(qtd=("pedido_id", "count"), diferenca_total=("diferenca_bruta", "sum"))
        .reset_index()
    )

    divergencias = resultado[resultado["situacao"] != "conciliado"]
    conciliados = resultado[resultado["situacao"] == "conciliado"]

    with pd.ExcelWriter(caminho_saida, engine="openpyxl") as writer:
        resumo.to_excel(writer, sheet_name="resumo", index=False)
        divergencias.to_excel(writer, sheet_name="divergencias", index=False)
        conciliados.to_excel(writer, sheet_name="conciliados", index=False)

Se quiser avançar, conecte esse relatório ao guia de geração de PDF com Python para criar uma versão executiva. Mas mantenha a planilha detalhada como evidência operacional, porque ela permite investigar linha por linha.

Testes para regras financeiras

Conciliação sem teste vira uma planilha automatizada frágil. Escreva pelo menos testes pequenos para as regras principais:

import pandas as pd

from conciliacao.conciliar import conciliar_vendas_pagamentos


def test_detecta_venda_sem_pagamento():
    vendas = pd.DataFrame([
        {"pedido_id": "1001", "status": "aprovado", "valor_bruto": 120.0},
    ])
    pagamentos = pd.DataFrame(columns=["pedido_id", "status_gateway", "valor_bruto"])

    resultado = conciliar_vendas_pagamentos(vendas, pagamentos)

    assert resultado.loc[0, "situacao"] == "sem_pagamento"

Também teste valor divergente, pagamento sem venda e caso conciliado. Em uma entrevista, isso mostra que você não apenas manipulou pandas, mas pensou em confiabilidade. Para reforçar a qualidade, use ruff e pytest no projeto, como explicado no artigo sobre Ruff em Python.

Cuidados com LGPD e segurança

Projetos financeiros costumam tocar dados pessoais e sensíveis. Mesmo quando o objetivo é técnico, trate privacidade com seriedade. Para portfólio público:

1. use nomes, e-mails, CPFs, chaves Pix e contas bancárias fictícias;
2. não publique extratos reais, ainda que parcialmente mascarados;
3. não suba .env, token de API ou credencial de banco;
4. não afirme que o projeto é “LGPD compliant” sem revisão especializada;
5. explique que os dados são sintéticos e servem apenas para demonstração.

Em uma empresa real, o processo também precisa de controle de acesso, retenção, trilha de auditoria, aprovação de regras e monitoramento de falhas. Python resolve a automação, mas a governança depende do contexto organizacional.

Como transformar em projeto de carreira

Para virar portfólio, o projeto precisa ser fácil de entender. O README deve responder:

1. qual problema de negócio o projeto simula;
2. quais arquivos entram no processo;
3. quais regras de conciliação foram implementadas;
4. como rodar localmente;
5. como executar testes;
6. quais divergências o relatório identifica;
7. quais limitações existem.

Um bom pitch seria:

Projeto em Python para conciliar vendas, pagamentos de gateway e extrato bancário usando pandas, regras de tolerância, testes automatizados e relatório Excel com divergências auditáveis.

Esse pitch conversa com vagas de operações, dados, finanças, QA de dados e automação. Se você quer posicionar o projeto para primeira vaga, conecte-o ao roadmap Python 2026 e ao guia de projetos de portfólio Python. Se quer ampliar para mercado de trabalho geral, o conteúdo de projetos de portfólio para programação júnior ajuda a organizar a apresentação para recrutadores.

Próximos passos

Depois da primeira versão, evolua com cuidado. Você pode adicionar leitura de API, validação com Pandera, persistência em SQLite, interface simples em Streamlit, dashboard no Power BI ou envio automático de e-mail. Mas não coloque tudo de uma vez. Um projeto pequeno, bem testado e bem explicado costuma impressionar mais do que uma arquitetura grande que ninguém consegue rodar.

Também vale criar dados com cenários variados: pagamento atrasado, taxa diferente, estorno, duplicidade, venda cancelada, lançamento bancário sem referência e data inválida. Esses casos mostram que você pensou no mundo real.

Conciliação financeira com Python é um tema forte porque une automação, dados, negócio e carreira. É técnico o suficiente para demonstrar pandas, funções, testes e organização de projeto, mas concreto o bastante para uma pessoa não técnica entender o valor. Se o seu objetivo é sair de exercícios genéricos e construir um portfólio alinhado a vagas brasileiras, esse é um ótimo projeto para executar com capricho.