Integração personalizada para receber dados de sistemas externos

No Connectif, é possível receber dados de sistemas externos para utilizar informações que não são registradas por padrão na plataforma. Por meio de uma integração personalizada, você poderá sincronizar os dados dos seus contatos com base em eventos gerados em outras plataformas.

Neste artigo, explicamos quais são os tipos de integração personalizada para receber dados e como criar um evento desse tipo, com um exemplo de integração com o ERP.

1. Propriedades

Eventos de recepção de dados

• Os eventos de recepção de dados são uma ferramenta poderosa para ampliar e personalizar o Connectif de acordo com seus próprios casos de uso.

• Ao criar um novo evento de recepção, você deve indicar o contexto: 

  • API pública.

  • Webhook.

  • Web ou App móvel.
     

Evento de recepção por meio de API pública

Os eventos de recepção por meio de API pública são o mecanismo mais seguro, pois exigem uma Chave API. Eles são projetados para que os eventos sejam enviados do seu servidor para o Connectif.

Características e limites:

• O tamanho máximo de um evento é de 512KB.

• É obrigatório definir um campo email como obrigatório e chave primária para identificar o contato.

• É possível indicar por meio do query string createContact se deve criar ou gerar erro quando o contato ao qual pertence o evento não existe.

• O nó disparador do workflow gerado por um evento de recepção por API pública não terá contexto web.

• Exigem validação rigorosa e não permitem enviar campos que não estejam definidos no evento.

Evento de recepção por meio de Webhooks

Os eventos de recepção por meio de Webhook são um mecanismo mais flexível, ideais quando não se controla o emissor dos dados, por exemplo, usar um webhook de uma ferramenta externa onde não é possível alterar o formato dos dados emitidos ou onde não é possível estabelecer um cabeçalho de segurança com chave API.

Características e limites:

• O tamanho máximo de um evento é de 512KB.

• É obrigatório definir um campo email como obrigatório e chave primária para identificar o contato.

• Sempre criam o contato no Connectif se não existir.
• Permitem definir JSON Pointer para mapear campos a estruturas complexas. Ideal quando a informação do evento está em objetos complexos e aninhados.
• Não geram erro de validação em caso de campos desconhecidos. Dessa forma, permite mapear apenas os campos que interessam, ignorando outros que serão simplesmente desconsiderados.

• O nó disparador do workflow gerado por um evento de recepção por Webhook não terá contexto web.

Evento de recepção por meio de Web ou App móvel

Os eventos de recepção por meio de Web ou App móvel permitem enviar eventos diretamente do lado cliente do seu site ou do seu app móvel. Para isso, é necessário usar respectivamente o SDK Web ou SDK Mobile.

Características e limites:

• Os eventos por Web ou App não exigem um campo email obrigatório e chave primária. Podem, portanto, ser enviados para contatos anônimos ou conhecidos durante o tracking web ou do seu app móvel.

• O nó disparador do workflow gerado por um evento de recepção por Web ou App móvel terá contexto web. Após esse nó, é possível usar o nó Mostrar conteúdo web.
   

2. Como funciona a criação de um evento de recepção de dados no Connectif

O processo de criação de um evento de recepção de dados consiste em alguns passos a seguir, independentemente do mecanismo escolhido. 

Como exemplo, a seguir mostramos como seria a criação de um evento de recepção de dados para conectar um ERP com o Connectif:

2.1. Criação da integração personalizada

1. Acesse "Integrações > Personalizadas" e clique em  Criar nova integração.

2. Defina o campo "Nome" para identificar a integração.

3. (Opcional) Personalize a cor, inclua uma descrição ou categorize a integração.

4. Clique em Atualizar.

2.2 Criação e configuração do evento "Receber Dados"

(Nesta seção será criado o evento de recepção e configurados os campos onde os dados recebidos serão armazenados).

5. Na aba Receber dados, clique em Criar novo evento de recepção.

6. Na janela pop-up, escolha o tipo de conexão para o evento e clique em Ir para o editor. No nosso exemplo, via API pública.

7. Atribua um Nome e um Alias ao evento.

8. Clique em Adicionar um novo campo para criar um campo do tipo Email, para coletar o e-mail do contato. 

9. Repita a ação indicada no ponto anterior quantas vezes quiser para os dados que deseja receber. 

10. Clique em Salvar e, na tela de confirmação, clique em Voltar à lista de eventos.

2.3. Criação da Chave API para habilitar a recepção de dados

(Nesta seção, explica-se como gerar o endereço para notificar o tipo de evento criado, o endpoint).

10. Vá para "Configurações da loja > API e acessos IP" e, em Chaves API, clique em Criar nova chave API.

11. Na seção Eventos personalizados, ative a permissão para Escrever.

12. Salve a chave API e, no menu de Chaves API, localize a que você acabou de criar e clique no botão para copiá-la (indicado na imagem).

13. Use a chave API para fazer a requisição de envio do evento a partir do seu sistema. 

2.4. Obtenção do endpoint de notificação

(Nesta seção, explica-se como gerar o endereço para notificar o tipo de evento criado, o endpoint).

14. Na aba Receber dados, clique em Editar.

15. Clique em Copiar URL para copiar para a área de transferência o endereço do endpoint.

2.5. Envio de dados para o Connectif

(Nesta seção explica-se como estabelecer a comunicação com o endpoint e enviar dados).

16. No seu código, cole esta URL junto com a Chave API e o corpo da requisição para gerar o evento de recepção. No caso de eventos via Webhook ou Web/App, não será necessário usar a Chave API.

17. Faça a chamada ao endpoint para notificar os dados do evento.

2.5.1 Exemplo de envio de dados via Postman (Webhook)

Uma vez configurado o evento de recepção no Connectif, é possível realizar testes de envio de dados utilizando o Postman para verificar se a informação está sendo recebida corretamente.

Configurar a requisição

1. Abra o Postman e crie uma nova requisição.
2. Selecione o método POST.
3. Insira como URL o endpoint gerado para o evento de recepção.

Exemplo:

https://webhook-api.connectif.cloud/{store-id}/custom-events/alias/webhook-event-example

Configurar os cabeçalhos (Headers)

Adicione os cabeçalhos necessários para o envio dos dados:

Configurar o corpo da requisição (Body)

Selecione Body > raw > JSON e insira um payload conforme os campos definidos no evento.

Exemplo:

{
    "email": "john.doe@example.org",
    "phone": "+34666777888",
    "name": "Hi there!"
}

Enviar a requisição

Clique em Send para fazer a solicitação.

Se a requisição for processada corretamente, o evento será recebido pelo Connectif e poderá ser usado em workflows, segmentações ou processos de automação.

Recomenda-se verificar o recebimento do evento por meio de um workflow de teste ou revisando a atividade do contato associado aos dados enviados.

Resultado:

A imagem a seguir mostra um exemplo de uma requisição realizada corretamente pelo Postman e a resposta devolvida pelo Connectif.

2.5.2 Exemplo de envio de dados via Postman (API)

Uma vez configurado o evento de recepção e criada a Chave API, é possível usar o Postman para verificar se o Connectif recebe corretamente os dados enviados.

Configurar a requisição

1. Abra o Postman e crie uma nova requisição.
2. Selecione o método HTTP indicado na documentação do endpoint que você vai usar.
3. Insira a URL correspondente ao endpoint da API.

Exemplo:

https://api.connectif.cloud/custom-events/alias/api-event-example?createContact=true

Configurar os cabeçalhos (Headers)

Adicione as credenciais exigidas pelo endpoint por meio dos cabeçalhos correspondentes.

Substitua {api_key} pela Key Secret correspondente.

Configurar o corpo da requisição (Body)

Selecione Body > raw > JSON e insira um payload conforme os campos definidos no evento.

Exemplo:

{ 
    "email": "john.doe@example.org", 
    "name": "Hi there!", 
    "phone": "+34666777888" 
}

Enviar a requisição

Clique em Send para fazer a solicitação.

Se a requisição for processada corretamente, a API retornará uma resposta satisfatória e os dados serão registrados no Connectif conforme a funcionalidade utilizada.

Resultado:

A imagem a seguir mostra um exemplo de uma requisição realizada corretamente por meio da API pública usando uma Chave API com permissões de escrita para eventos personalizados.

2.6. Sincronização dos dados com as informações do contato

(Nesta seção explica-se como sincronizar os dados no Connectif por meio de um workflow).

18. Acesse “Workflows”, clique em Criar novo workflow e selecione Criar workflow em branco.

19. Crie a estrutura do seu workflow com o nó do tipo disparador “Disparador [nome da sua integração]” e o nó do tipo ação “Definir campo”.

20. No nó “Disparador Receber dados de…”, clique em (Editar configuração do nó).

21. Verifique se os dados coletados pelo nó "Disparador Receber dados de...", provenientes do evento no sistema externo, estão corretos.

22. Clique em Salvar.

23. No nó “Definir campo”, clique em (Editar configuração do nó).

24. Relacione as variáveis para atribuir as informações coletadas pela integração personalizada aos campos de contato correspondentes.

25. Clique em Atualizar.

26. No workflow, clique em  Salvar para salvar as alterações e em  Iniciar para ativá-lo.

2.7. Criação de um Segmento Dinâmico Plus da integração

Com o Connectif, você poderá criar um Segmento Dinâmico Plus para filtrar pelas atividades e campos relacionados à integração personalizada.

Depois de criar um segmento de contatos da integração personalizada, ele não poderá ser excluído. Além disso, se algum de seus campos estiver sendo usado como condição de segmentação, também não poderá ser excluído nem editado. 

Continue aprendendo!

Para aproveitar todo o potencial da sua conta no Connectif, recomendamos continuar com os seguintes artigos:

• Integração personalizada para enviar dados, para enviar dados do Connectif para sistemas ou aplicativos externos.

• Detectar e reagir a links web criados fora do Connectif, para identificar e responder aos cliques em qualquer link do seu site.

• Integração com Facebook e Instagram, para gerenciar as audiências da sua conta do Facebook Ads com o Connectif.

• Formulários integrados, para detectar e coletar no Connectif formulários já existentes no seu site.