Código Python: ficha de estoque PEPS (FIFO) por lotes (download grátis)

Código Python: ficha de estoque PEPS (FIFO) por lotes (download grátis)

Você comprou o mesmo produto três vezes no mês e cada compra saiu por um preço diferente. Vendeu várias vezes e, no fechamento, bate aquela pergunta incômoda: quanto custou de verdade o que eu vendi? O método PEPS (primeiro que entra, primeiro que sai) responde com uma regra simples: sai primeiro o que é mais antigo, avaliado pelo custo da compra mais velha que ainda está no depósito. Este programa em Python aplica essa regra lote a lote, movimento a movimento, e no fim grava a prova: de qual lote veio cada unidade vendida e a que custo. Foi feito para o dono de uma pequena empresa que quer entender os próprios números, para o contador que confere o custo das mercadorias vendidas antes de assinar um balanço e para o encarregado de estoque que precisa explicar por que o estoque final não vale o mesmo em todos os métodos. Não é preciso saber programar: o arquivo roda do jeito que veio.

O pacote é leve, não usa internet e não instala nada. Traz movimentos de exemplo, então você vê o resultado na tela em menos de um minuto e depois troca esse arquivo pelos seus dados, mantendo as mesmas colunas.

O que o programa faz

1. Lê o arquivo datos/movimientos.csv, em que cada linha é um movimento: produto, data, tipo (compra ou venda), detalhe, quantidade e, quando é compra, custo unitário.
2. Abre um lote novo a cada compra, com a data, a quantidade e o custo. Um lote é apenas «tantas unidades compradas por este preço».
3. Quando chega uma venda, retira unidades do lote mais antigo. Se esse lote não for suficiente, passa para o próximo mais antigo, e assim por diante até cobrir a quantidade vendida.
4. Soma o custo de cada pedaço consumido, com arredondamento em centavos, e chega ao custo PEPS daquela venda.
5. Avalia o saldo que fica no depósito pelos lotes que sobraram: no PEPS, os que sobram são os mais recentes, e por isso o estoque final tende a se parecer com os preços de hoje.
6. Imprime a ficha em colunas, imprime o detalhe dos lotes consumidos venda por venda e fecha com um resumo por produto.
7. Confere se o saldo fecha (entradas menos saídas) e grava dois arquivos CSV prontos para o Excel.

Como executar

Você precisa do Python 3.11 ou mais novo, e de nada mais: o programa usa somente a biblioteca padrão. Descompacte o ZIP numa pasta, abra o terminal nessa pasta e execute o programa:

python kardex_peps.py

No Windows, o duplo clique também funciona quando o Python está instalado, mas a janela se fecha sozinha no fim; por isso o terminal é o melhor hábito, porque você lê o resultado inteiro. Não há nada para instalar, não é preciso cadastro e nenhum dado sai do seu computador. Se o sistema disser que não encontra «python», tente «py» no Windows ou «python3» no Linux e no Mac.

O código, explicado

Estes são os pedaços que fazem o trabalho. O primeiro mostra como um lote é aberto quando a mercadoria entra: cada compra acrescenta um lote novo à lista, com quantidade e custo, e deixa a linha da ficha já com o valor da entrada calculado.

        if movimiento["tipo"] == TIPO_ENTRADA:
            # Entrada: cada compra abre un LOTE nuevo con su cantidad y su costo.
            costo = Decimal(movimiento["custo_unitario"])
            estado["lotes"].append({"fecha": fila["fecha"], "cantidad": cantidad, "costo": costo})
            fila.update(e_cant=cantidad, e_vu=costo, e_val=redondear(cantidad * costo))

O coração do método está na venda. O programa olha sempre o primeiro lote da lista, que é o mais antigo, e decide: se o lote inteiro couber no que ainda falta cobrir, ele é consumido por completo e sai da lista; se não couber, o programa retira só a parte necessária e deixa o resto do lote para a venda seguinte. Esse é todo o segredo do PEPS, e explica por que uma única venda pode acabar avaliada com dois custos diferentes.

            while pendiente > 0 and estado["lotes"]:
                lote = estado["lotes"][0]
                if lote["cantidad"] <= pendiente:
                    toma = lote["cantidad"]
                    estado["lotes"].pop(0)
                else:
                    toma = pendiente
                    lote["cantidad"] -= toma
                pendiente -= toma
                valor = redondear(toma * lote["costo"])

Com o saldo acontece algo que surpreende muita gente: ele não é avaliado por uma média, e sim pelos lotes que ainda existem. Como o PEPS leva primeiro o que é velho, o que fica é o novo, e por isso o saldo aparece pelo custo mais recente. Esse detalhe é o que faz o estoque final mudar de valor de um método para outro, mesmo com as unidades exatamente iguais.

        fila["saldo_cant"] = sum((lote["cantidad"] for lote in estado["lotes"]), Decimal("0"))
        # # O saldo é avaliado pelos lotes que SOBRAM: o PEPS deixa o estoque pelo custo mais recente
        fila["saldo_val"] = redondear(sum((lote["cantidad"] * lote["costo"] for lote in estado["lotes"]), Decimal("0")))

E por último a parte que, para mim, é a mais útil na conversa com um contador: o programa imprime, venda por venda, quantas unidades saíram de cada lote e a que custo. Quando uma venda é atendida por dois lotes, aparecem as duas linhas com os dois custos, e essa é a prova documental de como o custo das mercadorias vendidas foi montado.

        for venta in estado["ventas"]:
            print(f"Saída {venta['fecha']}: {miles(venta['cantidad'])} unidades")
            for consumo in venta["consumos"]:
                print(f"  lote {consumo['fecha_lote']}   {miles(consumo['cantidad']):>10} x {miles(consumo['costo']):>12} = {miles(consumo['valor']):>16}")

O que você vai ver na tela

A impressão começa com um cabeçalho, segue com um quadro por produto, depois o bloco de lotes consumidos e termina com o resumo. Um pedaço do cabeçalho real é este:

================================================================================
  FICHA DE ESTOQUE PEPS (FIFO) POR LOTES
  Código Python didático · Kardex Tauro · kardex-tauro.muisca.co
================================================================================
Movimentos lidos: 10

Produto: Cimento cinza 50 kg

O bloco mais didático é o dos lotes consumidos: venda por venda, ele diz de qual lote saiu cada unidade. Abaixo ele aparece com os valores planos, do jeito que o arquivo CSV guarda, para você copiar para a planilha; no console você vai vê-los com o separador de milhar do seu idioma. As seis linhas são das quatro vendas do cimento e das duas vendas do cabo:

A segunda venda de cimento é a que merece atenção: pediu 20 unidades, o lote antigo tinha só 10, então o programa tirou 10 pelo custo antigo e 10 pelo custo novo. Essa mistura é exatamente o que acontece no depósito quando o lote anterior acaba.

Depois vem o resumo por produto, que é a conferência rápida: soma entradas, saídas e saldo, calcula o custo PEPS das vendas de cada produto e avisa se o saldo fecha com as entradas menos as saídas.

Repare num detalhe que vale ouro para explicar o PEPS: o cimento é consumido do lote mais velho para o mais novo e o saldo final fica pelo custo da compra mais recente, o mais alto dos três. As unidades finais são as mesmas que a média ponderada daria; o que muda é o valor pendurado nelas, e essa mudança mexe no custo das mercadorias vendidas e no lucro do mês.

Erros comuns e dicas

• Datas em formatos estranhos: use ano-mês-dia e ordene as linhas da mais antiga para a mais recente. O programa respeita a ordem do arquivo, não reorganiza por você.
• Vender mais do que existe: quando uma venda pede mais unidades do que os lotes cobrem, o programa avisa com uma mensagem clara em vez de inventar um número. Confira esse caso antes de publicar os seus números.
• Trocar os nomes das colunas: o programa espera exatamente os do exemplo. Se o seu sistema exporta outros nomes, renomeie numa cópia do arquivo, nunca no original.
• Quantidades com separador de milhar: deixe os números planos, sem pontos e sem vírgulas, para não serem lidos como decimais.
• Achar que PEPS e média ponderada dão o mesmo: o PEPS segue os lotes e muda o custo a cada venda; a média é recalculada a cada compra e distribui um único custo por todas as unidades. Se os dois relatórios não batem, não existe erro de digitação: são métodos diferentes.
• Guardar o ZIP numa pasta com acentos ou espaços: quase sempre funciona, mas se algo falhar, mova a pasta para um caminho curto e sem acentos.
• Esquecer a cópia de segurança: antes de trocar os dados de exemplo pelos seus, guarde uma cópia do arquivo original. É um CSV de texto e uma coluna a mais pode quebrá-lo.

Quando isso não basta

Este programa resolve bem uma parte do problema: avaliar vendas e saldos por lotes com os seus movimentos, num arquivo que você entende e pode revisar. Ele fica curto quando a empresa cresce e você não quer mais abrir um CSV para saber o que aconteceu: vários depósitos, várias pessoas mexendo no mesmo estoque, devoluções, transferências entre filiais, produtos com data de validade, relatórios que o contador pede no último dia do mês. Nessa hora o script vira um caderno de anotações, não um sistema.

Para esse momento existe o Kardex Tauro, um software de estoque feito para pequenas empresas: mantém a mesma ficha por lotes com PEPS sem que ninguém escreva uma linha de código, controla depósitos e usuários e deixa os relatórios prontos para entregar. O programa que você acabou de baixar é grátis e serve para organizar o estoque enquanto a operação ainda cabe num arquivo; quando o arquivo fica pequeno, é a vez do sistema.

Baixe o ZIP, rode o exemplo e leia o bloco de lotes consumidos com calma: quando você conseguir explicar de onde saiu cada unidade do custo das mercadorias vendidas, você entendeu o PEPS. Se ajudar, compartilhe com o seu contador e depois troque os dados de exemplo pelos seus.