👤 Para times que integram o Pipefy a outros sistemas
🔐 Disponível para todos os planos
🎯 Para saber quando e como usar operações em lote no Pipefy Piece
Quando uma integração precisa criar ou atualizar centenas ou milhares de cards de uma vez, repetir a mesma ação item a item deixa o fluxo lento e caro de manter. Cada card processado sozinho significa uma execução, e milhares de execuções para uma única carga de dados.
Ao terminar este artigo, você vai saber quando faz sentido usar uma operação em lote no Pipefy Piece, o que configurar antes de adicionar o step na sua integração e o que esperar do retorno de cada ação.
📖 O que você vai entender aqui:
Antes de configurar o step
1. Conexão do Pipefy Piece. Ações em lote funcionam apenas com uma Service Account do Pipefy (OAuth client credentials). Tokens de acesso pessoal não são suportados. Crie uma conexão do Pipefy Piece (Client ID e Client secret em Members & permissions → Service accounts no Pipefy) e selecione essa conexão em cada step de lote.
2. Acesso à organização. A Service Account precisa ser membro do pipe ou database selecionado no step, com permissão para criar e atualizar cards ou registros (export usa o mesmo modelo de permissão do upsert).
3. Disponibilidade da funcionalidade. Operações em lote são habilitadas por organização. Se sua organização ainda não está habilitada, as ações falham antes do Pipefy aceitar o job. Confirme com seu administrador Pipefy se os steps de lote não aparecem ou sempre retornam erro.
4. Assíncrono por natureza. Enviar um lote apenas aceita o job; as linhas são processadas depois. Planeje como você vai esperar a conclusão (veja Como esperar a conclusão de um lote abaixo).
Como funciona o processamento em lote
- Batch upsert faz upload do seu arquivo, mapeia colunas para campos e depois cria ou atualiza linhas.
- Batch export não tem upload; o Pipefy monta um arquivo a partir de um relatório salvo (só pipes) ou de um filtro avançado.
- Get batch operations lista os lotes recentes de um pipe/database (mais recente primeiro).
- Reprocess batch operation reenvia apenas as linhas que falharam de um lote de upsert já finalizado (não disponível para export).
Como esperar a conclusão de um lote
Todo step de upsert e export oferece a opção Wait for batch completion.
| Configuração | O que acontece | Melhor para |
| Off (padrão) | O step retorna assim que o Pipefy aceita o job (batchId, status, submittedAt). O processamento continua em segundo plano. | Lotes de longa duração, ou quando outro sistema recebe o callback do Pipefy |
| On | O Pipefy Piece pausa a execução até o Pipefy terminar e chamar de volta. O step então retorna contagens e links (relatório de erro ou arquivo exportado). | Execuções de flow que só devem continuar depois que o lote terminar |
Se Wait for batch completion estiver desligado, você pode:
- Consultar com Get batch operations em um step posterior (loop ou flow agendado), ou
- Configurar uma Callback URL para seu próprio endpoint HTTPS (o Pipefy envia o resultado por POST quando o lote atinge um status terminal).
Dados que você recebe de volta
Após o envio (wait desligado), upsert e export retornam aproximadamente:
| Campo | Significado |
| batchId | UUID do lote, use em Reprocess batch operation ou ao consultar o status |
| status | ex: queued, pending (export geralmente começa como pending) |
| submittedAt | Quando o Pipefy aceitou o job |
| callbackUrl | Só quando o wait está desligado e você configurou uma callback URL |
Após a conclusão (wait ligado, ou ao ler um lote finalizado via Get batch operations / callback), lotes de upsert finalizados podem incluir:
| Campo | Significado |
| totalCount | Linhas no lote |
| itemCounts | succeeded, failed, skipped, etc. |
| resultFile | URL temporária para o relatório de erro (upsert) ou arquivo exportado (export) |
| hasFailedItems | true quando o status é completed_with_errors |
Lotes de export terminam apenas como completed ou failed (sem completed_with_errors parcial).
Limites (compartilhados entre upsert e export)
| Limite | Valor |
| Linhas por lote (padrão, efeitos colaterais não suprimidos) | 5.000 |
| Linhas por lote (com as duas caixas de suprimir marcadas no Batch upsert) | 10.000 |
| Tamanho do arquivo de origem | Até 50 MB (o campo Source file no Batch upsert pode aplicar um limite de upload menor) |
| Chaves de match (upsert) | Até 3 |
| Chave de idempotência | Até 100 caracteres |
| Callback URL | Até 500 caracteres, http ou https |
Antes de avançar, confirme que você entende:
☐ Você sabe quando uma operação em lote resolve melhor que processar item a item
☐ Você sabe qual conexão configurar antes de adicionar o step
☐ Você sabe a diferença entre Wait for batch completion ligado e desligado
☐ Você sabe onde encontrar o resultado de um lote já enviado
