Integração - PipeRun

1 - Acessar a documentação de API do PipeRun;

2 - Gerar API TOKEN dentro do PipeRun;

3 - Criar um Campo personalizado de pessoa no Octadesk para salvar o ID do contato, gerado pelo PipeRun; 

4 - Construir um Bot que capture o e-mail que pode ser usado para consulta na API do PipeRun;

5 - Verificar se já existe um Contato no PipeRun com a informação coletada pelo Bot;

6 - Usar regra de validação para direcionamento quando contato não existir na PipeRun;

7 - Cadastrar o Contato gerado pelo Bot no PipeRun;

8 - Verificar ID do funil dentro do PipeRun;

9 - Verificar ID da etapa do funil dentro do PipeRun;

10 - Criar uma oportunidade, a partir dos dados coletados pela criação do bot na Octadesk, escolhendo o funil e etapa do funil que deseja utilizar.

Acesse o link da documentação de API da PipeRun clicando aqui. 

A documentação de API é um tutorial detalhado sobre como fazer integrações, a usaremos para encontrar as informações necessárias para realizar a integração.

A criação do API Token serve como a chave de acesso que vamos utilizar quando iniciarmos a integração. Basta clicar no lado superior direito, onde está  o nome de sua empresa >> Integrações.

Nessa página já constará a chave API e como mostra o GIF abaixo:

O campo personalizado é onde iremos salvar o ID do PipeRun, e  utilizá-lo na integração. Por isso precisamos criá-lo antecipadamente, como no exemplo abaixo.

Lembrando que é necessário ativá-lo e ativar também a opção de pesquisa.

Para que a integração com a PipeRun funcione corretamente, temos que ter ciência que ela precisa de informação do cliente, e essa informação precisa ser perguntada em determinada fase do bot e a resposta ser salva.

Conseguimos capturar as informações do cliente nas fases de pergunta, podendo ser usadas perguntas prontas que o sistema da Octadesk oferece, ou criar as suas próprias, usando o “Pergunte qualquer coisa”.

Nesse exemplo, usaremos e-mail como dado para consultar se o contato já existe na base da PipeRun.

Para fazer essa verificação iremos usar a etapa do Bot chamada “Conecte a outro sistema”, essa etapa nos permite realizar requisições na API da PipeRun para efetuar uma consulta, vamos realizar uma requisição do tipo GET (Nos permite buscar ou consultar uma informação).

A URL da PipeRun deve ser inserida no campo “Com quem você quer integrar?” e em seguida Enter.

A URL é esta: https://api.pipe.run/v1/persons

Ao inserir a URL, outros campos e abas irão aparecer para preenchimento.

Iremos preenchê-las da seguinte forma:

Na opção PARAMS:

Chave: email

Valor: Clique na # ao lado do campo e selecione o e-mail

Na opção HEADER:

Chave: token

Valor: Seu API Token gerado no PipeRun

Cadastre mais um parâmetro e preencha:

Chave: accept

Valor: application/json

Após realizar a configuração acima, um campo de valide sua integração será apresentado, você deve preencher com um e-mail para verificar se ele existe na PipeRun, vinculado a um contato.

Importante ressaltar que a integração retornará os dados do contato caso ele exista, e retornará em branco caso ele não exista. Portanto, neste primeiro momento o ideal é utilizar um e-mail que exista na base, para que possamos testar se a integração está funcionando.

É possível ver uma configuração no Bot chamada “Salve as informações encontradas”, esse é um recurso que permite salvar as informações que a API da PiperRun retornou em campos do Octadesk. Agora será o momento de utilizarmos o campo personalizado de pessoas que criamos na etapa 3 deste artigo, para salvarmos o ID do Contato.

Iremos selecionar o item “data.0.id”.

Ele representa o ID do Contato cadastrado lá no PipeRun e, fazer com que essa informação seja salva vai nos permitir diferenciar contatos que existem no PipeRun, dos contatos que não existem, afinal, se ele não existir a integração não retornará dado algum e o campo ID PipeRun criado no Octadesk não será preenchido.

O Bot possui uma etapa chamada “Valide uma informação”, ela serve para validar se um campo em específico foi preenchido ou não, de acordo com o resultado da validação podemos configurar caminhos diferentes para o Bot. 

Iremos validar através desse campo, o ID PipeRun, se ele foi preenchido, usando a regra “Estiver Vazio”.

Ao configurar o Bot para validar se o campo ID PipeRun, está vazio ou não, será possível configurar um caminho diferente.

- Se a regra for válida: Significa que não existe um contato cadastrado na PipeRun com o e-mail que usamos para validar a integração, portanto será necessário cadastrar esse cliente na PipeRun.

- Se a regra não for válida: Significa que um existe um contato cadastrado na PipeRun com o e-mail que usamos para validar a integração, portanto, não precisamos cadastrá-lo novamente.

Pensando naquele cliente que passou pelo fluxo do Bot e ainda não tem cadastro na PipeRun, iremos criá-lo para que possamos ter seus dados na base.

Nesta etapa, iremos usar novamente a etapa do Bot chamada “Conecte a outro sistema”. Ao invés de utilizarmos o método GET, agora iremos cadastrar uma informação na PipeRun via API, portanto, vamos utilizar o método POST (Enviar uma nova informação).

A URL da PipeRun deve ser inserida no campo “Com quem você quer integrar?” e em seguida Enter.

A URL para a criação do contato é a seguinte: https://api.pipe.run/v1/persons

Essa parte da integração você pode necessitar da ajuda de um desenvolvedor caso exista a necessidade de acrescentar mais informações que serão enviadas.

Na opção HEADER:

Chave: content-type

Valor: application/json

Cadastre mais um parâmetro e preencha:

Chave: accept

Valor: application/json

Cadastre mais um parâmetro e preencha:

Chave: token

Valor: Seu API Token gerado no PipeRun

Na opção BODY, iremos preencher quais informações serão enviadas ao PipeRun, este é um exemplo que pode ser utilizado:

{

  "contactEmails": [

    "#email-contato"

  ],

  "contactPhones": [

    "#tel-celular-contato"

  ],

  "name": "#nome-contato"

}

Caso os campos das variáveis para teste não apareçam, apague as variáveis no body e insira novamente.

Se tiver sucesso na integração o contato será registrado dentro do PipeRun.

Agora será o momento de utilizarmos o campo personalizado de pessoas que criamos na etapa 3 deste artigo, para salvarmos o ID do Contato.

Iremos selecionar o item “data.id” e salvar com a variável criada para o PipeRun.

Para localizar o ID do Funil de vendas da PipeRun, será necessário fazer um GET, visto que o mesmo não está localizado dentro da plataforma.

Nesta etapa, iremos usar novamente a etapa do Bot chamada “Conecte a outro sistema”.

A URL da PipeRun deve ser inserida no campo “Com quem você quer integrar?” e em seguida Enter.

A URL para a criação do contato é a seguinte: https://api.pipe.run/v1/stages

Na opção HEADER:

Chave: token

Valor: Seu API Token gerado no PipeRun

Cadastre mais um parâmetro e preencha:

Chave: accept

Valor: application/json

Você irá precisar do ID do Funil para configurar o Body da criação da Oportunidade/Deal.

Para localizar o ID da etapa Funil de vendas da PipeRun, será necessário fazer um GET, visto que o mesmo não está localizado dentro da plataforma.

Nesta etapa, iremos usar novamente a etapa do Bot chamada “Conecte a outro sistema”.

A URL da PipeRun deve ser inserida no campo “Com quem você quer integrar?” e em seguida Enter.

A URL para a criação do contato é a seguinte: https://api.pipe.run/v1/pipelines

Na opção HEADER:

Chave: token

Valor: Seu API Token gerado no PipeRun

Cadastre mais um parâmetro e preencha:

Chave: accept

Valor: application/json

Você irá precisar do ID da Etapa do Funil para configurar o Body da criação da Oportunidade/Deal.

O PipeRun obrigatoriamente solicita o ID de um Contato para realizar a criação de uma nova deal/oportunidade, por isso, as etapas anteriores foram necessárias.

Nesta etapa, iremos usar novamente a etapa do Bot chamada “Conecte a outro sistema”, no método POST (Enviar uma nova informação).

A URL para a criação da oportunidade é a seguinte: https://api.pipe.run/v1/deals

Ao inserir a URL, outros campos e abas irão aparecer para preenchimento.

Iremos preenchê-las da seguinte forma:

Na opção HEADER:

Chave: content-type

Valor: application/json

Cadastre mais um parâmetro e preencha:

Chave: accept

Valor: application/json

Cadastre mais um parâmetro e preencha:

Chave: token

Valor: Seu API Token gerado no PipeRun

Na opção BODY, iremos preencher quais informações serão enviadas ao PipeRun, este é um exemplo que pode ser utilizado:

{

  "title": "Oportunidade - #nome-contato",

  "person_id": "#id-piperun-contato",

  "pipeline_id": ID DO FUNIL DE VENDAS,

  "stage_id": ID DA ETAPA DO FUNIL DE VENDAS

}

ATENÇÃO: Como o PipeRun não aceita o mesmo nome em sua oportunidade, caso contrário ele substitui uma existente, uma forma de não gerar conflito é no título "Oportunidade", incluir a variável do nome do contato. Nessa variável você também poderá usar o ID do Contato, e-mail, telefone, ficará a seu critério.

A estrutura acima é conhecida como BODY de uma requisição, ela segue alguns padrões conforme orientados na API do PipeRun e é uma das partes da integração que pode necessitar da ajuda de um desenvolvedor caso exista a necessidade de acrescentar mais informações que serão enviadas.

Caso precise saber o número de cadastro do seu contato, basta abrir o contato e o número dele estará no campo ”ID da pessoa”. Nesse exemplo, ele é o número 22852469.

Se tiver sucesso na integração, a deal/oportunidade será registrada dentro do PipeRun.