De CSV para API: como ganhei 48 horas no fechamento da folha de pagamento

Ainda sinto o cheiro de café frio daquela madrugada de outubro de 2025. Eram 4 da manhã e eu estava, pela terceira vez naquela semana, corrigindo manualmente uma planilha de espelho de ponto. O arquivo CSV exportado pelo software antigo da "LogiTrans" — uma transportadora aqui de São Paulo com 180 colaboradores — tinha decidido, por conta própria, ignorar as vírgulas nas horas noturnas. O resultado? O Roberto, motorista há 10 anos, foi lançado com 73 horas trabalhadas num dia de 12. Isso explodiu a consistência do sistema de RH, e o fechamento da folha, que deveria ter acontecido no dia 25, foi para o dia 27.

O problema não era apenas a demora. Era a falta de confiança nos dados. Todo mês tínhamos um "posto de controle": duas pessoas da equipe de DP cruzando os dedos e olhando linha por linha do Excel antes de subir para o ERP. Eu sabia que, como engenheira de automação especialista em REP, manter aquele processo manual era um risco de passivo trabalhista absurdo, mas a diretoria só via custo na implementação de uma integração. O colapso daquela madrugada foi o argumento final que eu precisava.

A decisão foi tomada: matar o CSV de vez. O objetivo era sair de um ciclo de 5 dias para 3 dias no processamento da folha. Eu precisava que o software de ponto conversasse diretamente com o sistema de RH via API. Não havia mágica, era engenharia pura, mas o resultado de precisão foi assustador.

O caos da digitação manual e por que o CSV trai

O grande vilão da história não era a competência da equipe do DP, mas o formato de arquivo. O CSV (Comma-Separated Values) é um ecossistema frágil quando tratamos de dados estruturados de jornada. Se você configurar o Windows com separador decimal ponto e o software de RH exportar com vírgula, a quebra de linha acontece. A perda de tempo não estava em "exportar", mas em "tratar" o dado.

A cada fim de mês, a equipe gastava em média 12 horas apenas corrigindo formatação: horas extras que apareciam como minutos, datas invertidas (MM/DD vs DD/MM) e, o pior, PIS e CPF truncados. Esse processo manual abre uma porta enorme para erros de digitação que passam despercebidos até que o colaborador reclame do contracheque. Além disso, lidar com arquivos planos significa que qualquer um com acesso à pasta da rede pode abrir, alterar e salvar sem deixar rastro auditável — um risco de segurança que muitas vezes ignoramos até que aconteça um vazamento de dados salariais.

Substituir isso por uma conexão via API (Application Programming Interface) não é apenas modernizar, é blindar. Em vez de baixar um arquivo que "dorme" no desktop, a API empurra os dados estruturados em formato JSON (JavaScript Object Notation) assim que o batimento de ponto é validado. O sistema de RH recebe o pacote, lê a estrutura e, se houver qualquer erro de schema (tipo de dado incorreto), a requisição é rejeitada instantaneamente com um código de erro 400 ou 422. Você não consegue subir dados quebrados, ponto final.

A engenharia por trás da conexão direta

O primeiro passo não foi técnico, foi de mapeamento. Eu precisei sentar com o gestor de RH e alinhar exatamente o que precisávamos. A LogiTrans usava um ERP de mercado que aceitava Webhooks. O software de ponto escolhido para a substituição possuía uma documentação de API REST completa.

A lógica de automação que desenhei seguiu um fluxo simples, porém rígido:

1. Validação no REP: O colaborador bate o ponto. O software de ponto valida a regra de jornada (se está dentro da tolerância de 10 minutos, por exemplo). Se houver uma inconsistência grave, o sistema já barra no relógio ou no app.
2. Disparo do Evento: Uma vez que o período (semana ou quinzena) é fechado pelo gestor no ponto, o software dispara um POST para o endpoint do ERP.
3. Autenticação Segura: A conexão usa tokens JWT (JSON Web Token) com expiração curta. Isso garante que, mesmo que alguém intercepte o tráfego, não consiga reenviar os dados velhos (replay attack).
4. Confirmação (Ack): O ERP recebe o JSON, processa e retorna um status 200 OK ou 201 Created. Se o funcionário não existir na base de RH ou se o CPF estiver divergente, a API retorna erro, e nosso sistema de ponto loga isso para correção imediata.

Esse foi o ganho de precisão. No CSV, se o código do funcionário estivesse errado, o Excel aceitava. Na API, o sistema de RH simplesmente diz: "Não conheço essa pessoa". O erro pula na tela do operador no mesmo dia.

Lidando com as exceções: afastamentos e tolerâncias

Nenhuma automação é 100% sem intervenção humana; o segredo é focar o humano apenas onde ele é necessário. Tivemos um debate intenso sobre como tratar as justificativas de ausência e os ajustes de afastamento no ponto.

Antes, o DP recebia o atestado, arquivava uma cópia física e depois digitava a abono no sistema. Com a API, eu configurei um endpoint de Webhook Listener. Quando um colaborador anexa o atestado digitalizado no aplicativo do ponto, a integração cria uma "solicitação de abono" no ERP. O analista de RH só precisa aprovar ou rejeitar dentro do ERP dele. Uma vez aprovado, o status volta para o software de ponto via API e as horas são abonadas automaticamente.

Outro ponto crítico foi a configuração da tolerância de atraso. No método manual, o DP aplicava uma fórmula no Excel que, muitas vezes, desconsiderava a regra específica da Portaria 1.510/2009 sobre a tolerância de 10 minutos no início e fim da jornada. Com a integração, a regra está codificada no nível do banco de dados do software de ponto. A API envia apenas o resultado líquido (se houve desconto ou não). O ERP de RH não calcula mais jornada de ponto; ele recebe o cálculo pronto e auditado. Isso eliminou as divergências entre o que o ponto dizia e o que a folha pagava quando um funcionário chegava às 08:07.

Onde ficam os dados? A escolha entre Nuvem e Local

Uma preocupação válida da TI da empresa era: "Se a conexão cair, perdemos o ponto?". Foi aqui que abordamos a questão da infraestrutura. Optamos por uma arquitetura híbrida para máxima segurança. O REP (Registrador Eletrônico de Ponto) físico continua coletando as batidas localmente (ARM - Arquivo-Fonte de Dados), garantindo que uma queda da internet não pare a fábrica.

No entanto, para a integração via API funcionar, os dados precisam estar na nuem. O software de ponto faz o upload do AFD (Arquivo Fonte de Dados) e do AFDT (Arquivo de Controle de Frequência) para servidores criptografados (SSL/TLS 1.3) periodicamente. Discutimos se deveríamos manter um servidor local para "sincronizar", mas o custo de manutenção de um servidor físico para apenas 180 funcionários não compensava. Na prática, ter os dados na nuem facilitou o cumprimento da LGPD, pois o acesso aos logs de jornada agora é gerenciado por senhas biométricas no portal, algo muito mais difícil de auditar numa pasta compartilhada no servidor local da empresa.

Claro, isso exige uma avaliação de segurança. Eu recomendo fortemente ler sobre onde seus dados ficam mais seguros antes de assinar qualquer contrato, pois nem todo provedor de nuvem segue as normas brasileiras de armazenamento de dados trabalhistas com o mesmo rigor.

O resultado financeiro e operacional de 2026

Passamos de um ciclo onde o DP gastava a terça e a quarta-feira inteiras "passando ponto", para um modelo onde o software sincroniza as marcações a cada 15 minutos.

O corte de 2 dias não foi abstrato.

• Dia 25 (Antes): Início do processamento.
• Dia 27 (Antes): Final com erros.
• Dia 25 (Depois): O sistema de RH já está com 99% dos dados batidos. A equipe passa o dia apenas validando as exceções (atestados e correções de esquecimento de registro).

A precisão saltou de 92% (pós-revisão manual) para 99,8% na primeira tentativa de importação. Em números reais, evitamos 23 reclamações de funcionários sobre erro de horas extras no primeiro mês de implementação. Se cada reclamação gera em média 2 horas de análise do RH e um custo emocional que ninguém mensura, a economia de horas-homem foi superior a 46 horas apenas no mês de estreia.

Há uma ressalva honesta que preciso fazer: a implementação não foi grátis. Tivemos custo de desenvolvimento da interface e um mês de ajustes finos nos mapeamentos de campos (principalmente com escalas 12x36). O payback (retorno sobre investimento), no entanto, foi atingido no terceiro mês, considerando apenas a economia de horas extras do departamento pessoal.

O aprendizado final: não automatize o caos

Se eu pudesse passar uma lição clara para outros engenheiros ou gestores que pensam em seguir esse caminho: não conecte um sistema desorganizado a outro via API esperando milagre. Se os cadastros de funcionários no RH (PIS, CPF, data de admissão) estiverem sujos, a API vai só devolver erros mais rápido. O "tratamento de dados" que eu fazia no Excel tinha que ser feito antes, na higienização da base do RH.

A automação via API é um exponenciador. Se o processo é bom, ela o torna excelente e rápido. Se o processo é ruim, ela quebra tudo em alta velocidade. Hoje, a LogiTrans fecha a folha com tranquilidade no dia 25, e o Roberto, nosso motoriro, recebe suas horas extras corretas sem que ninguém precise ficar até madrugada somando células no Excel. A tecnologia não substitui o humano, ela libera o humano para fazer o trabalho que importa: cuidar das pessoas, e não das planilhas.