Batch export: guia de uso

Quando outro sistema precisa dos dados dos seus processos, selecionar os registros e as colunas certos é tão importante quanto gerar o arquivo. Com o conector Pipefy, você pode incluir essa exportação na sua integração.

Ao terminar este artigo, você vai saber configurar Batch export, selecionar um relatório salvo ou um filtro avançado, escolher as colunas de saída e obter o arquivo após a conclusão do processamento.

📖 O que você vai entender aqui:

O que a ação Batch export faz

A ação Batch export exporta cards de um pipe ou registros de uma database para um arquivo CSV ou JSON armazenado pelo Pipefy. Você recebe uma URL temporária de download (resultFile) quando o processamento termina.

Não há arquivo de entrada. Diferentemente de Batch upsert, você define apenas o que exportar (relatório ou filtro), as colunas e o formato.

Comportamentos importantes:

• A submissão da etapa aceita a solicitação; o arquivo é gerado de forma assíncrona.
• A exportação termina apenas como completed ou failed; não existe completed_with_errors.
• Reprocess batch operation não se aplica a exportações.
• Exportações com falha não retornam um motivo detalhado no callback (planeje cuidadosamente a validação e a conferência das colunas).

Antes de adicionar a etapa do Pipefy

• Conexão do conector Pipefy (Service Account) com acesso ao pipe ou à database de origem
• Para exportações de relatórios salvos: um pipe com um relatório que já mostre as linhas esperadas na interface do Pipefy
• Para exportações com filtro avançado: JSON do filtro preparado
• Estratégia para aguardar a conclusão

Passo 1: adicione a ação Batch export

1. Na integração, adicione uma etapa → conector Pipefy → Batch export.
2. Selecione a conexão do conector Pipefy e a organização.

Passo 2: escolha o pipe ou a database e o formato

A etapa Batch export envia automaticamente ao Pipefy o tipo de entidade CARDS ou TABLE_RECORDS a partir de Target.

Passo 3: escolha a origem da exportação (relatório ou filtro)

Pipes: duas opções

Quando Target é Pipe (cards), o campo Export source é exibido:

Databases: somente filtro

Databases não têm relatórios salvos. A interface mostra apenas Advanced filter em Selection. Se você tiver escolhido uma configuração baseada em relatório, altere para Advanced filter.

Passo 4: JSON do filtro avançado para pipes e databases

Quando Export source for Advanced filter, configure Selection → Advanced filter.

O valor é um único objeto JSON, com a mesma estrutura que o Pipefy usa nos filtros de relatórios salvos. A etapa Batch export inclui um exemplo padrão que você pode editar:

{
  "operator": "and",
  "queries": [
    {
      "field": "title",
      "operator": "contains",
      "value": "text to match"
    }
  ]
}

Objeto do grupo

Cada condição em queries

Exemplo com data:

{
  "operator": "and",
  "queries": [
    { "field": "title", "operator": "eq", "value": "Match me", "type": "string" },
    { "field": "created_at", "operator": "gte", "value": "2026-01-01", "type": "date" }
  ]
}

Filtro vazio: um grupo sem queries (mas com um operator válido) exporta todas as linhas do repositório, conforme as permissões

Filtros dinâmicos: mapeie o filtro de uma etapa anterior passando JSON para Advanced filter (objeto ou string). Um JSON inválido faz a etapa falhar antes da submissão, com uma mensagem clara de erro de interpretação.

• O link na interface leva à documentação para desenvolvedores do Pipefy, com uma referência mais detalhada sobre filtros.

Passo 5: campos retornados (Returning fields)

Ao usar Advanced filter

Abra Returning fields e selecione várias colunas, ou deixe vazio para exportar todas as colunas padrão do repositório (atributos nativos, campos personalizados e colunas de fases nos pipes).

As colunas nativas disponíveis na lista suspensa incluem:

Campos personalizados aparecem como field_<internal_id> (ID interno numérico), e não como o slug do campo exibido no mapeamento de Batch upsert.

Colunas de fases (somente para pipes) seguem padrões como start_at_phase_<seq>, end_at_phase_<seq> e duration_in_phase_<seq>. Elas não estão disponíveis para exportações de databases.

Cabeçalhos do arquivo: o Pipefy grava os nomes de exibição dos campos personalizados no arquivo (field_105 → Comment). IDs nativos, como card_id, permanecem como estão. Nomes duplicados são diferenciados com (field_xxx) no cabeçalho.

Ao usar Saved report

1. Defina Export source como Saved report.
2. Escolha Saved report em Selection.
3. Não configure Returning fields: o relatório define as colunas. A etapa Batch export bloqueia a execução se você selecionar colunas enquanto um relatório estiver selecionado (o Pipefy ignoraria as colunas extras sem aviso).

Para controlar as colunas explicitamente, altere Export source para Advanced filter.

Passo 6: aguarde a conclusão e baixe o arquivo

Wait for batch completion

Saídas após a conclusão

Etapas seguintes comuns:

• Requisição HTTP: execute GET em resultFile para obter o arquivo em uma etapa posterior da integração.
• Armazene a URL ou o arquivo no seu sistema antes que a URL assinada expire.

Callback URL (espera desativada)

O campo opcional Callback URL recebe um POST quando a exportação atinge um estado terminal. O limite é de 500 caracteres, o mesmo de upsert. Não pode ser definido junto com Wait for batch completion ativado.

Idempotency key

Opcional. Atenção às exportações agendadas: reutilizar a mesma chave retorna o lote original e o arquivo com os dados daquele momento; não executa uma nova exportação. Para exportações diárias, use uma nova chave a cada execução (por exemplo, inclua a data) ou deixe o campo vazio.

Get batch operations: consulte o status da exportação

A mesma ação do guia de upsert:

1. Pipefy → Get batch operations
2. Os mesmos valores de Target e Pipe / Database
3. Filtro opcional por Status: os status terminais da exportação são completed e failed
4. Leia resultFile do lote correspondente mais recente quando operationType for export

Use batchId de Batch export para identificar seu processamento entre os lotes recentes.

Limites e regras específicas da exportação

Compare a quantidade de linhas com o mesmo relatório salvo na interface do Pipefy ao testar exportações baseadas em relatórios.

Problemas comuns

Referência rápida: campos do conector e API do Pipefy

Você não precisa chamar o GraphQL manualmente ao usar estas ações do conector Pipefy. A tabela ajuda na leitura da documentação da API do Pipefy ou na investigação de erros com seu administrador.

Antes de avançar, confirme que você entende

☐ Sei quando usar um relatório salvo ou um filtro avançado.

☐ Sei como a origem da exportação determina as colunas do arquivo.

☐ Sei aguardar a conclusão e obter resultFile.