O PipeRun é o CRM brasileiro mais popular entre empresas B2B de médio porte, e provedores de internet com uma operação comercial estruturada estão entre os usuários. O problema é que, mesmo com um CRM bom, o programa de indicações continua rodando em planilha do lado de fora. Lead chega no PipeRun como "lead orgânico", vendedor não diferencia, comissão fica perdida.

A solução é simples no conceito e direta na execução: conectar o sistema de indicações ao PipeRun via API pra que cada indicação caia no funil com tag clara, dados completos e responsável certo. Esse tutorial mostra como fazer isso, do token até o teste final.

Quem é esse tutorial pra: gestor comercial, marketing ou TI em provedor de internet (ou empresa B2B/B2C com base recorrente) que já usa PipeRun. Você precisa ter acesso de admin no PipeRun pra gerar token de API e criar campos personalizados.

Por que integrar (e o que dá errado sem integração)

O cenário típico em provedor sem integração: o cliente ativo recebe um link de indicação do programa, manda pra um amigo via WhatsApp. O amigo preenche um formulário no site. Lead aparece num e-mail ou planilha. Alguém do comercial copia os dados pra o PipeRun, marca origem como "WhatsApp" no campo padrão e atribui pro próximo vendedor da fila.

Os problemas que isso gera:

A integração resolve os 4 com webhook em tempo real e campos personalizados padronizados. Vamos configurar.

Pré-requisitos

Passo 1: Gerar token API no PipeRun

O PipeRun usa autenticação Bearer Token na API REST. Pra criar um:

  1. Logue no PipeRun como administrador
  2. Vá em Configurações → API → Tokens
  3. Clique em Novo Token
  4. Dê um nome identificável (ex: fazup-indicacao)
  5. Marque os escopos necessários:
    • opportunities:read e opportunities:write
    • persons:read e persons:write
    • custom-fields:read
    • pipelines:read
    • users:read (pra atribuir responsável)
  6. Salve. O PipeRun mostra o token uma única vez. Copie e guarde em local seguro.

O token tem o formato:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.xxx.yyy
⚠️ Cuidado com o token: ele dá acesso de leitura/escrita ao seu CRM. Trate como senha. Não cole em GitHub público, prints ou chats não criptografados. Se vazar, revogue imediatamente em Configurações → API → Tokens.

Passo 2: Criar campos personalizados

Os campos padrão do PipeRun (nome, telefone, e-mail, valor) cobrem 60% do que precisamos. Pra ter contexto completo da indicação, vamos criar campos personalizados em oportunidade:

  1. No PipeRun, vá em Configurações → Campos Personalizados → Oportunidade
  2. Crie os 3 campos abaixo:
    • Indicador (Nome): tipo Texto, símbolo indicador_nome
    • Indicador (Código): tipo Texto, símbolo indicador_codigo
    • Comissão PIX: tipo Decimal, símbolo comissao_pix

Pra distinguir lead de indicação dos demais no funil, configure também uma Origem personalizada:

  1. Vá em Configurações → Origens
  2. Crie a origem "Indicação" com cor laranja (sugestão pra ficar visível no card)

Anote o ID da origem criada. Você vai precisar no payload da API.

Passo 3: Mapear funil e responsável

O PipeRun pode ter vários funis (pipelines). Decida qual vai receber as indicações:

Pra provedor com 50+ indicações por mês, recomenda-se funil dedicado. Pra menos que isso, funil principal funciona.

Anote o pipeline_id e stage_id do estágio inicial.

Sobre responsável, defina a regra de atribuição:

O PipeRun aceita atribuição via user_id no payload da oportunidade. A FazUp implementa a lógica de roteamento e envia o user_id correto em cada chamada.

Passo 4: Conectar o sistema de indicações

Agora a parte da conexão: configurar o sistema de indicações pra disparar uma chamada à API do PipeRun toda vez que uma indicação for criada.

O endpoint que o FazUp consome:

POST https://app.crmpiperun.com/api/v1/opportunities

Headers:
  Authorization: Bearer eyJ0eXAi...
  Content-Type: application/json

Body:
{
  "title": "Maria Clara S. (indicação)",
  "pipeline_id": 7,
  "stage_id": 22,
  "user_id": 14,
  "source_id": 9,
  "value": 99.90,
  "person": {
    "name": "Maria Clara S.",
    "phone": "+5547999887766",
    "email": "maria@email.com"
  },
  "custom_fields": {
    "indicador_nome": "João Silva",
    "indicador_codigo": "U-1042",
    "comissao_pix": 35.00
  }
}

No FazUp, esse payload é montado e enviado automaticamente. Você só configura no painel admin: token, pipeline_id, stage_id padrão e regra de atribuição.

Quer pular essa parte?

A equipe FazUp configura tudo (token, campos, funil, responsável) em 24h. Sem custo adicional.

Falar com a equipe

Passo 5: Testar end-to-end

Antes de ativar pros indicadores reais, faça um teste completo:

  1. Crie um indicador fake no FazUp (ex: João Teste, código U-TESTE-01)
  2. Acesse o link de indicação dele
  3. Preencha o formulário com dados de teste (use o telefone do gestor pra ver as notificações)
  4. Vá no PipeRun e abra o funil configurado
  5. Em até 5 segundos, valide:

Se algum item falhar, vai pro próximo (troubleshooting).

Troubleshooting comum

"API retorna 401 (Unauthorized)"

Token errado, expirado ou sem permissão. Confira no PipeRun em Configurações → API → Tokens que o token está ativo e com os escopos certos. Verifique se o header Authorization: Bearer ... está formatado corretamente (com a palavra Bearer e espaço antes do token).

"Oportunidade criada mas custom_fields ficam vazios"

O símbolo do campo personalizado está incorreto no payload. Vai em Configurações → Campos Personalizados e copia o "Símbolo" exato. Diferencia maiúsculas de minúsculas.

"Origem aparece como 'Outros' em vez de 'Indicação'"

O source_id está incorreto ou ausente. Liste as origens via GET /api/v1/sources e copie o ID da origem "Indicação" que você criou no passo 2.

"Lead duplicado quando o cliente indicado já era contato"

Por padrão, o PipeRun cria contato novo se você passar dados de pessoa no payload. Pra evitar duplicidade, use GET /api/v1/persons?phone=... antes pra checar se já existe e, se sim, passe person_id em vez de person no payload da oportunidade.

FAQ

Preciso de qual plano do PipeRun pra integrar?

Plano Pro em diante. A integração depende do acesso à API e a campos personalizados, que ficam disponíveis a partir do Pro.

Como o token de API é protegido?

O token tem escopo restrito ao que a integração precisa e pode ser revogado a qualquer momento no painel do PipeRun. Recomendamos nomear como fazup-indicacao pra identificar e rotacionar quando necessário.

É possível enviar lead pra um funil específico (não o padrão)?

Sim. Durante o setup você informa qual pipeline_id deve receber os leads de indicação. Pode ser o funil principal ou um funil dedicado.

O que acontece se o token expirar?

O FazUp detecta o erro 401, pausa novos disparos automaticamente e notifica o admin do FazUp por e-mail. Você gera um novo token, atualiza no painel e o sistema volta a operar. Nenhuma indicação é perdida durante a pausa.

Dá pra integrar mais de uma conta PipeRun?

Sim. É comum em provedores com filiais ou marcas separadas. Cada conta usa um token próprio. A FazUp roteia o lead pra conta correta com base na marca/região do indicador.

Pronto. Com esses 5 passos seu PipeRun passa a receber indicações como leads de primeira classe: rastreados, atribuídos, com comissão pré-calculada e prontos pra fechar.

Se quiser ver como o produto que automatiza isso funciona na prática, dá uma olhada na página de integração PipeRun do FazUp ou na visão geral do produto.