Código Python: livro diário com partidas dobradas validadas (download grátis)

Código Python: livro diário com partidas dobradas validadas (download grátis)

Um lançamento que não fecha é o erro mais caro e mais silencioso da contabilidade de uma pequena empresa: ele entra no sistema, ninguém percebe e três meses depois as contas não fecham. Este programa de console lê o seu livro diário de um arquivo de texto, confere cada lançamento pelas regras das partidas dobradas e separa os que não fecham antes que cheguem ao sistema. Foi escrito para o dono de um negócio pequeno que quer entender os próprios números, para o auxiliar que digita lançamentos o dia inteiro e para o contador que recebe documentos de terceiros e precisa de uma conferência automática antes de olhar tudo à mão. É um arquivo só, não instala nada e roda igual no Windows, no Linux e no Mac.

O que vem no ZIP

A entrada usa um formato que qualquer pessoa prepara numa planilha: uma linha por linha do lançamento, com o número do lançamento, a data, o código da conta, o nome da conta e os dois lados do movimento. Ao executar, aparecem também dois arquivos de saída com números simples, prontos para abrir no Excel: salida/diario.csv, com os lançamentos aceitos, e salida/rechazados.csv, com o número de cada lançamento rejeitado e o motivo escrito em palavras.

O que o programa faz

1. Lê datos/asientos.csv. Cada linha traz o número do lançamento, a data, a conta, o nome da conta, o débito e o crédito: uma linha é uma linha do lançamento, não o lançamento inteiro.
2. Agrupa as linhas pelo número do lançamento, porque um lançamento pode ter várias linhas de débito e de crédito. Esse é o lançamento composto, o pão de cada dia de qualquer negócio.
3. Soma os débitos e os créditos do lançamento e confere quatro coisas: que as duas somas sejam exatamente iguais, que cada linha traga um só valor e maior que zero, que a conta seja só dígitos com no mínimo quatro, e que a data exista de verdade no calendário.
4. Se encontra um único erro, rejeita o lançamento inteiro e escreve o motivo em linguagem clara. Nunca lança meia verdade: ou entra completo ou não entra.
5. Mostra os lançamentos aceitos um por um com a sua linha de conferência, a lista dos rejeitados e o resumo por conta com saldo devedor ou credor.
6. Fecha com a conferência global de débitos contra créditos e grava os dois arquivos de saída para você revisar com calma.

Como executar

Você precisa do Python 3.11 ou superior e de mais nada. O programa usa somente a biblioteca padrão, então não há pacotes para instalar, nem ambientes virtuais para criar, nem dependências que quebram no ano seguinte.

1. Baixe o ZIP e descompacte em uma pasta, por exemplo na área de trabalho.
2. Se ainda não tem o Python, instale da página oficial. No Windows, marque a caixa que adiciona o Python ao PATH durante a instalação.
3. Abra o terminal: no Windows o prompt de comando ou o PowerShell, no Mac e no Linux o terminal de sempre.
4. Entre na pasta onde descompactou o pacote com o comando cd.
5. Execute python libro_diario.py. Você verá o diário na tela e os dois arquivos novos dentro da pasta salida.

O código, explicado

Quatro trechos bastam: o cabeçalho, a caixa de ferramentas, o coração da validação e a decisão sobre o que entra no diário. Todo o resto é mostrar resultados e gravar arquivos.

O cabeçalho. O programa se apresenta, diz com que versão do Python foi testado e deixa claro que não há nada para instalar. É a frase que economiza mais dúvidas: quem baixa o pacote sabe desde a primeira linha que só precisa do Python.

# ==========================================================================
#  LIVRO DIÁRIO COM PARTIDAS DOBRADAS VALIDADAS
#  Código Python didático para contabilidade · Kardex Tauro · kardex-tauro.muisca.co
#  O que faz: lê os lançamentos de datos/asientos.csv, valida cada um pelas regras
#  das partidas dobradas, mostra o diário e salva salida/diario.csv e salida/rechazados.csv
#  Testado com Python 3.11. Somente biblioteca padrão: nada para instalar.
# ==========================================================================

A caixa de ferramentas. Três importações e nenhuma surpresa. Decimal é a chave do exercício: dinheiro não se soma com decimais binários, porque o arredondamento do computador produz centavos fantasma que depois ninguém explica. pathlib monta caminhos que funcionam igual no Windows, no Linux e no Mac. E o comentário que vem depois fixa a ideia de fundo: débito e crédito não são bom e ruim, são os dois pratos da mesma balança.

from decimal import Decimal, ROUND_HALF_UP          # Decimal: dinheiro não se calcula com decimais binários (float)
from pathlib import Path                            # pathlib: caminhos que funcionam no Windows, Linux e Mac

# PARTIDAS DOBRADAS: o que se debita de um lado se credita do outro, pelo mesmo valor
# Um lançamento pode trazer várias linhas de débito e de crédito: é o lançamento composto
# Débito não é bom nem crédito é ruim: são os dois pratos da mesma balança

A validação. Aqui está a parte que vale dinheiro. A função percorre as linhas do lançamento, acumula débitos e créditos e devolve uma lista de motivos: se a lista volta vazia, o lançamento está certo. Cada regra é conferida separadamente e todas estão escritas em linguagem de gente, porque a mensagem de erro é a única coisa que o usuário vê quando algo falha. A última é o coração da coisa: se os débitos e os créditos não são iguais, o lançamento não entra.

def validar(lineas: list[dict]) -> list[str]:
    """Confere um lançamento e devolve a lista de motivos de rejeição (vazia = aceito)."""
    errores = []
    debitos = CERO
    creditos = CERO
    for numero, linea in enumerate(lineas, start=1):
        debito = linea["debito"]
        credito = linea["credito"]
        # Regra 2: cada linha traz UM só valor (débito ou crédito) e maior que zero
        if (debito != "") == (credito != ""):
            errores.append(f"Linha {numero}: traz débito e crédito ao mesmo tempo, ou nenhum dos dois")
        else:
            importe = debito or credito
            if not importe.replace(".", "").isdigit() or Decimal(importe) <= CERO:
                errores.append(f"Linha {numero}: o valor tem que ser um número maior que zero")
            elif debito != "":
                debitos += Decimal(debito)
            else:
                creditos += Decimal(credito)
        # Regra 3: a conta é só dígitos, no mínimo 4 (nada de letras nem símbolos)
        if not (linea["cuenta"].isdigit() and len(linea["cuenta"]) >= 4):
            errores.append(f"Linha {numero}: a conta deve ser só dígitos, no mínimo 4")
        # Regra 4: a data tem que existir de verdade no calendário
        try:
            date.fromisoformat(linea["fecha"])
        except ValueError:
            errores.append(f"Linha {numero}: a data deve ser AAAA-MM-DD e existir no calendário")
    # Regra 1, o coração da coisa: débitos = créditos. Se não fecha, o lançamento não entra
    if debitos != creditos:
        errores.append(f"Os débitos e os créditos não fecham: DÉBITOS {miles(debitos)} <> CRÉDITOS {miles(creditos)}")
    return errores

A decisão. Este bloco do programa principal marca o caráter do exercício: os lançamentos com erro vão para uma lista separada e os demais para o diário. Não existe o estado intermediário. Um lançamento desbalanceado é rejeitado inteiro, o motivo fica guardado e o diário nunca fica partido entre uma linha que entrou e outra que não entrou.

    aceptados = {}
    rechazados = []
    for numero, lineas in asientos.items():
        errores = validar(lineas)
        if errores:
            # Um lançamento desbalanceado não se lança pela metade: rejeita-se inteiro
            rechazados.append((numero, lineas, errores))
        else:
            aceptados[numero] = lineas
    print(f"Lançamentos aceitos: {len(aceptados)}")
    print(f"Lançamentos rejeitados: {len(rechazados)}")

O que você vai ver na tela

Com os dados de exemplo o programa lê seis lançamentos, aceita cinco e rejeita um. O cabeçalho da saída resume tudo sem enfeite:

Lançamentos lidos: 6
Lançamentos aceitos: 5
Lançamentos rejeitados: 1

O lançamento que não entra é o número 4, de 12 de março: um aluguel pago pelo banco. Como está escrito em datos/asientos.csv, as suas duas linhas são estas:

O débito registra 500000 e o crédito registra 450000: faltam 50000 em algum lugar e o lançamento não fecha. O programa diz isso sem rodeios e aponta o lançamento inteiro, não uma linha solta:

LANÇAMENTO 4   DATA 2026-03-12
  Motivo: Os débitos e os créditos não fecham: DÉBITOS 500000 <> CRÉDITOS 450000

Esse é o momento didático do exercício, e é o que quase nenhum sistema mostra: as duas cifras frente a frente, na mesma tela, com a diferença que falta à vista. Com essa mensagem o erro se corrige em dois minutos; sem ela, o descuadre aparece três meses depois como um mistério nas contas.

Depois da lista de rejeitados vem o resumo por conta: cada conta mostra o que somou ao débito, o que somou ao crédito e de que lado fica o seu saldo, devedor ou credor. Os totais somam 2220800 de cada lado, e a última linha confirma: TOTAL DÉBITOS = TOTAL CRÉDITOS: CONFERE.

Erros comuns e dicas

• O arquivo tem que estar em UTF-8. Se você reescrever com um editor antigo e salvar em outra codificação, os nomes com acento saem errados e o programa percebe.
• Execute de dentro da pasta do pacote. O programa descobre a própria pasta a partir do caminho do arquivo, então encontra os dados de onde quer que você o chame.
• Os valores ficam simples no arquivo de entrada. Escreva o valor como número inteiro, sem separador de milhar e sem decimais: a validação exige só dígitos, com um ponto decimal opcional.
• Um valor por linha. Nunca preencha débito e crédito na mesma linha, nem deixe os dois vazios: essa linha é marcada como erro e leva o lançamento inteiro para a lista de rejeitados.
• As contas são códigos. Só dígitos, no mínimo quatro. Se precisar de hierarquia, acrescente mais dígitos, não letras nem traços.
• Não repita o número de um lançamento em datas diferentes. Como o programa agrupa por número, juntaria linhas que não pertencem ao mesmo lançamento.
• Comece com os seus dados. Troque o arquivo de exemplo por dez lançamentos seus e compare a saída com o seu livro: é a melhor forma de ver como se digita na sua equipe.

Quando isto não basta

Este programa é um filtro de entrada, não um sistema de contabilidade: não controla terceiros, nem carteira, nem estoque, nem numeração sequencial, nem permissões por usuário. Ele serve enquanto o volume é pequeno e enquanto uma só pessoa revisa o arquivo antes de lançar. Quando o negócio cresce e várias mãos trabalham ao mesmo tempo, o passo natural é um software que valide as partidas dobradas no momento da digitação e que deixe o rastro de quem fez cada coisa. Aí faz sentido o Kardex Tauro, um programa grátis que organiza estoque e movimentos. A regra é simples: o script para entender e controlar; o software para quando a planilha e o arquivo de texto já não bastam.

Guarde o pacote como base do seu próprio controle interno: troque as regras de validação pelas regras do seu negócio, acrescente uma coluna com o centro de custo e você terá um diário sob medida em uma tarde.