O CRM de Vendas PipeRun possui uma API aberta, ou seja, é possível adicionar, alterar, consultar e remover informações do CRM utilizando o token de um usuário gestor.

A documentação completa da API do CRM de Vendas PipeRun está disponível clicando aqui.

Confira neste artigo as principais informações sobre as requisições que podem ser feitas à API do PipeRun e em quais situações é recomendado o seu uso.

TÓPICOS DO ARTIGO

  1. O que é uma API
  2. Como consumir uma API
  3. Estrutura de uma requisição
  4. Por que usar uma API?

O QUE É UMA API?

API é um acrônimo para Application Programming Interface , ou, em português, Interface de Programação de Aplicativos.

O intuito de uma API é trocar dados entre sistemas diferentes. Na maior parte das vezes, essas trocas de dados tem como objetivo automatizar processos manuais e/ou permitir a criação de novas funcionalidades. Resumidamente, uma API funciona como uma “ponte” que permite a conexão entre um dispositivo de um solicitante e um específico banco de dados.

Por meio de APIs, desenvolvedores podem criar novos softwares e aplicativos capazes de se comunicar com outras plataformas.

Por exemplo: um software de CRM, como o PipeRun, recebe uma informação sobre um lead que desistiu de uma compra. Portanto, envia a informação deste lead, via API, para uma outra plataforma, como a RD Station, com o intuito de realizar a nutrição do lead para que este volte a comprar o produto/serviço no futuro. Neste caso, acontece uma troca de dados para automatizar um processo que seria manual.

Ou então: toda vez que um lead entra em uma determinada etapa de funil, um SMS poderá será disparado para este lead, automaticamente. Esse disparo automático só é possível graças à comunicação entre a API do PipeRun e a API da empresa de telefonia.

Confira as integrações disponíveis no PipeRun clicando aqui.

COMO CONSUMIR UMA API?

Para consumir uma API é necessário realizar uma requisição.

A requisição pode ser realizada tendo os seguintes itens na sua estrutura:

  • Uma URL apontando para o recurso a ser consumido (também conhecido como endpoint);
  • Parâmetros query string para realizar buscas;
  • Método de requisição (são os famosos "verbos");
  • Header e body, caso precise criar ou alterar alguma informação no banco de dados.
A API sempre retornará um status code informando a situação da requisição. Se ela foi bem sucedida, se não foi permitida, se o endpoint não existe, etc.

ESTRUTURA DE UMA REQUISIÇÃO

Uma requisição possui alguns elementos na sua estrutura. São eles:

Confira sobre cada um abaixo.

URL

Na requisição, é necessário utilizar um URL. Ele é composto por:

  • Base URL

Esse é o início do URL da requisição. Aqui você basicamente especificará a informação de domínio que se repete em qualquer requisição. Digamos que você queira utilizar a API do PipeRun, então:

https://api.pipe.run/v1

  • Resource (ou Path)

O recurso (resource) é a rota para o tipo de recurso que você quer que a API acesse.

Por exemplo: vamos simular que estamos buscando os dados das empresas cadastradas na sua conta do PipeRun. Então acrescentamos o recurso /companies à base URL:

https://api.pipe.run/v1/companies

  • Query String

Query string são os parâmetros de busca da requisição.

Por exemplo: para buscar pelas empresas cadastradas na conta do PipeRun que possuem um nome que comece com "escritório" (para um exemplo onde eu esteja buscando por escritórios de advocacia, por exemplo):

?starts_with=escritorio

e nossa URL ficaria assim:

https://api.pipe.run/v1/companies?starts_with=escritorio

Como podem ver, por se tratar de parâmetros de busca da URL você usa o "?" antes de especificar o parâmetro e caso queira utilizar mais de um parâmetro você utiliza o "&" para separar os parâmetros.

Exemplo de múltiplos parâmetros:

https://api.pipe.run/v1/companies?starts_with=escritorio&id=12345

Embora o exemplo utilizado acima foi o de uso de filtro, a Query String não é utilizada somente para filtros. Ela pode ser utilizada como parâmetros de paginação, versionamento, ordenação, relações, etc.

MÉTODO

O método serve para informar o tipo de ação que você quer fazer na requisição.

Dentre os principais métodos, temos:

  • GET (Buscar dados);
  • POST (Enviar dados);
  • PUT e PATCH (Atualizar dados);
  • DELETE (Deletar dados).

Existem vários outros métodos que não serão citados no artigo. Nesse link você pode conferir a lista completa.

HEADERS

Headers, ou cabeçalhos da requisição permitem que você envie informações adicionais à requisição. Ele pode ser utilizado para inúmeras funções, como: autenticação de usuário, formatação de objeto, etc.

No caso da API do PipeRun, é necessário utilizar o token da conta para autenticação ao realizar as requisições. Caso o token não seja informado, o acesso ao recurso que está sendo requisitado não será permitido.

BODY

O body é o corpo da requisição que você quer enviar na requisição. Ele é utilizado somente nos métodos de POST, PUT e PATCH. Não é necessário em métodos de leitura de dados (como o GET).

Por exemplo: digamos que você queira adicionar uma nova empresa via API no PipeRun. Neste caso, utilizando o método POST, os dados que serão adicionados deverão ir no body da requisição, como o nome, endereço e contato da empresa. Algumas informações são obrigatórias. Você pode conferir essas informações na documentação da API do PipeRun.

HTTPS STATUS CODE

Para facilitar o entendimento das respostas das APIs existem padrões de códigos de status que podem ser utilizados.

Os códigos mais utilizados para as respostas de uma requisição são o 200 ("Ok"), o 201 ("Created"), o 204 ("No content"), o 404 ("Not found"), o 400 ("Bad request"), e 500 ("Internal server error").

Existem vários outros códigos de resposta do protocolo HTTP que podem ser utilizados. Neste link temos a lista completa.

Como padrão, os códigos de sucesso tem o prefixo 20x, os de redirecionamento 30x, os de erro do cliente 40x e os de erro de servidor 50x.

AUTENTICAÇÃO

Não podemos falar de APIs sem falar de segurança, afinal estamos falando de serviços WEB.

Como principais métodos de autenticação de APIs, temos:

  • Basic authentication: Baseado em usuário e senha codificados em Base64 e utilizado no header da requisição;
  • Secret token;
  • Token de acesso que pode ser limitado a escopo, e que é enviado na requisição pelo Header ou pela Query String. Nesse caso temos padrões famosos como o Auth e JWT.
Geralmente, as APIs possuem documentação para que o usuário possa entender seu funcionamento. Sempre leia a documentação antes de utilizar uma API. Clique aqui para conferir a documentação da API do PipeRun.

POR QUE USAR UMA API?

Como vimos, uma API pode mudar o dia a dia da empresa, agregando simplicidade, agilidade e automação aos sistemas. No CRM PipeRun, diversas integrações estão configuradas, buscando trazer facilidade de comunicação entre plataformas diferentes das áreas de marketing e vendas.

Portanto, a API pode ser utilizada para agregar agilidade em áreas da empresa, ou mesmo aperfeiçoar áreas estratégicas de importância.

Por exemplo: uma organização que tem como meta para o ano dobrar o número de clientes pode adotar o uso de consumo de APIs na Pré-venda para ter maior eficiência na qualificação e conversão de leads.

Em caso de dúvidas, chame nossa equipe no chat. 😉