Como versionar a integração quando muda o leiaute do extrato

Um provedor renomeia a coluna de tarifa, muda a ordem dos campos e acrescenta um tipo de evento. O importador antigo continua lendo a posição e atribui o campo seguinte como se fosse o custo. A conciliação ainda gera um total, mas os valores estão em categorias erradas. Versionar o mapeamento permite detectar mudança de origem, testar a adaptação com os dois formatos e explicar quando cada versão entrou.

Defina o contrato de leitura de cada arquivo

Documente provedor, relatório, conta, cabeçalho, delimitador, codificação, tipos, moeda, sinal e campos obrigatórios. Indique quais colunas são lidas pelo nome e como são tratadas colunas extras. Um novo campo opcional pode ser armazenado sem afetar a carga. A ausência de ID, moeda ou valor precisa aparecer como erro. Uma mudança de nome pode ter significado idêntico ou acompanhar uma mudança semântica. Confirme na documentação e em amostra do relatório.

O RFC 4180 descreve uma convenção comum de CSV. O conector Texto/CSV do Power Query permite escolher delimitador e comportamento de detecção de tipos. Configure o que a integração precisa, sem depender da inferência em todo arquivo. A Wise e a Stripe documentam formatos e relatórios de saldo, mas o formato efetivamente exportado depende do relatório e da configuração usada. Guarde a referência do documento e uma amostra autorizada do leiaute original.

Detecte a mudança antes de lançar valores

Compare cabeçalhos, quantidade de campos e tipos essenciais no início de cada carga. Se o arquivo tem cabeçalho conhecido e muda a ordem, leia por nome. Se o formato traz registros com cabeçalhos diferentes por tipo, defina regras separadas. Faça a integração rejeitar versões desconhecidas ou guardar em uma fila de validação. Inclua verificação de código de moeda, unidades, sinal e categorias. Uma coluna pode manter o nome e trocar o significado, então os testes de valor continuam necessários.

Confirme se a mudança afeta relatórios antigos e se arquivos reexportados com nova versão trazem os mesmos identificadores. Rode a rotina nova e a antiga em um intervalo comum, sem duplicar entradas no ERP. Compare contagem, somas, taxa por tipo, saldo, estornos e itens sem correspondência. Se o provedor publica novo tipo de evento, descubra se representa lançamento novo ou apenas detalhamento. Registre a decisão e prepare um exemplo para evitar que uma categoria desconhecida passe como receita.

Exemplo de transição com dois leiautes

Uma exportadora recebe um relatório de maio com coluna de tarifa em português. Em junho, a origem oferece cabeçalho em inglês e muda os campos para incluir moeda da taxa. A versão 1 do mapeamento funciona para maio. A versão 2 lê o novo nome e valida moeda. Uma carga de teste compara 40 movimentos que o provedor disponibilizou nos dois formatos. O bruto e o líquido coincidem, enquanto duas tarifas são cobradas em outra moeda e precisam de linha separada.

Na primeira importação nova, a equipe registra arquivo, data, versão e resultado do teste. Os documentos de maio permanecem reprocessáveis pelo mapeamento antigo. Um arquivo de abril reexportado com o formato novo é identificado pelo cabeçalho e processado pela versão 2. A proteção por chave da transação evita criar duplicidade no ERP. A contabilidade recebe a indicação da data de corte e a lista de taxas com tratamento diferente.

Deixe uma forma de repetir ou voltar

Guarde o arquivo original, versão do mapeamento, data da importação e vínculo entre evento e lançamento. Defina quem aprova a troca e qual condição suspende a carga. Se houver erro de produção, identifique os lotes afetados antes de reprocessar. Uma reimportação precisa preservar o que já foi lançado, sinalizar o que mudou e deixar trilha para eventual correção contábil. A rotina deve manter acesso restrito às amostras que tragam dados de clientes ou contas.

Use casos com aspas, acentos, campos vazios, mudança de ordem e tipos novos em seus testes. Compare totais por moeda e certifique-se de que dados de origem, como zeros em identificadores, continuam preservados. Se a plataforma permite escolher idioma no download, registre a configuração usada para reduzir variações desnecessárias.

Quando o provedor anuncia a mudança antes da vigência, reserve um período de validação com uma conta de teste ou cópia dos dados. Registre as diferenças que a equipe prevê e as que encontrou. Se surgir um campo de status novo, confirme se ele muda a seleção de eventos disponíveis. A nova rotina deve indicar o motivo de cada linha descartada e permitir comparar o lote com o arquivo original.

Perguntas frequentes

Toda coluna nova deve bloquear a importação?

Defina quais campos são obrigatórios e quais são opcionais. Uma coluna extra pode ser aceita se os campos usados mantiverem significado e os totais passarem.

Posso adaptar o arquivo antigo manualmente para o leiaute novo?

Preserve o original e use um mapeamento documentado. Uma cópia transformada deve indicar origem e regra para permitir repetição da conferência.

Como comparar versões se o relatório mudou a referência?

Busque identificadores complementares e faça uma amostra com valores, moedas e datas. Mantenha pendentes as linhas cuja relação não puder ser sustentada.

Fontes oficiais

• RFC Editor — formato CSV
• Microsoft — conector de Texto/CSV no Power Query
• Wise — como baixar extratos de saldo
• Stripe — relatório de saldo

Leituras relacionadas

• Como usar os IDs da Stripe para conciliar transações e repasses
• Guias para exportadores de serviços

Como a Zen pode ajudar

A contabilidade para exportação de serviços da Zen ajuda a organizar documentos, conciliar recebimentos e analisar as regras da sua operação. Peça uma proposta personalizada para conversar sobre o seu caso.