Batch upsert: guia de uso

Atualizar registros um a um leva tempo quando as informações chegam em uma planilha ou em outro sistema. Com o conector Pipefy, você pode incorporar essas alterações à sua integração como uma operação em lote.

Ao terminar este artigo, você vai saber preparar o arquivo, configurar a ação Batch upsert, definir como os registros serão correspondidos, acompanhar o processamento e tratar as linhas que falharam.

📖 O que você vai entender aqui:

O que a ação Batch upsert faz

A ação Batch upsert cria ou atualiza vários cards em um pipe ou registros em uma database a partir de um único arquivo CSV ou JSON.

Nos bastidores, o conector Pipefy:

1. Envia o arquivo para o armazenamento do Pipefy (você não precisa configurar isso manualmente).
2. Submete o lote com o mapeamento de colunas e as opções que você definiu.
3. Opcionalmente, aguarda até que o Pipefy termine de processar todas as linhas.

Antes de adicionar a etapa do Pipefy

• Conexão do conector Pipefy usando uma Service Account, com acesso ao pipe ou à database de destino
• Arquivo dentro dos limites de quantidade de linhas e tamanho (consulte a seção 12)
• Definição de quando as linhas devem sempre criar itens, atualizar por chave ou ser ignoradas quando não houver correspondência
• Definição de como a etapa Batch upsert aguardará a conclusão (visão geral)

Passo 1: conecte o Pipefy com uma Service Account

1. No Pipefy, abra Members & permissions → Service accounts e crie uma Service Account (planos Business, Enterprise ou Unlimited).
2. Copie o Client ID e o Client secret (exibido apenas uma vez, na criação).
3. Conceda à conta acesso ao pipe ou à database que você usará na etapa de processamento em lote.
4. Na integração, abra Connections para o conector Pipefy (ou conecte ao adicionar a etapa).
5. Cole o Client ID e o Client secret e salve.

Passo 2: prepare o arquivo CSV ou JSON

CSV

• UTF-8, com valores separados por vírgulas.
• O valor padrão de First data row é 2 (cabeçalho na linha 1).
• Cada cabeçalho mapeado deve aparecer exatamente uma vez.
• A correspondência dos cabeçalhos ignora maiúsculas, minúsculas e espaços no início e no fim (Email, email e EMAIL são equivalentes).

Exemplo:

JSON

• A raiz deve ser um array de objetos.
• As colunas mapeadas são chaves no nível superior de cada objeto.
• First data row não se aplica a JSON.
• Uma chave ausente é tratada como uma célula vazia, não como um erro.

Exemplo:

[
  { "Name": "Acme Corp", "Email": "ops@acme.example" },
  { "Name": "Beta Inc", "Email": "hello@beta.example" }
]

Regras de conteúdo para os dois formatos

As colunas dedicadas a etiquetas e responsáveis esperam IDs ou endereços de e-mail separados por vírgulas, e não nomes de exibição.

Passo 3: adicione a ação Batch upsert

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

Passo 4: configure destino, arquivo e mapeamento

Destino (Target)

Arquivo de origem (Source file)

Padrões comuns:

• Google Sheets / Excel: exporte para CSV em uma etapa anterior e, em seguida, passe o arquivo aqui.
• Download HTTP: use uma etapa que busque o arquivo e mapeie Source file para a saída dessa etapa.

Mapeamento de campos (Field mapping)

Em Field mapping, adicione linhas de Field to column:

Você pode deixar Field mapping vazio se usar apenas colunas de atributos (título, data de vencimento, etiquetas, responsáveis e ID do registro), mas é obrigatório ter pelo menos um mapeamento ou uma coluna de atributo.

Colunas de atributos (opcionais)

Use estas colunas quando o valor não for um campo personalizado:

Passo 5: correspondência, criação e efeitos adicionais

Correspondência de cards ou registros existentes (Match existing cards or records by)

Selecione até três chaves, combinadas com AND:

• ID do registro ou card: requer Record id column
• Título: requer Title column
• Qualquer campo personalizado da lista suspensa

Deixe vazio para sempre criar novos cards ou registros.

Campos com múltiplos valores (etiquetas, responsáveis, checklists, conexões e anexos) não podem ser chaves de correspondência.

Criação quando não houver correspondência (Create when no match is found)

Efeitos adicionais na gravação de cards

Estas caixas de seleção aparecem na etapa Batch upsert (os nomes correspondem às opções da API do Pipefy):

Com as duas opções ativadas, o limite de linhas aumenta de 5.000 para 10.000 (consulte os limites).

Chave de idempotência (Idempotency key, opcional)

Repetir a mesma chave no mesmo repositório retorna o lote existente em vez de criar um novo. Prefira uma chave exclusiva por execução (por exemplo, inclua o ID da execução do fluxo), para que novas tentativas não reutilizem um lote antigo sem aviso.

Passo 6: escolha como aguardar a conclusão

Consulte a visão geral: como aguardar um lote.

Observações específicas de Batch upsert:

Passo 7: use os resultados nas próximas etapas

Imediatamente após a submissão (espera desativada)

Use batchId nas etapas seguintes, por exemplo, em Reprocess batch operation ou Get batch operations.

Após a conclusão (espera ativada)

A etapa retorna:

Se status for failed, o lote inteiro falhou, não apenas linhas individuais. Verifique o erro no log da execução.

Formato do relatório de erros:

• Origem CSV: arquivo CSV com row, error e, em seguida, as colunas mapeadas.
• Origem JSON: array JSON de { "row", "error", "data" }.

Corrija os dados e envie um arquivo corrigido em um novo lote, ou use Reprocess após corrigir as linhas que falharam por motivos transitórios.

Get batch operations: consulte o status

Use quando Wait for batch completion estiver desativado e você precisar do status em uma etapa posterior.

1. Adicione Pipefy → Get batch operations.
2. Defina Target e Pipe ou Database (o mesmo repositório do lote).
3. Opcionalmente, filtre por Status.
4. Defina Page size (de 1 a 50; padrão 10).
5. Para a próxima página, passe pageInfo.endCursor em After cursor quando hasNextPage for true.

Cada lote na resposta inclui isFinished quando o status é terminal.

Significado dos status:

Os lotes são ordenados do mais recente para o mais antigo.

Reprocess batch operation: tente novamente as linhas com falha

A ação Reprocess batch operation submete novamente apenas as linhas que falharam em um lote de upsert concluído. Não é necessário reenviar o arquivo.

1. Adicione Pipefy → Reprocess batch operation.
2. Defina Batch id com o batchId de Batch upsert (ou de Get batch operations).
3. Execute a integração depois que o lote original atingir completed_with_errors (ou determinados casos de failed com falhas no nível das linhas).

Regras:

• Linhas bem-sucedidas e ignoradas nunca são executadas novamente.
• É seguro chamar a ação quando não houve falhas (o lote permanece inalterado).
• Não se aplica a Batch export (a exportação não tem reprocessamento).
• Erros determinísticos (por exemplo, duplicação em um campo único) falharão novamente até que você altere os dados ou o mapeamento.

Após a conclusão do reprocessamento, use Get batch operations ou aguarde um novo upsert com Wait for batch completion se tiver encadeado outra submissão.

Limites e casos não suportados

Limites

Não suportado via Batch upsert

Problemas comuns

Antes de avançar, confirme que você entende

☐ Sei preparar o arquivo e mapear apenas os campos que pretendo alterar.

☐ Sei como a correspondência e as células mapeadas vazias afetam os registros existentes.

☐ Sei acompanhar o lote e revisar as linhas que falharam.