👤 Para usuários técnicos e desenvolvedores que integram sistemas externos ao Pipefy
🔐 Disponível para planos com acesso à API
🎯 Para quem precisa decidir se uma operação de escrita mora dentro do pipe, dentro do flow ou fora, na API
A conta já saiu do começo. Os pipes estão rodando, as automações estão no ar e o time confia no processo para tocar o dia a dia. Então aparece a operação que as automações nativas não resolvem sozinhas: atualizar centenas de cards de uma vez depois de uma mudança de política, limpar um campo em lote antes de um novo ciclo, sincronizar um dado que nasce em outro sistema. A pergunta que trava não é qual comando digitar. É onde essa operação deveria viver.
Ao terminar este artigo, você vai saber decidir entre três caminhos de escrita no Pipefy, automação nativa, HTTP action dentro do flow e API GraphQL de fora, com critérios claros de volume, origem do dado e manutenção, para não sair para a API quando o problema se resolvia mais perto de casa.
📖 O que você vai entender aqui:
As três camadas de escrita
Toda operação que altera dados no Pipefy pode acontecer em uma de três camadas, e cada uma resolve bem um tipo de caso.
A primeira é a automação nativa, dentro do próprio pipe. Ela cobre o que acontece em resposta a um evento do processo: um card muda de fase, um campo é preenchido, um prazo vence. É a camada mais fácil de manter porque quem cuida do processo enxerga a regra na interface, sem precisar ler código.
A segunda é a HTTP action dentro do flow. Ela entra quando a lógica ainda pertence ao processo, mas precisa de algo que a automação nativa não faz: uma chamada com regra própria, uma limpeza consistente de campos, uma atualização que depende de um passo anterior do flow. Continua dentro do Pipefy, continua rastreável, e é o tema do artigo *A peça HTTP*.
A terceira é a API GraphQL, de fora. Ela é a camada certa quando a operação não nasce de um evento do processo, mas de um sistema externo ou de uma necessidade pontual de manutenção em massa. É o caso de sincronizar dados que vivem em outro software ou de aplicar uma correção em lote que ninguém vai repetir toda semana.
A pergunta que separa as três não é técnica, é de origem. Se a operação responde a um evento do processo, ela pertence ao processo (nativa ou HTTP action). Se ela nasce fora ou é uma intervenção pontual, a API é o lugar.
A matriz de decisão
Antes de abrir a IDE do GraphQL, três perguntas resolvem a maior parte dos casos.
De onde nasce a operação? Se o gatilho é um evento do processo, comece pela automação nativa e só suba para HTTP action se a nativa não alcançar. Se o gatilho é externo (um sistema que empurra dados) ou é uma manutenção pontual, a API faz sentido.
Qual o volume e com que frequência? Uma correção única em lote é candidata natural à API. Uma operação que se repete a cada card, todo dia, quase sempre pertence ao flow, porque é lá que ela fica visível e mantida por quem cuida do processo.
Quem vai manter isso daqui a seis meses? Uma automação nativa é lida por qualquer admin na interface. Uma HTTP action ainda vive dentro do Pipefy. Uma integração externa vive fora, depende de uma conexão que precisa de dono e some do radar de quem só olha o pipe. Quanto mais longe do processo a operação mora, mais cuidado de governança ela exige.
Antes de escolher a API para uma operação em massa, olhe o teto do seu plano. A API do Pipefy limita a 500 solicitações a cada 30 segundos, e passar desse número bloqueia novas chamadas por 5 minutos. Para atualizações em lote, a recomendação é trabalhar em levas de até 30 cards por vez. Volume alto não é impedimento, mas é uma variável de decisão: uma operação que estoura o teto precisa ser fatiada, e isso muda o esforço de manutenção da conta.
- Saiba mais: Como usar a API do Pipefy
Atualizar, limpar e remover são decisões diferentes
Depois que você decidiu que a operação é de API, o tipo de escrita muda o critério. Atualizar um valor, limpar um campo e remover um card não são a mesma coisa com risco crescente. São decisões de natureza diferente.
Atualizar é a operação de menor consequência. Você troca o valor de um campo por outro. Em lote, cada card é uma chamada própria empilhada na mesma requisição, o que casa bem com a leva de até 30 cards que o teto do plano recomenda. O risco aqui é de escala, não de perda: se errar o valor, você corrige com outra atualização.
Limpar parece igual a atualizar, mas esvaziar um campo tem um detalhe que separa os tipos. Para campos de texto, limpar é atribuir um valor vazio. Já campos de anexo pedem tratamento à parte, porque anexo não é um texto que se apaga escrevendo por cima. Antes de limpar anexos em massa, confirme o comportamento específico desse tipo de campo no Help Center, porque tratar anexo como texto é a forma mais comum de uma limpeza em lote falhar sem avisar.
- Saiba mais: Como limpar campos em massa via API
Remover é a única operação de escrita que não tem volta. Deletar um card apaga o histórico dele, e em processos auditáveis isso raramente é o que você quer. Antes de deletar em lote, pergunte se o que você precisa é remover de vez ou apenas tirar o card do fluxo ativo. Se for o segundo caso, arquivar preserva o registro e costuma ser a decisão de arquitetura correta. Deletar deveria ser a exceção reservada a dados que realmente não podem existir, não o atalho para "sair da minha frente".
A pergunta que protege o processo: essa operação precisa ser irreversível? Se a resposta não é um sim convicto, provavelmente existe um caminho que preserva o histórico.
- Saiba mais: Como excluir cards em massa via API
A regra que não muda: Service Account, nunca token pessoal
Independente da camada e do tipo de operação, uma coisa não é negociável em ambiente de produção: a autenticação usa uma conta de serviço, não o token pessoal de quem construiu a integração.
O motivo é de continuidade. Uma chamada autenticada com token pessoal para de funcionar no dia em que aquela pessoa sai da empresa ou tem o acesso alterado. A operação em massa que limpava campos, a sincronização que rodava toda noite, tudo para de uma vez e sem aviso. A conta de serviço desacopla a integração de qualquer pessoa física, e é o que mantém a operação viva quando o time muda.
Se você encontrar conexões pessoais em automações ou receitas antigas, a boa prática é já trocar, não esperar o processo parar para descobrir.
- Saiba mais: Fundamentos técnicos e Service Account
Antes de avançar, confirme que você entende:
☐ Por que a origem da operação (evento do processo vs. sistema externo) decide a camada antes do volume
☐ Que atualizar, limpar e remover são decisões de natureza diferente, não a mesma operação com risco maior
☐ Que o teto de chamadas do seu plano é variável de decisão, não detalhe de implementação
☐ Que arquivar preserva o histórico e deletar não tem volta, e qual dos dois o seu processo realmente precisa
