Código Python: contagem física vs sistema, diferenças e ajustes

Código Python: contagem física vs sistema, diferenças e ajustes

Cedo ou tarde todo negócio pequeno faz uma contagem física, e a cena se repete: o estoquista percorre as prateleiras com a prancheta na mão, os números vão para o computador e não batem com o que o sistema mostra. A parte difícil não é contar, é decidir o que fazer com a diferença. Ajustar tudo de uma vez, sem deixar registro, transforma qualquer conferência posterior em discussão sem prova. Não ajustar nada faz o estoque do sistema se afastar da realidade e a compra do mês seguinte vira chute. Este programa cobre exatamente esse meio do caminho: pega a contagem e o estoque do sistema, mede a diferença em unidades e em dinheiro, separa o que pode ser ajustado do que precisa de recontagem, deixa os itens ainda não contados em uma lista à parte e salva o comprovante que o contador vai pedir depois. Foi escrito para o dono de uma pequena empresa, para o estoquista que conta com prancheta e caneta e para o contador que precisa explicar o ajuste no fechamento do mês.

O ZIP traz tudo o que é preciso para rodar hoje mesmo, sem conexão com a internet e sem instalar bibliotecas:

O que o programa faz

O programa trabalha em quatro etapas: ler, comparar, resumir e arquivar. Produto por produto ele faz o seguinte:

1. Lê o arquivo datos/conteo.csv, em que cada linha traz o nome do produto, o estoque informado pelo sistema, o custo unitário e até duas contagens feitas no depósito.
2. Usa a última contagem disponível: havendo uma segunda contagem, é ela que vale; não havendo, vale a primeira. Assim a recontagem substitui a primeira tentativa sem apagar o número anterior.
3. Calcula a diferença em unidades subtraindo o estoque do sistema daquilo que foi contado. Resultado positivo é sobra; negativo é falta.
4. Converte essa diferença em dinheiro multiplicando pelo custo unitário, com aritmética decimal exata, em centavos e com arredondamento comercial.
5. Compara o tamanho da diferença com a tolerância. O que passa da tolerância não é ajustado: fica marcado para recontagem, porque diferença grande quase sempre é erro de contagem e não movimento real do depósito.
6. Deixa pendente o produto que ainda não tem nenhuma contagem, para que ele não desapareça no meio do caminho nem suje os totais do relatório.
7. Soma as sobras e as faltas separadamente, calcula o ajuste líquido e confere por um segundo caminho se a soma de todas as diferenças bate com esse líquido.
8. Salva dois arquivos: a contagem completa com todas as linhas e uma folha só com as diferenças, que é a que vai para a contabilidade junto com a folha de contagem assinada.

Como rodar

A única coisa que precisa estar instalada é o Python 3.11 ou superior. O programa usa somente a biblioteca padrão da linguagem: não há pandas para instalar, nem pacote extra, nem conexão com a internet. Depois de descompactar o ZIP, abra o terminal na pasta que ficou e digite um comando só.

No Windows: python conteo_fisico.py. No Linux ou no Mac o comando pode ser python3 conteo_fisico.py. Se a máquina responder que não encontra o comando python, tente python3. Se responder que não encontra o arquivo, quase sempre é o terminal aberto na pasta errada: o programa monta os caminhos a partir da própria localização, então basta entrar na pasta descompactada e repetir o comando. A pasta de saída o programa cria sozinho; não há nada para preparar à mão nem banco de dados para configurar.

O código, explicado

Não é preciso entender o arquivo inteiro para aproveitar o programa, mas vale a pena olhar cinco partes, que são as que carregam a lógica do negócio. O resto é apresentação da tabela e formatação de números.

A primeira parte são os caminhos de entrada e de saída. O programa pergunta a si mesmo onde mora e, a partir daí, monta três caminhos, sem escrever nenhum caminho absoluto no código. Esse detalhe é o que permite mover a pasta para a área de trabalho, para um pendrive ou para uma pasta compartilhada na rede sem mexer em uma linha:

BASE = Path(__file__).resolve().parent
ENTRADA = BASE / "datos" / "conteo.csv"            # contagem de exemplo que viaja dentro do ZIP
SALIDA = BASE / "salida" / "conteo.csv"            # resultado da contagem, pronto para abrir no Excel
AJUSTES = BASE / "salida" / "ajustes.csv"          # somente as diferenças: é a folha que vai para a contabilidade

ENTRADA aponta para a contagem de exemplo que viaja dentro do ZIP, SALIDA guarda a contagem completa e AJUSTES guarda somente as linhas com diferença, que são as que vão para a contabilidade. Os três caminhos se apoiam no pathlib, que monta os caminhos com o separador do sistema operacional. No bloco de importação aparece ainda a decisão mais importante do programa: os números são tratados com Decimal e não com o float de sempre, porque dinheiro não se calcula com decimais binários. Um centavo perdido no arredondamento é uma diferença que ninguém quer explicar depois, e aqui isso não acontece porque todo valor é quantizado em dois decimais com arredondamento comercial.

A segunda parte define a tolerância e as constantes de trabalho. A tolerância é a linha de corte do relatório: diferença grande não se ajusta, conta-se de novo. Cada negócio define a sua, e no exemplo ela está em cinco unidades, o que para um depósito de ferragens é uma margem razoável:

TOLERANCIA = Decimal("5")

# Constantes de trabalho: zero e um centavo (nunca mudam)
CERO = Decimal("0")
CENTAVO = Decimal("0.01")

A terceira parte é a função que compara. Ela recebe uma linha da contagem, lê o estoque do sistema, o custo unitário e a última contagem disponível, e devolve um registro com tudo o que o relatório precisa mostrar:

def evaluar(fila: dict) -> dict:
    """Compara a contagem final com o sistema e classifica a linha: diferença, valor, resultado e ação."""
    producto = fila["produto"]
    sistema = Decimal(fila["sistema"])
    costo = Decimal(fila["custo_unitario"])
    final = ultimo_conteo(fila)

A quarta parte é a decisão. Com a diferença já calculada, o programa classifica a linha em um de três resultados e escolhe a ação. Repare nas duas últimas linhas: a ação não depende de faltar ou sobrar, depende do tamanho da diferença. Passar da tolerância não se ajusta, conta-se outra vez, e é esse critério que separa um ajuste confiável de um ajuste feito no escuro:

    # Diferença = o contado menos o que o sistema diz (positiva: sobra)
    diferencia = final - sistema
    valor = redondear(diferencia * costo)

    if diferencia == CERO:
        resultado, accion = SIN_NOVEDAD, SIN_AJUSTE
    else:
        resultado = SOBRANTE if diferencia > CERO else FALTANTE
        # Passar da tolerância não se ajusta: conta-se outra vez
        accion = RECONTAR if abs(diferencia) > TOLERANCIA else AJUSTAR

A quinta parte monta o ajuste líquido. Aqui o programa soma as sobras e as faltas separadamente e depois recalcula o total por outro caminho, linha por linha, para comparar os dois. Quando não batem, a linha de conferência avisa e o relatório não deve ser usado para ajustar o sistema:

    sobrantes_u, faltantes_u = suma_unidades(sobrantes), suma_unidades(faltantes)
    sobrantes_v, faltantes_v = suma_valor(sobrantes), suma_valor(faltantes)
    neto_u, neto_v = sobrantes_u + faltantes_u, sobrantes_v + faltantes_v
    suma_dif = sum((r["diferencia"] for r in con_conteo), CERO)
    cuadra = suma_dif == neto_u and suma_valor(con_conteo) == neto_v

O que você vai ver na tela

Ao rodar o programa aparece primeiro o cabeçalho com o nome do relatório e a linha da tolerância. Depois vem a tabela da contagem, com uma linha por produto e sete colunas: o nome do produto, o estoque do sistema, a contagem final, a diferença em unidades, o valor dessa diferença, o resultado e a ação recomendada. A coluna da diferença mostra o sinal, para que se veja de imediato o que sobra e o que falta, e a coluna da ação é a que volta para o depósito: Ajustar quer dizer que a diferença é pequena e pode ser corrigida de uma vez, Recontar quer dizer que a diferença passou da tolerância e o item precisa ser contado de novo antes de mexer no sistema, e Contar é para o produto que ficou sem nenhuma contagem. Embaixo aparece o resumo com os totais por grupo, o ajuste líquido, a linha de conferência e a lista de produtos para recontar. Um trecho da saída real é este:

============================================================================================================
  CONTAGEM FÍSICA VS SISTEMA
  Código Python didático · Kardex Tauro · kardex-tauro.muisca.co
============================================================================================================
Produtos lidos: 10
Tolerância: 5,00 unidades

Produto                          Sistema Contagem final  Diferença           Valor Resultado    Ação        
------------------------------------------------------------------------------------------------------------
Cimento cinza 50 kg               120,00         120,00       0,00            0,00 SEM NOVIDADE Sem ajuste  
Cabo THHN 12 AWG                   45,00          48,00      +3,00      456.000,00 SOBRA        Ajustar     
Tubo PVC 1/2 pol x 6 m            200,00         206,00      +6,00       58.800,00 SOBRA        Recontar    
Arame de amarrar 1/8               34,00          33,00      -1,00       -7.200,00 FALTA        Ajustar     
Disco de corte 7 pol               60,00          54,00      -6,00      -25.800,00 FALTA        Recontar    
Fita métrica 5 m                   25,00          25,00       0,00            0,00 SEM NOVIDADE Sem ajuste  
Luvas de vaqueta                   18,00                                           PENDENTE     Contar      
Tinta anticorrosiva                40,00          38,00      -2,00      -64.000,00 FALTA        Ajustar     
Registro de gaveta 1/2 pol         90,00          95,00      +5,00       43.000,00 SOBRA        Ajustar     
Martelo de unha 16 oz              12,00           9,00      -3,00     -126.000,00 FALTA        Ajustar     
------------------------------------------------------------------------------------------------------------

============================================================================================================
RESUMO DA CONTAGEM
============================================================================================================
  SEM NOVIDADE  2 produtos         0,00 unidades               0,00
  SOBRA         3 produtos       +14,00 unidades        +557.800,00
  FALTA         4 produtos       -12,00 unidades        -223.000,00

  Total de sobras:     +14,00 unidades       +557.800,00
  Total de faltas :     -12,00 unidades       -223.000,00
  Ajuste líquido :      +2,00 unidades       +334.800,00
  Produtos sem contagem: 1 (não entram no ajuste)
  Conferência (soma das diferenças = ajuste líquido): FECHA
  Produtos para recontar (2): Tubo PVC 1/2 pol x 6 m, Disco de corte 7 pol

Arquivo gerado: salida/conteo.csv
Arquivo gerado: salida/ajustes.csv

Repare na linha de conferência: quando diz FECHA, a soma de todas as diferenças bate com o ajuste líquido calculado em separado, e o relatório pode seguir para a contabilidade com tranquilidade. Se dissesse REVISAR, há algo digitado errado na contagem e é melhor corrigir antes de ajustar qualquer coisa, porque ajuste sobre dado ruim só muda o erro de lugar. Olhe também a coluna do valor, e não apenas a das unidades: uma falta de três unidades em um martelo pesa bem mais em dinheiro do que uma sobra de cinco unidades em um registro de gaveta barato, e o ajuste contábil é feito pelo valor, não pelo número de unidades. É por isso que o programa trabalha com o custo unitário de cada produto e não com uma média geral.

Os dois arquivos que ficam na pasta de saída abrem direto no Excel ou em qualquer planilha. A contagem completa serve para conferir e assinar; o arquivo de ajustes é curto de propósito, porque leva só as linhas com diferença e é ele que se arquiva junto com a folha de contagem.

Erros comuns e dicas

• Rodar o programa de outra pasta: como ele resolve os caminhos a partir do próprio arquivo, o mais simples é abrir o terminal dentro da pasta descompactada e digitar o comando ali.
• Deixar o Excel salvar o CSV com ponto e vírgula como separador, o que é comum em português: o arquivo passa a ser lido como uma coluna só. Exporte com vírgula.
• Confira as colunas de contagem: com as duas preenchidas, o programa usa a segunda. Para comparar a primeira contagem, deixe a segunda vazia.
• Não zere a tolerância. Sem tolerância, qualquer unidade de diferença manda a linha para recontagem e o relatório perde utilidade justo quando o depósito está mais bagunçado.
• Confira o custo unitário antes de ajustar. Um custo antigo gera ajuste errado mesmo com as unidades perfeitas.
• Guarde o arquivo de ajustes junto com a folha de contagem e com a data à vista. Quando alguém perguntar por que o estoque mudou, a prova já está na mesa.
• Se a linha de conferência disser REVISAR, não ajuste nada ainda: primeiro corrija a contagem e rode o programa de novo.

Quando isso não é suficiente

Este programa é um bom ponto de partida, mas não é um sistema de estoque. Ele trabalha sobre um arquivo CSV, salva um resultado e para por aí: não tem usuários, não registra quem mudou o quê, não guarda o histórico das contagens anteriores e não conversa com o faturamento. Quando o negócio conta todo mês em vários depósitos, quando entram e saem itens todos os dias e quando o contador pede o rastro de cada ajuste, o arquivo e o script ficam curtos. É aí que entra o Kardex Tauro, que é gratuito e organiza o estoque com a ficha de estoque, as entradas, as saídas e os ajustes em um lugar só, de modo que a contagem física é comparada com algo que se mantém em dia. Se o estoque cabe em uma planilha e a contagem é de vez em quando, este programa resolve e sobra.

Baixe o ZIP, rode o exemplo do jeito que vem e depois troque datos/conteo.csv pela sua própria contagem: o programa não precisa de mais nada. Se o negócio continuar crescendo e o controle virar tarefa diária, vale a pena olhar o Kardex Tauro com calma; enquanto isso, este programa deixa o trabalho da contagem organizado, medido em unidades e em dinheiro e com a prova pronta para o contador.