Pular para o conteúdo
Nesta página
Integrações

Webhooks e chaves de API

A seção Integrações (API / Webhooks) liga o DeepLead a outros sistemas. Ela tem um endereço que recebe contatos (formulário do seu site, Make, Zapier, ERP) e outro que dispara campanhas de e-mail. Os dois se autenticam com uma chave de API criada na mesma tela.

# Onde fica

  1. No seletor de módulo, no topo, escolha CRM.
  2. No rodapé do menu, clique em Configurações.
  3. Na lista de seções, clique em Integrações (API / Webhooks).

A tela tem quatro blocos: APIs & Webhooks, Chaves de API, Alertas de Câmbio
e Histórico de chamadas. O alerta tem artigo próprio:
Alertas de câmbio.

# Quem pode usar

Quem tem a página Configurações liberada para o perfil e enxerga o módulo CRM.
Dentro da seção não há restrição por perfil: quem abre a tela cria e remove chaves.
Para limitar, veja Permissões por página.

# Criar uma chave de API

  1. No bloco Chaves de API, clique em Nova chave.
  2. Em Nome da chave, escreva onde ela será usada (por exemplo Formulário do site).
  3. Clique em Gerar chave.
  4. Copie a chave com o botão ao lado dela. A tela avisa: “Atenção: esta chave será
    exibida apenas uma vez!”.
  5. Clique em Fechar.

Depois de fechar, a lista mostra só o começo da chave. Perdeu a chave, crie outra e
remova a antiga.

A mesma chave vale para os dois endereços. Crie uma chave para cada sistema: assim dá
para desligar um deles sem parar os outros. A coluna Último uso mostra quais estão
em uso.

# Desativar, reativar e remover uma chave

Na coluna Ações de cada chave:

  • Desativar / Ativar (ícone de liga e desliga): a chave desativada é recusada
    na hora e pode ser ativada de novo.
  • Remover (lixeira): a tela avisa que “Qualquer sistema que use esta chave deixará
    de funcionar imediatamente.”. Clique em Remover. Não dá para desfazer.

# Restringir a chave a domínios

  1. Na linha da chave, clique no ícone de globo (Domínios permitidos).
  2. Em Adicionar domínio, digite exemplo.com ou *.exemplo.com e clique no +
    (ou tecle Enter).
  3. Repita para os outros domínios. Para tirar um, clique no x ao lado dele.
  4. Clique em Salvar.
  • Lista vazia: “qualquer domínio será aceito”.
  • *.exemplo.com cobre o domínio e todos os subdomínios; exemplo.com cobre só ele.
  • A lista é conferida nas chamadas de rastreamento que partem do navegador de quem
    visita o seu site (veja Rastreamento do site). O Webhook de
    Contatos e a API de Campanhas são chamados de servidor para servidor e não passam por
    essa conferência.

# Webhook de Contatos

Cria ou atualiza contatos por POST.

  1. Em APIs & Webhooks, clique em Webhook de Contatos para abrir o cartão.
  2. Copie o endereço em URL do Endpoint.
  3. No sistema de origem, configure um POST para esse endereço com os cabeçalhos
    x-api-key (a sua chave) e Content-Type: application/json.
  4. Envie o contato em JSON. As abas Básico, Lote / Múltiplos e Variações
    trazem exemplos prontos para copiar.
Campo O que é
email E-mail do contato. Único campo obrigatório.
name Nome completo. Sem ele, o contato entra com o trecho do e-mail antes do @.
phone Telefone com DDI.
company, trade_name, document, website Empresa, nome fantasia, CPF ou CNPJ e site.
referrer Nome de quem indicou.
birth_date Data de nascimento (DD/MM/AAAA ou AAAA-MM-DD).
status active, inactive ou unsubscribed.
notes Observações.
lead_score Pontuação do lead (número inteiro).
tags Lista de tags. As que não existem são criadas.
custom_fields Objeto com a chave de cada campo personalizado e o valor.
address Objeto com street, number, complement, neighborhood, city, state, zip_code e country (duas letras, como BR).

Regras:

  • O contato é procurado pelo e-mail e, se não for achado, pelo telefone. Achou: só os
    campos enviados são atualizados. Não achou: cria um contato novo, com status active
    quando nenhum é informado.
  • Nome travado na ficha (cadeado ao lado do campo Nome) não é alterado pelo webhook.
  • Para mandar vários contatos, envie {"contacts": [ ... ]}. Cada um é tratado
    separadamente: o de e-mail inválido vira erro e os demais entram.
  • Para o contato já cair numa lista, acrescente ?list_id= ao endereço. O endereço
    pronto, com o list_id, está no detalhe de cada lista (veja Listas). A
    lista precisa ter sido criada pelo mesmo usuário que criou a chave.
  • O bloco Campos personalizados desta conta mostra a chave, o tipo e as opções de
    cada campo. null apaga o valor; campo não enviado fica como está. Valor inválido
    não impede salvar o contato: aparece nos erros da resposta.
  • O endereço pode vir incompleto: o que foi enviado é gravado.
  • A resposta traz created, updated e errors.

# API de Campanhas

Dispara uma campanha de e-mail a partir de um template. O cartão API de Campanhas
traz a URL do Endpoint e os exemplos.

Campo O que é
template_id Identificador do template de e-mail. Obrigatório.
target list, contacts ou all. Obrigatório.
list_id Lista de destino. Obrigatório quando target é list.
contact_ids Lista de identificadores de contatos. Obrigatório quando target é contacts.
variables Objeto com as variáveis do template.
subject, from_name, from_email Trocam o assunto e o remetente só nesse envio. Sem eles valem os do template e do perfil.
sending_rate Número máximo de e-mails por lote.

Regras:

  • Só contatos com status ativo recebem. Quem se descadastrou fica de fora.
  • Cada chamada cria uma campanha, que aparece em Campanhas com as estatísticas de
    abertura e clique.
  • O mesmo template disparado de novo em menos de 60 segundos não é reenviado: a resposta
    devolve a campanha já criada, com duplicate: true.
  • O envio usa o remetente configurado na conta. Veja
    Remetente e domínio de e-mail.

# Acompanhar as chamadas

O bloco Histórico de chamadas lista as últimas 100 chamadas recebidas.

  1. Filtre por Status (Sucesso, Parcial, Erro), por Tipo (Contatos,
    Lista, Campanha) e pelo período (De e Até).
  2. Leia as colunas Recebidos, Processados e Atualizados.
  3. Clique no ícone de olho para abrir Detalhes da chamada, com a lista de Erros
    e o Payload recebido.

Parcial significa que parte dos contatos entrou e parte deu erro.

# Problemas comuns

O que aparece O que fazer
“Chave de API ausente. Envie o header x-api-key.” O cabeçalho x-api-key não chegou. Confira o nome dele no sistema de origem.
“Chave de API inválida.” A chave foi digitada errada ou removida. Crie outra.
“Esta chave de API foi desativada.” Ative a chave na lista ou use outra.
“JSON inválido no body da requisição.” O corpo não é um JSON válido. No Make, siga o bloco Dica para Make.com / Integromat do cartão.
“Lista não encontrada ou não pertence a este usuário.” O list_id está errado ou a lista é de outro usuário. Copie o endereço no detalhe da lista.
“Formato inválido. Use: exemplo.com ou *.exemplo.com” Digite só o domínio, sem https:// e sem caminho.

# Veja também