🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para quem integra sistemas que exportam ou consomem dados tabulares
🎯 Nível: básico
Grande parte dos sistemas corporativos ainda vive em CSV. Relatórios exportados de ERPs, arquivos de conciliação financeira, bases de fornecedores, listas de produtos: o formato tabular é onipresente porque é simples, portátil e compreendido por praticamente qualquer ferramenta. O problema é que APIs e flows de integração falam JSON. Quando os dois precisam se encontrar dentro de um flow, há uma etapa de conversão no meio.
A opção CSV no Integrações Pipefy resolve exatamente esse ponto de fricção. Ela converte CSV em JSON para que o flow consiga processar dados tabulares como qualquer outra resposta de API. Converte JSON em CSV quando o destino final é uma planilha, um sistema legado ou qualquer ferramenta que espera dados no formato tabular. E também converte Excel para CSV.
📖 O que você vai entender aqui:
Processamento de Planilhas e Relatórios (Excel e CSV para JSON)
Este é o caminho mais frequente quando o fluxo precisa interpretar dados vindos de relatórios estruturados ou planilhas extraídas de sistemas parceiros (como dados do SAP). Na aba Utilidade, ao selecionar a opção CSV, a plataforma disponibiliza duas ações sequenciais para resolver esse cenário:
- Convert Excel to CSV: se a origem dos dados for uma planilha nativa do Excel nos formatos .xlsx ou .xls, esta ação processa o arquivo e o transforma em texto plano (string de CSV).
- Convert CSV to JSON: na sequência (ou caso o sistema de origem já envie um relatório diretamente em CSV), esta ação lê a string de texto delimitado e a converte em um formato de array JSON.
A partir desse ponto, os dados ficam 100% disponíveis no Data Selector de forma estruturada, permitindo que as próximas ações realizem filtros, loops de leitura (For Each) ou insiram os registros linha por linha dentro de um Pipe.
Geração e exportação de tabela (JSON para CSV)
Este cenário segue a lógica inversa. O fluxo coletou informações de múltiplos cards, consolidou dados de APIs ou realizou checagens internas, e o resultado final precisa ser devolvido para um sistema externo que só aceita tabelas (como um portal de fornecedores ou uma rotina de importação legada).
- Convert JSON to CSV: também localizada no menu Utilidade > CSV, esta ação lê o array JSON gerado dinamicamente ao longo do fluxo e o converte diretamente para o formato de texto CSV.
Com essa estrutura de texto delimitado pronta, o fluxo ganha a liberdade de encaminhar o conteúdo formatado por e-mail, usar outras ferramentas de arquivo da plataforma para anexá-lo de volta a um card como um documento ou despachá-lo via requisição HTTP para o servidor de destino.
A opção CSV não lê nem escreve arquivos por conta própria. Ela converte texto. O CSV de entrada chega como string, normalmente vindo de outro passo do flow. O CSV de saída também é uma string, que você entrega para um sistema ou ação que vai fazer algo com ela. Entender isso evita confusão na hora de montar o flow.
Caso de uso enterprise: conciliação em massa de Notas Fiscais e deltas do SAP ERP
Em grandes operações de Procurement, os dados de conformidade raramente chegam fracionados. Diariamente, o sistema de planejamento global (como o SAP) gera um relatório massivo de auditoria contendo milhares de linhas de lançamentos, faturamentos e deltas de fornecedores. Por limitações de exportação do ERP legado, esse arquivo é extraído em formato nativo do Excel (.xlsx) — uma estrutura binária pesada que exige processamento inteligente para não sobrecarregar a nuvem.
Como o fluxo é desenhado:
- Captura do Arquivo: o fluxo coleta automaticamente o relatório .xlsx gerado pelo SAP assim que ele é depositado em um servidor seguro (SFTP) ou diretório em nuvem.
- Tratamento do Binário: utilizando a ação Convert Excel to CSV, a plataforma quebra a estrutura rígida do Excel e converte o arquivo em texto plano (string delimitada) em segundos.
- Estruturação Analítica: o resultado alimenta imediatamente a ação Convert CSV to JSON, que transforma as linhas da tabela em um array de objetos JSON perfeitamente maleável para a automação.
- Triagem e Orquestração: o fluxo entra em um nó de Loop (For Each) para processar a volumetria. Um Router interno faz a triagem das colunas: se uma linha indicar uma divergência fiscal, o Pipefy isola o registro e abre um card de auditoria urgente no Pipe de Contas a Pagar.
Boas práticas aplicadas para fluxos de alta performance
Para garantir que esse processamento em massa rode com segurança e eficiência, o fluxo deve ser blindado seguindo os guias de boas práticas de produto do Pipefy para evitar estouros de infraestrutura:
- Gerenciamento de memória (Proteção contra Over of Memory): converter planilhas massivas em objetos JSON consome muita memória volátil. Como o ambiente possui um limite rígido de 512MB por execução, a boa prática exige filtrar colunas desnecessárias na origem ou limpar o payload antes de transformá-lo em JSON, garantindo que apenas os dados essenciais trafeguem na memória do fluxo.
- Estratégia de fracionamento (Sub-flows / Callables): processar um loop linear com milhares de registros em um único fluxo principal vai fatalmente estourar o tempo máximo de execução de processamento. A arquitetura de alta performance recomenda utilizar o fluxo principal apenas para quebrar o arquivo (Orquestrador) e, de dentro do loop, disparar fluxos filhos assíncronos (Callables) fracionados para processar blocos de linhas em paralelo.
- Evitar Nós Desnecessários dentro do Loop: cada ação executada consome tempo de CPU e chamadas de API. Colocar buscas repetitivas (como Get Card ou requisições HTTP redundantes) dentro de um loop de mil linhas degrada a performance do fluxo. O correto é extrair essas consultas para fora do loop (fazer um fetch único de dados de apoio no início) e usar a memória local para cruzamento.
- Idempotência no registro de cards: se uma flutuação de rede interromper o processamento na linha 800 de um relatório de 1000 itens, o fluxo será reexecutado. Para evitar a criação de cartões duplicados no Pipefy no reprocessamento, inclua uma chave única do ERP (como o número da Nota Fiscal) em um campo de controle e use uma busca rápida antes de decidir pela criação.
Dois pontos de atenção antes de usar em produção
Objetos aninhados não sobrevivem à conversão para CSV de forma limpa. Quando o JSON de entrada tem objetos dentro de objetos, a peça achata a estrutura usando a chave do objeto pai como prefixo do cabeçalho. O resultado pode ser funcional, mas a estrutura da tabela fica diferente do que a maioria das ferramentas espera. Se o JSON de origem tem hierarquia, vale normalizar os dados antes de passar pela conversão na opção CSV, usando a opção de Code ou um Files Helper de transformação.
Caracteres especiais em dados de texto podem quebrar a interpretação do CSV. Vírgulas dentro de um campo de endereço, aspas em nomes comerciais, quebras de linha em campos de descrição: todos esses casos podem desalinhar as colunas se o delimitador não estiver configurado corretamente ou se os valores não estiverem entre aspas no CSV de origem. Teste o flow com dados reais antes de ir para produção, especialmente quando a origem é um sistema que você não controla.
CSVs muito grandes processados inteiramente pela opção CSV podem impactar a performance do flow e o consumo de tarefas. Se o arquivo tem milhares de linhas, considere dividir o processamento em lotes, ou avaliar se o sistema de origem consegue pré-filtrar os dados antes de enviar.
Checklist de conclusão
☐ A diferença entre CSV para JSON e JSON e Excel para CSV, e quando cada direção se aplica
☐ Por que a peça CSV trabalha com strings, não com arquivos
☐ O que acontece com objetos JSON aninhados na conversão para CSV
☐ Por que testar com dados reais é obrigatório quando a origem tem texto livre
