Leonardo Peron5 min de leitura
Integração por arquivo — CSV, posicional, SFTP, EDI — tem cara de coisa antiga e continua movendo folha de pagamento, retorno bancário, nota de fornecedor e catálogo de distribuidor. Ela sobrevive por motivos que não envelheceram: qualquer sistema sabe gravar um arquivo, ele atravessa fronteira de empresa sem liberar acesso a nada, e o arquivo é prova — dá para reabrir em dezembro o lote de março e ver o que chegou. O que envelheceu foi a disciplina em volta dela: quase todo defeito aqui é de convenção, não de tecnologia.
O nome do arquivo é metade do protocolo
Um arquivo chamado clientes.csv é a decisão de não decidir nada. O nome
carrega, no mínimo, origem, tipo de conteúdo, data de referência e um número
sequencial que nunca se repete.
O sequencial é o que quase sempre falta e o que mais serve depois: ele mostra que o lote 418 nunca chegou. Sem ele, arquivo que não veio é indistinguível de dia sem nada — a cegueira do webhook que não chega, e a razão de o alarme de ausência valer aqui.
E arquivo não se sobrescreve: correção entra com nome e sequencial novos, apontando para o anterior. Gravar por cima apaga a evidência de que o primeiro existiu.
Versionar o layout é outra coisa, e também precisa existir: quando o fornecedor acrescenta uma coluna no meio, quem lê por posição quebra de uma vez. Versão declarada no cabeçalho ou no nome transforma isso em erro claro em vez de dado deslocado.
O arquivo que ainda está sendo escrito
O defeito mais comum e o mais difícil de reproduzir: a leitura pega o arquivo enquanto o outro lado ainda grava. Metade das linhas entra, ninguém dá erro, e o resto some porque na rodada seguinte o arquivo já consta como lido.
A defesa que resolve a maioria dos casos é gravar com nome temporário e renomear ao terminar, porque quem lê só enxerga o nome final. A segunda é o arquivo-sinal, um arquivo vazio que só aparece depois de o principal estar completo. A terceira, mais fraca, é ignorar o que foi modificado há poucos minutos: depende de relógio e de rede, então é reforço, não regra.
O lote que chega meio errado
Cinco mil linhas, três inválidas. A decisão precisa estar no acordo antes de acontecer, porque na hora vira improviso.
Tudo ou nada. O lote inteiro é recusado. É o certo quando as linhas se relacionam — o lote contábil em que a soma tem de fechar, pelo motivo de integrar ERP com contabilidade.
Aceita o que vale, recusa o resto. Melhor para cadastro e catálogo, e só é honesto com a peça que todo mundo esquece: o arquivo de retorno. Sem ele, quem mandou acha que mandou cinco mil, o outro lado ficou com 4.997, e a diferença aparece meses depois.
Quarentena. O lote fica parado até alguém decidir. Serve para o caso raro e vira desastre como padrão: quarentena sem dono é fila que ninguém olha com outro nome.
O retorno merece o cuidado do arquivo de ida: nome, sequencial e uma linha por registro recusado, com o motivo em texto que quem opera entende — não o código interno da validação.
Reprocessar sem duplicar
A tentação é controlar por arquivo: guardar o nome ou o resumo dos já processados e recusar repetido. Funciona até o primeiro reenvio legítimo, em que o remetente corrigiu três linhas e mandou o lote inteiro de novo. O arquivo é outro, passa pela conferência, e as 4.997 linhas boas entram duas vezes.
A identidade é do registro, não do arquivo: uma chave estável por linha, com restrição de unicidade no destino, como em o mesmo evento duas vezes. O controle por arquivo continua útil para outra pergunta — qual sequencial faltou.
O que quebra em silêncio, em português
Nenhum dos problemas abaixo dá erro: todos entregam dado errado com sucesso declarado.
Codificação. Arquivo gravado em Latin-1 e lido como UTF-8 transforma "Conceição" em algo ilegível, e o registro entra assim. O acordo declara a codificação, e a entrada valida procurando caractere de substituição.
Separador decimal. 1.234,56 e 1,234.56 são o mesmo valor em duas
convenções, e um lido pela outra vira número mil vezes maior ou truncado. Num
CSV separado por vírgula, um valor com vírgula decimal ainda desloca a linha
inteira — por isso ponto e vírgula sobrevive melhor em português. O acordo tem
de dizer as duas coisas: separador de campo e separador decimal.
Data ambígua. 03/04/2026 é válido em dois formatos e significa meses
diferentes. Ano na frente elimina a dúvida; qualquer outro formato exige que o
acordo diga qual é.
Zero à esquerda. CEP, CNPJ, código de produto e conta bancária perdem o zero quando alguém abre o arquivo numa planilha e salva de novo. O sintoma aparece longe: um CNPJ de treze dígitos que ninguém acha no cadastro.
O teste que confirma
Monte um arquivo de sete linhas e mande pelo caminho de verdade: um nome com cedilha e til, um valor com centavos, uma data no dia 3 do mês 4, um CNPJ que começa com zero, um campo com o separador dentro do texto, uma linha inválida de propósito e uma linha idêntica a outra já processada ontem.
Depois leia o resultado no destino, não o log da rotina. As sete respostas: o acento chegou íntegro, o valor tem os centavos certos, a data caiu em abril, o CNPJ manteve quatorze dígitos, a linha com separador não deslocou nada, a inválida gerou retorno legível e a repetida não criou um segundo registro.
Se ainda não há caminho para mandar esse arquivo, o problema é anterior: é o levantamento de integrar um sistema sem API, por onde o projeto começa.