Searching for

Chamadas de API

As Chamadas de API (API Calls) são formas de fazer um software conversar com outro e permitir a troca de informações entre eles. Dessa forma, é possível integrar dados de diferentes plataformas, mesmo que não haja uma integração nativa no aplicativo.

Como funcionam as Chamadas de API?

Em nosso sistema, é possível realizar Chamadas de API em automações. Isso significa que você pode enviar ou receber informações para/de outro aplicativo, e os dados ou atributos capturados podem ser usados para personalizar o caminho do contato dentro da automação, integrar aplicações ou sincronizar dados entre bancos de dados para enriquecer as informações do contato.

Exemplo de uma chamada de API

Ao gerar uma Chamada de API, você estará lançando uma mensagem direcionada, que será recebida pelo servidor do software de destino.

Opções de ação de uma chamada de API (HTTP method)

O método HTTP de APIs pode executar cinco ações diferentes em uma base de dados:

  • GET: receba informação de um local.
  • POST: envie informações para outro local.
  • DELETE: delete informações.
  • PUT: edite/atualize informações.
  • PATCH: edite/modifique uma informação específica.

Como transmitir esses dados

A escolha do formato do dado que você vai transmitir vai depender do que o software que vai receber esta informação aceita. Cada software possui uma linguagem própria, e é importante que essa mesma linguagem seja utilizada para receber e enviar dados por uma chamada de API:

  • Json: JavaScript Object Notation é uma forma de trocar informações entre sistemas de forma leve e rápida. É a principal linguagem de comunicação entre softwares.
  • XML: provê acesso serial ao conteúdo de um documento XML de forma orientada.
  • Plain Text: utilize caso o aplicativo possibilite o envio de dados na forma de texto puro.
  • Plain HTML: usado para aplicações de terceiros que enviam dados em HTML puro.
  • URL encoded form: método usado para fazer requisições em forma de URL codificada.

O Pipz recebe os dados apenas em JSON.

URL, API Key e API Secret

Para fazer uma API Call funcionar em automação, você precisará de alguns dados básicos:

  • URL: o endereço de origem ou destino da informação. Cada sistema tem uma URL própria, mostrando o caminho que os dados devem seguir;
  • API Key: a chave é única para cada conta e funciona para identificar qual usuário está requisitando dados;
  • API Secret: é a senha que, aliada ao API Key, autoriza a troca de informações entre sistemas.

Esses dados permitem a autenticação básica, ou Basic Authentication. O Pipz apenas realiza este tipo de autenticação.

Como criar uma chamada de API no Automations do Pipz

Na aba Steps da automação que você está editando, clique e arraste no sinal (+) de um passo já criado e selecione o passo API Call. É este passo que permite o compartilhamento de informações com outro sistema:

Passo de Chamada de API em uma automação

  1. Selecione o HTTP method que quer para aquele passo: GET, POST, PUT, PATCH ou DELETE.
  2. Adicione a URL do sistema que vai se comunicar com a sua base do Pipz.
  3. Escolha o tipo de conteúdo que você quer compartilhar (Json ou outro).
  4. Em Payload: cole, no formato de dados compatível com o sistema que vai receber os dados, quais informações serão trocadas.
  5. Em User e Password: insira as informações de autenticação do sistema com quem você está se comunicando (opcional em alguns casos). Aqui é o API Key é API Secret, respectivamente.
  6. Em Object name: escolha um nome para esta API Call. Isso faz com que seja possível resgatar as informações geradas por este API, principalmente no GET, em outros Steps da automação. Este passo é especialmente importante nos casos de criação de condição baseada em resultados de API, como vamos mostrar mais abaixo.

Segue um exemplo de como deveriam ser enviados os dados para criar um contato no Pipz usando um método POST:

Chamada de API POST na automação do Pipz

POST https://api.pipz.io/v1/contact/ Content type: Json

{
    "name": "John Doe",
    "email": "joe@doe.com",
    "job_title": "Director of Sales",
    "phone": "+1089647827",
    "remote_id": "johndoe123",
    "company_id": 561
}

Pronto! Em seguida continue a construção do seu fluxo com os próximos passos.

Criando condições a partir de dados da Chamada de API

É possível usar uma Chamada de API como condição de uma automação caso o método HTTP escolhido seja GET (puxar um dado de outro sistema para o Pipz). Assim, a informação recebida pode gerar uma bifurcação TRUE ou FALSE. Veja o exemplo abaixo:

Condição em Chama de API - Pipz

Como funciona a Chamada de API do Pipz

Uma Chamada de API possui a seguinte estrutura:

{
    "system": {
        "origin": "manual",
        "started_at": "2017-06-21T14:37:21.143025+00:00",
        "step_action": "start automation",
        "trigger_event_name": "behaviour_add_contact_to_flow",
        "tracker_id": null,
        "flow_id": 24,
        "flow_name": "Auto 1"
    },
    "user": {
    }
}

A chave system indica as informações geradas pelo sistema automaticamente. Já a chave user diz respeito às informações inseridas ou requisitadas na API Call pelo usuário. Se a chamada for de envio de dados, essas informações serão especificadas no Payload. No caso de GET, são as informações enviadas para o Pipz (não é necessário preencher o payload neste último caso).

A primeira chave dentro da chave user indica o nome da Chamada de API que você configurou inicialmente. Dentro de "*Object Name*": {} estarão as informações que você poderá usar como condição.

{
    "system": {
        "origin": "manual",
        "started_at": "2017-06-21T14:37:21.143025+00:00",
        "step_action": "start automation",
        "trigger_event_name": "behaviour_add_contact_to_flow",
        "tracker_id": null,
        "flow_id": 24,
        "flow_name": "Auto 1"
    },
    "user": {
        "*Object Name*": {
            "email":"admin@ecentry.com",
            "Id":5,
            "Stages":[
              {
                "id":1,
                "name":"New"
              },
              {
                "id":2,
                "name":"Subscriber"
              },
              {
                "id":9,
                "name":"Other"
              },
              {
                "id":3,
                "name":"Lead"
              },
              {
                "id":4,
                "name":"Marketing Qualified Lead"
              },
              {
                "id":5,
                "name":"Sales Qualified Lead"
              },
              {
                "id":6,
                "name":"Opportunity"
              },
              {
                "id":7,
                "name":"Customer"
              },
              {
                "id":8,
                "name":"Evangelist"
              }
            ],
            "name":"Admin"
        }
    }
}

São estas as informações que você poderá usar para criar condições na automação. Veja abaixo.

Condicionando Steps a partir de uma Chamada de API

Agora que você entendeu como funciona uma Chamada de API para criar condições (GET), vamos ver na prática como fazer uma.

  • Crie uma Chamada de API, configurando que dados você quer puxar para o Pipz nesta automação a partir da base que mantém essa informação. Esta URL https://api.pipz.io/v1/contact/{{email}}/ que vamos usar como exemplo vai puxar os dados segundo a variável {{email}}. Ou seja, ao entrar um contato na automação, o Pipz vai gerar uma requisição para receber as informações do contato com aquele e-mail.

  • Insira a API Key, APi Secret e o nome que deseja dar para aquela Chamada de API (em Object Name). Para este exemplo, vamos usar learningcenter.

  • Crie uma condição na automação. Você já sabe qual informação quer verificar, certo? Neste exemplo, queremos saber se os contatos que entrarem na automação estão no ´Stage´ Lead.

Condição na Automação - Chamada de API - Pipz

  • Configure a condição: selecione a opção Saved Result From API Call como dado para a condição. Em Attribute, coloque o dado que quer verificar. Mas atenção! É preciso inserir o caminho de verificação do código que você quer que o sistema faça, confirme ensinamos acima (user.*Object Name*.Attribute). Neste caso é: user.learningcenter.stage.

  • Escolha o parâmetro (contém, é, não é, etc.) e o valor (Lead, MQL, Other, Evangelist, etc.).

  • Crie passos para as opções TRUE e FALSE da automação. No exemplo, escolhemos a notificação e customizamos o assunto do e-mail para cada situação.

  • Salve e teste a sua automação! Depois, basta deixá-la rodando.

Chamada de API no Pipz (API Docs)

Para criar Chamadas de API apontando para o Pipz, seja para GET, POST ou PATCH, consulte a nossa documentação (API Docs) para verificar os links de cada situação.

O Database Name necessário para cada atributo está especificado nos artigos.

Lembre-se que o Pipz apenas recebe dados em Json.