Integração Pipefy + Leavo

Integração via Webhook – Pipefy + Leavo

1. Visão Geral

O Pipefy é uma plataforma de gestão de processos (BPM) e workflows que permite criar pipes (fluxos) e cards (tarefas). A integração com o Leavo permite automatizar processos entre qualificação de leads e gestão de tarefas/projetos.

Casos de uso principais:

• Criar card no Pipefy quando lead é qualificado no Leavo
• Notificar Leavo quando card muda de fase no Pipefy
• Sincronizar status de leads com fases de processos
• Automatizar follow-up baseado em SLA de cards

Fluxos disponíveis:

• ✅ Leavo → Pipefy: Via API GraphQL (criar cards, mover fases)
• ✅ Pipefy → Leavo: Webhooks notificam mudanças

Diferencial: API GraphQL completa, webhooks configurados via API, suporte a SLA de cards.

2. Documentação Oficial

Pipefy:

• Pipe & Table Webhooks
• GraphQL Endpoint
• Organization Webhooks

Leavo:

• Painel de Webhooks

3. Recursos disponíveis via Webhook

3.1 Eventos do Pipefy

O Pipefy suporta 10 eventos de cards:

Eventos mais relevantes: card.move, card.done, card.late

4. Como configurar webhooks

4.1 FLUXO 1: Leavo → Pipefy (Criar Cards)

Permite que leads qualificados no Leavo virem cards automaticamente no Pipefy.

Passo 1: Obter Access Token do Pipefy

1.1 No Pipefy:

1. Vá em Configurações (⚙️)
2. Clique em Pessoal
3. Selecione Tokens de acesso
4. Clique em "Gerar novo token"
5. Copie o token

⚠️ IMPORTANTE: Guarde este token com segurança.

Passo 2: Identificar IDs Necessários

2.1 Pipe ID:

Via GraphQL:

query {
  me {
    pipes {
      id
      name
    }
  }
}

2.2 Phase ID (Fase inicial):

query {
  pipe(id: 123456) {
    phases {
      id
      name
    }
  }
}

Passo 3: Configurar Middleware (n8n ou Make)

⚠️ IMPORTANTE: O Pipefy usa API GraphQL. Use middleware para transformar webhook do Leavo em mutation GraphQL.

Opção A: Usando n8n

3.1 Criar Workflow:

3.2 Nó Function (Transform):

// Transformar payload do Leavo para GraphQL Mutation
const leavo = $json.body.data;

// Construir mutation GraphQL
const mutation = `
  mutation {
    createCard(input: {
      pipe_id: 123456
      fields_attributes: [
        { field_id: "title", value: "${leavo.nome} - ${leavo.empresa}" }
        { field_id: "email", value: "${leavo.email}" }
        { field_id: "phone", value: "${leavo.telefone}" }
      ]
    }) {
      card {
        id
        title
      }
    }
  }
`;

return {
  json: {
    query: mutation
  }
};

3.3 Nó HTTP Request:

Passo 4: Configurar Webhook de Saída no Leavo

1. No Leavo, vá em Webhooks → Saída
2. Clique em "+ Criar Webhook"

Configurar:

4.2 FLUXO 2: Pipefy → Leavo (Notificar Mudanças)

Permite que mudanças no Pipefy (ex: card concluído) atualizem o Leavo.

Passo 1: Criar Webhook de Entrada no Leavo

1. No Leavo, vá em Webhooks → Entrada
2. Clique em "+ Criar Webhook"

Configurar:

• Nome: Receber de Pipefy - Cards
• Descrição: Atualiza leads quando card muda
• Webhook ativo: LIGADO

Passo 2: Criar Webhook no Pipefy (via API)

Mutation GraphQL:

mutation {
  createWebhook(input: {
    actions: ["card.move", "card.done"]
    name: "Leavo Integration"
    pipe_id: 123456
    url: "https://api.leavo.ai/api/webhooks/p1q2r3s4..."
  }) {
    webhook {
      id
      actions
      url
    }
  }
}

Passo 3: Estrutura do Payload do Pipefy

Exemplo de card.move:

{
  "data": {
    "action": "card.move",
    "on_phase": {
      "id": 789,
      "name": "Concluído"
    },
    "from_phase": {
      "id": 456,
      "name": "Em andamento"
    },
    "created_by": {
      "id": 12345,
      "name": "João Vendedor",
      "email": "joao@empresa.com"
    },
    "card": {
      "id": 98765,
      "pipe_id": 123456,
      "title": "Maria Santos - Empresa ABC"
    }
  }
}

5. Testando a integração

✅ Checklist - Leavo → Pipefy

Pipefy:

• Access Token obtido
• Pipe ID identificado
• Phase ID identificado
• Field IDs identificados

Middleware (n8n):

• Workflow criado
• Webhook configurado
• Function GraphQL implementada
• HTTP Request configurado

Teste:

• Lead qualificado
• Webhook disparou
• Card criado no Pipefy
• Campos corretos

✅ Checklist - Pipefy → Leavo

Leavo:

• Webhook de entrada criado
• URL copiada

Pipefy:

• Webhook criado via API
• URL do Leavo configurada
• Ações configuradas

6. Estrutura de Payloads

6.1 Leavo → Pipefy (GraphQL Mutation)

mutation {
  createCard(input: {
    pipe_id: 123456
    fields_attributes: [
      { field_id: "title", value: "João Silva - Tech Corp" }
      { field_id: "email", value: "joao@techcorp.com" }
      { field_id: "phone", value: "5511999999999" }
      { field_id: "empresa", value: "Tech Corp" }
    ]
  }) {
    card {
      id
      title
      url
    }
  }
}

7. Observações e Limitações

7.1 Limitações do Pipefy

8. Boas Práticas

8.1 Use Field IDs Corretos

✅ Obtenha IDs dos campos via GraphQL:

query {
  pipe(id: 123456) {
    start_form_fields {
      id
      label
    }
  }
}

8.2 Monitore SLAs

✅ Use eventos de SLA:

• card.late - Card atrasado
• card.overdue - Card vencido

9. Troubleshooting

9.1 Card não cria

9.2 Webhook não dispara

10. Casos de Uso

10.1 Gestão de Leads em Pipe

Objetivo: Leads qualificados viram cards

Fluxo:

10.2 Sincronização de Status

Objetivo: Status do card reflete no lead

Fluxo:

Referências

• Pipefy Webhooks Documentation
• Pipefy GraphQL API
• Painel de Webhooks Leavo