Código Python: ficha de estoque com média ponderada (download grátis)

Código Python: ficha de estoque com média ponderada (download grátis)

Saiu mercadoria da prateleira e o custo do que saiu precisa ser anotado no mesmo dia, não no fechamento do mês. Se o preço de compra mudou duas vezes na mesma semana, a conta feita de cabeça vai sair errada. Este programa em Python lê as compras e as vendas de um arquivo, recalcula o custo médio ponderado a cada movimento e deixa a tabela pronta para conferência ou para entregar à contabilidade. Ele atende o dono que quer saber de onde vem o custo que aparece na margem, quem entrega a mercadoria no balcão e o contador que precisa do detalhe sem refazer tudo à mão.

Não é um sistema de estoque e não tem telas: é um arquivo de texto com instruções que qualquer pessoa consegue ler, rodar e alterar. Junto com ele vão dados de exemplo de dois produtos de uma ferramenta, o cimento e o cabo, para que o resultado faça sentido antes de qualquer preparação.

O que vem no pacote

O ZIP pesa 5459 bytes e abre em uma única pasta. Dentro dele está tudo: o programa comentado, os dados de exemplo, a saída que você deve obter e um guia curto. Não há dependência para instalar nem cadastro para fazer em lugar nenhum.

O que o programa faz

O caminho é o da ficha de papel, na mesma ordem em que os fatos aconteceram:

1. Lê datos/movimientos.csv. Cada linha traz a data, o produto, o tipo de movimento, a quantidade, o custo unitário e o detalhe do documento.
2. Separa os movimentos por produto e percorre tudo na ordem do arquivo.
3. Em cada compra, sobe a quantidade em estoque e soma ao valor o que foi realmente pago.
4. Depois de cada movimento, refaz o custo médio: o valor do saldo dividido pelas unidades que restaram.
5. Em cada venda, valoriza a mercadoria pelo custo médio vigente antes de dar baixa no saldo.
6. Imprime a ficha em colunas, monta o resumo por produto com a conferência e grava tudo em salida/kardex.csv.

Como rodar

Você precisa do Python 3.11 ou mais novo e de mais nada: o programa usa somente a biblioteca padrão, então não existe pacote para instalar nem licença para pagar. Os passos são estes.

1. Instale o Python pelo site oficial, marcando a opção que o adiciona ao sistema.
2. Descompacte o arquivo baixado em qualquer pasta.
3. Abra o terminal e entre nessa pasta com o comando que troca de diretório.
4. Digite o comando e aperte Enter.

python kardex_promedio.py

A tabela aparece na janela e, no fim, vem o aviso do arquivo gerado. O CSV fica em salida/kardex.csv, na mesma pasta, pronto para abrir no Excel ou em qualquer planilha. Um detalhe que economiza tempo: o programa se localiza sozinho, porque usa a pasta do próprio arquivo como referência, então pode ser chamado de qualquer caminho e vai gravar o resultado ao lado de si mesmo.

O código, explicado

O programa tem menos de duzentas linhas e cada linha leva um comentário. Estas cinco partes são as que vale entender, porque são elas que decidem o custo.

Primeira: dinheiro não se calcula com decimal binário. Os centavos são tratados com Decimal, e não com float, e todo resultado é arredondado para dois decimais com arredondamento comercial. É a diferença entre uma ficha que fecha e outra que arrasta centavos perdidos.

def redondear(valor: Decimal) -> Decimal:
    """Arredonda para dois decimais (centavos) com arredondamento comercial."""
    return valor.quantize(CENTAVO, rounding=ROUND_HALF_UP)

Segunda: cada compra entra pelo que foi pago de verdade. O estado do produto guarda três coisas: as unidades, o valor e a lista de linhas que serão impressas. Numa entrada, a quantidade aumenta, o valor pago é somado e a linha recebe os dados daquela compra.

        if movimiento["tipo"] == TIPO_ENTRADA:
            # Entrada: el inventario sube por lo que realmente se pagó.
            costo = Decimal(movimiento["custo_unitario"])
            valor = redondear(cantidad * costo)
            estado["cantidad"] += cantidad
            estado["valor"] += valor
            fila.update(e_cant=cantidad, e_vu=costo, e_val=valor)

Terceira: a venda sai pelo custo médio anterior ao movimento. Aqui está o miolo da média ponderada e a ordem importa: o custo médio é calculado sobre o saldo que existia antes da baixa. Se fosse calculado depois, a mercadoria sairia valorizada por um custo que ainda não existia e a margem não bateria com a realidade.

        elif movimiento["tipo"] == TIPO_SALIDA:
            # Salida: se valora al promedio vigente ANTES de descontar el movimiento.
            promedio = redondear(estado["valor"] / estado["cantidad"]) if estado["cantidad"] else Decimal("0.00")
            valor = redondear(cantidad * promedio)
            estado["cantidad"] -= cantidad
            estado["valor"] -= valor
            fila.update(s_cant=cantidad, s_vu=promedio, s_val=valor)

Quarta: o saldo é refeito a cada movimento. Terminado o movimento, o programa deixa na linha o saldo em unidades, o custo médio do saldo e o valor do saldo. O custo médio impresso vai arredondado em centavos, mas o valor do saldo guarda a soma real: é por isso que a ficha não perde centavos quando você a confronta com a contabilidade.

        fila["saldo_cant"] = estado["cantidad"]
        # # Custo médio vigente: valor do saldo dividido pelas unidades do saldo
        fila["saldo_prom"] = redondear(estado["valor"] / estado["cantidad"]) if estado["cantidad"] else Decimal("0.00")
        fila["saldo_val"] = redondear(estado["valor"])

Quinta: a conferência avisa em voz alta quando algo não fecha. O resumo soma entradas e saídas de cada produto e compara: quando o saldo é igual às entradas menos as saídas, imprime FECHA, senão REVISAR. É o alarme mais barato que um estoque pode ter.

        cuadra = entradas_cant - salidas_cant == estado["cantidad"]
        print(f"  {producto}")
        print(f"    Entradas : {miles(entradas_cant):>9} unidades {miles(entradas_val):>16}")
        print(f"    Saídas     : {miles(salidas_cant):>9} unidades {miles(salidas_val):>16}")
        print(f"    Saldo        : {miles(estado['cantidad']):>9} unidades {miles(redondear(estado['valor'])):>16}")
        print(f"    Conferência (saldo = entradas - saídas): {'FECHA' if cuadra else 'REVISAR'}")

Com essas cinco peças já dá para ler o programa inteiro. Se depois surgir a necessidade, é possível acrescentar uma coluna ao CSV e usar o campo livre para o depósito ou o fornecedor, sem mexer no cálculo.

O que você vê na tela

A primeira tela repete o cabeçalho do programa, informa quantos movimentos foram lidos e abre a tabela do primeiro produto. É assim:

================================================================================================================================================================
  FICHA DE ESTOQUE COM MÉDIA PONDERADA
  Código Python didático · Kardex Tauro · kardex-tauro.muisca.co
================================================================================================================================================================
Movimentos lidos: 10

Produto: Cimento cinza 50 kg
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Data        Detalhe                                         Entrada  Custo un. Valor entrada    Saída   C. médio   Custo venda    Saldo   C. médio   Valor saldo

Da esquerda para a direita: a data, o detalhe do documento, a quantidade e o custo unitário da compra, o valor dessa entrada, a quantidade e o custo médio da venda, o custo da venda, o saldo em unidades e o valor do saldo com o seu custo médio. As linhas de compra e as de venda se distinguem porque as colunas que não se aplicam ficam vazias. O saldo final fecha cada produto e o resumo com a conferência vem depois. Nos dados de exemplo o cimento começa com uma compra de 100 unidades a 18 000 cada, depois uma venda de 90 unidades e uma segunda compra a 20 000: nesse ponto dá para ver o custo médio subir e a venda seguinte sair valorizada pelo custo novo, e não pelo preço da primeira compra.

Erros comuns e dicas

• O tipo do movimento precisa trazer exatamente a palavra aceita para compra ou para venda. O programa não adivinha: ao encontrar outra coisa ele para com uma mensagem, em vez de continuar com um número errado.
• Se você editar o CSV no Excel, salve como CSV separado por vírgulas e mantenha os nomes das colunas, porque é por eles que o programa lê cada dado.
• As datas são escritas na ordem ano, mês e dia, por exemplo 2026-03-02. O programa não reordena o arquivo: um movimento com data trocada permanece nessa posição na ficha.
• Quando uma venda zera o saldo, o custo médio só é calculado enquanto existem unidades; a condição que evita dividir por zero já está escrita dentro do programa.
• Quando o resumo imprime REVISAR, quase sempre há um custo unitário digitado errado ou um movimento com o tipo trocado. Vale conferir essas duas colunas antes de qualquer outra coisa.
• O CSV de saída pode ser copiado e ampliado com mais produtos: o programa monta um bloco por produto sem nenhuma alteração no código.

Quando isso não basta

Vale dizer com clareza o que este programa resolve e o que ele não resolve. Ele dá conta do cálculo da média ponderada sobre um arquivo bem preenchido e mostra por que a ordem dos movimentos muda o custo da venda, mas não controla quem digita, não cruza a nota fiscal com o romaneio, não trabalha com vários depósitos e não avisa quando um custo ficou alto demais. Também não guarda histórico de alterações.

Quando a empresa já não quer depender de um arquivo mantido por uma única pessoa, o passo seguinte é o Kardex Tauro, um programa de estoque para o dia a dia em que o mesmo cálculo acontece sem ninguém precisar rodar nada. Enquanto o volume for pequeno e uma pessoa cuidar dos movimentos, este código basta: ele é gratuito e pode ser lido do começo ao fim.

Baixe o pacote, rode com os dados de exemplo e depois troque o arquivo de movimentos pelo seu. Ver o próprio estoque numa tabela que fecha é a melhor maneira de entender o custo médio ponderado. E se o resultado ajudar, guarde: o Kardex Tauro publica outros programas didáticos como este.