Usar a API do E-goi

Home > Português > Integrações > Usar a API do E-goi

Temas deste artigo

 

O E-goi oferece centenas de integrações e uma API para realizar ações remotas, como adicionar contatos e enviar campanhas.

 

 

O que é a API do E-goi?

A API (Application Programming Interface) do E-goi é uma ferramenta poderosa que permite realizar ações remotas na plataforma, como adicionar contatos ou enviar campanhas. Com a capacidade de se integrar com inúmeros serviços, a API expande significativamente a funcionalidade e a automação que o E-goi pode oferecer. Este artigo visa guiá-lo através do acesso e uso da sua chave de API (API key) e do Goidini, bem como fornecer dicas de segurança e sugestões de integração.

 

 

O que é um webhook?

É um mecanismo através do qual o E-goi notifica automaticamente um URL à sua escolha sempre que acontece um certo evento, como a inscrição de um contato, um clique num email, etc.

Quando o evento acontece, o E-goi envia um pedido por HTTP (normalmente um POST) para o URL que escolheu. A partir daí, pode armazenar e processar os dados do seu lado num outro software ou serviço.

Um webhook é uma forma simples de integrar o E-goi com sistemas ou serviços que não se integram diretamente com a plataforma.

 

 

 

Antes de começar

 

Segurança e necessidades

Preparar-se para utilizar a API do E-goi envolve alguns passos iniciais importantes:

  • Verifique suas necessidades: Tenha claro o que deseja alcançar com a API, seja para adicionar contatos automaticamente, enviar campanhas de e-mail programaticamente, entre outras funcionalidades.
  • Segurança é fundamental: Antes de prosseguir, entenda que sua chave de API é tão sensível quanto a sua senha. Tê-la em mãos é essencial, mas deve guardá-la num local seguro e longe de acessos não autorizados.

 

 

Custos

A API está disponível em todos os planos E-goi (incluindo o plano grátis 5001), exceto no plano GoSend. Cada plano tem um limite de chamadas à API, conforme o nosso tarifário.

 

 

Passo-a-passo

 

Encontrar a sua chave da API

1) Acesse o E-goi, clique no menu de usuário (canto superior direito) e depois em Integrar.

2) Em Chave da API, estará a chave pronta a copiar.

 

 

 

Manuseio seguro da sua chave de API

Nunca compartilhe sua chave de API com outras pessoas e somente use-a em integrações de confiança, pois ela dá acesso remoto à sua conta E-goi.

 

 

O que fazer em caso de roubo da chave de API

1) Clique no menu de usuário (canto superior direito) e depois em Integrar.

2) Em Chave da API clique no ícone Regenerar a chave para obter uma nova, invalidando a anterior.

 

 

Criar um webhook

Atenção! Para criar e usar webhooks, é necessário ter conhecimentos técnicos de programação.

1) Clique no menu no canto superior direito (onde está o seu ícone de usuário ou foto de perfil) e escolha Integrar.

2) No painel do lado esquerdo, clique em Marketing API ou Transacional API ou Registered API dependendo da API do E-goi onde quer adicionar o webhook.

3) Clique no separador Gestão de webhooks à direita e depois em Adicionar webhook. Introduza o URL do webhook (ou seja, o URL do seu site que vai receber as informações do E-goi), escolha a lista de contatos onde constam os dados que vai enviar e, por fim, assinale os eventos propriamente ditos (inscrições na lista, aberturas de emails, etc.). Clique em Gravar para criar o webhook.

Daí em diante, sempre que ocorrer um dos eventos que assinalou, o E-goi enviará os dados desse evento para o URL do webhook, onde pode depois processá-los do seu lado.

 

 

Ver estatísticas de uso

1) Clique no menu no canto superior direito (onde está o seu ícone de usuário ou foto de perfil) e escolha Integrar.

2) No painel do lado esquerdo, clique em Marketing API ou Transacional API ou Registered API dependendo do tipo de estatísticas que pretende ver. 

Aparecerão do lado direito as estatísticas dessa API. Se também quiser ver as estatísticas dos webhooks correspondentes, clique no separador Gestão de webhooks.

Em cada estatística, além dos totais, constará cada pedido (ou seja, o log) com:

  • URL
  • data e hora
  • código de resposta
  • dados completos do pedido, entre os quais:
    • pedido (payload)
    • código da resposta
    • cabeçalho da resposta
    • tempo de resposta
    • resposta detalhada

 

 

Perguntas frequentes

 

É difícil integrar a API do E-goi com outros sistemas?

Não. A API do E-goi foi idealizada para ser flexível e acessível a programadores. Com uma boa leitura da documentação disponível em inglês, pode integrar o E-goi com inúmeros sistemas, sites ou softwares.

A maioria dos problemas de integração via API está relacionada com autenticação, estrutura dos pedidos, limites da API ou formatação incorreta do payload.

A API devolve erro

Confirme:

  • se a chave da API está correta e ativa.
  • se o endpoint da API está correto.
  • se o método HTTP que usou é o esperado (GET, POST, PUT, DELETE, etc.).
  • se o payload que enviou está em JSON válido.
  • se todos os campos obrigatórios do pedido foram enviados.
  • se não ultrapassou os limites de uso da API da sua conta E-goi.
Exemplo: Um pedido pode devolver erro porque o campo "email" foi enviado vazio ou porque o JSON tem uma vírgula extra que invalida o payload.

Erro de autenticação da API

Normalmente acontecem quando:

  • a sua chave da API não está correta.
  • a sua chave da API foi eliminada ou regenerada.
  • o seu pedido usa credenciais de autenticação erradas.
  • o cabeçalho de autenticação não foi enviado corretamente.

Confirme sempre que usa a chave API correta da sua conta E-goi e que o seu pedido tem os cabeçalhos necessários conforme a documentação do pedido.

Pedido (ou request) inválido

Este erro indica que o pedido que fez à API não respeita o formato ou regras que a API supõe.

Causas mais comuns:

  • faltam campos obrigatórios do pedido.
  • tipos de dados inválidos.
  • ID dos elementos do pedido (ex. contato, campanha) não existem.
  • payload JSON mal formatado.
  • uso incorreto do endpoint ou método HTTP.
Atenção! Mesmo pequenas diferenças na estrutura do JSON podem invalidar o pedido enviado à API.

Limites da API

Para proteger a estabilidade do E-goi, a API pode aplicar limitações temporárias quando recebe um volume excessivo de pedidos em pouco tempo.

Nesses casos:

  • alguns pedidos podem falhar temporariamente.
  • a API pode devolver erros de limitação (rate limit).
  • reduza a frequência dos seus pedidos e tente de novo mais tarde.
Atenção! Se faz integrações de grande volume, implemente mecanismos automáticos de retry, queue e controlo de velocidade dos seus pedidos.

Validar o payload JSON

Antes de fazer pedidos à API do E-goi, confirme que o seu JSON:

  • tem uma estrutura válida.
  • não tem vírgulas extra.
  • usa aspas corretamente.
  • envia os campos que a API espera.
  • respeita os formatos de data, endereços de email, ID e listas de contatos.
Ferramentas como Postman, Insomnia ou validadores JSON na web podem ajudar a testar o seu payload antes de usá-lo na API.

 

Onde posso encontrar exemplos ou inspiração para integrações?

Updated:

Outros artigos

and 27 more ...