Conversões e conectores

Enviar conversões para Meta, Google e TikTok e entregar leads a sistemas externos (Kommo, HTTP próprio).

Conversões e conectores

Este guia cobre dois assuntos que usam a mesma plataforma de Integrações:

• Conversões: mandar o resultado de um lead (formulário preenchido, lead qualificado, venda) de volta às plataformas de anúncio, pelo servidor, para elas otimizarem a campanha. Hoje: Meta, Google Ads e TikTok.
• Conectores: levar o lead capturado para o sistema do cliente (API própria / CRM próprio e Kommo) e, no caso do Kommo, também ler relatórios dele.

Tudo é configurado no painel. A API pública permite consultar o que foi enviado (GET /v1/conversions); não existe API pública para criar ou editar integrações.

O que existe e o que é planejado. Existem os apps Meta (API de Conversões), Google Ads, TikTok (Events API), API própria (HTTP), Kommo e Kommo somente leitura. Não existem conectores nativos para Zapier, n8n, Make, HubSpot, RD Station ou similares: veja Zapier, n8n e Make. Conectores nativos e gestão de integrações por API (webhooks:manage) são planejados.

Onde configurar

Em Administração → Integrações (https://admin.asender.net/t/<conta>/integracoes) você vê o catálogo de apps e as instalações da conta. Cada instalação mostra o status, a saúde, o tamanho da fila e o último erro, e abre um detalhe com configuração, teste de conexão, entregas e auditoria.

Estados de uma instalação: rascunho (criada, ainda sem credencial válida ou teste ok; não recebe entrega), ativa, pausada (você pausou; as entregas esperam até religar ou 7 dias), reautorizar (a credencial foi recusada; as entregas esperam até reconectar) e removida. Os segredos (tokens, senhas) só são escritos: depois de salvos, o painel mostra apenas se existe e os últimos caracteres.

Conversões para plataformas de anúncio

Quando uma conversão é enviada

Há dois caminhos, e ambos usam as mesmas instalações:

1. Formulário de Páginas. Ao escolher a instalação como destino do formulário, cada lead capturado gera uma conversão (por padrão o evento Lead).
2. Jornada do CRM, ação "Enviar conversão (anúncios)": a conversão offline. Quando algo acontece depois do formulário (o lead virou "qualificado", o negócio foi ganho), a jornada avisa a plataforma para otimizar pelo resultado real. A ação pede: a integração (a instalação), o evento (por exemplo QualifiedLead, Purchase), e opcionalmente valor (decimal com ponto, como 1500.50) e moeda (ISO 4217; o padrão é BRL). O gatilho típico é "Etapa alterada". Os parâmetros são validados ao salvar a jornada, não quando o lead qualifica.

A mesma ação aceita só instalações dos apps meta_capi, google_ads e tiktok_events.

O que é enviado

Em todos os casos o servidor monta o pedido; e-mail e telefone nunca saem em claro, só o hash.

Detalhes que valem a pena conhecer:

• Telefone só é enviado com código do país. Sem +, um número brasileiro de 10 ou 11 dígitos recebe 55; qualquer outro número sem código do país é descartado (um hash errado só geraria ruído na plataforma).
• Deduplicação com o pixel. O event_id é o do navegador (o mesmo que o pixel usou) ou, na falta dele, o id do envio do formulário. Assim a Meta e o TikTok contam o evento uma vez, mesmo que ele chegue pelo pixel e pelo servidor. Para isso funcionar, use o mesmo event_id no pixel do seu site.
• Idade do evento. A Meta recusa event_time com mais de 7 dias; a entrega avisa quando o evento é mais velho que isso.
• Google Ads: o app nasce com "Só validar" ligado (validate_only): o Google valida o pedido, mas não registra a conversão. Desligue quando o teste estiver ok, e confira que a ação de conversão é a certa.

Consentimento

A conversão só sai se o contato consentiu com publicidade/marketing. Sem o consentimento (ausente, recusado, ou formulário sem caixa de aceite), a entrega é ignorada: não vai à plataforma, não conta como erro e não afeta a saúde da instalação. No CRM, o consentimento precisa estar ativo para publicidade. A entrega ignorada aparece com o motivo "o contato não deu consentimento".

Configurar no painel

Meta. Em Integrações, instale Meta (API de Conversões). Informe o ID do pixel (Gerenciador de Eventos → Fontes de dados) e o token de acesso da Conversions API. Opcionais: versão da Graph API e código de evento de teste.

TikTok. Instale TikTok (Events API) com o código do pixel (TikTok Ads Manager → Eventos) e o token de acesso.

Google Ads. Instale Google Ads (conversões), autorize o acesso com a conta Google e informe o ID da conta (10 dígitos, sem hífens), o ID da conta gerente (MCC) se o acesso for por ela, e a ação de conversão (ID ou nome do recurso).

Em cada uma, use Testar conexão antes de ativar. O teste da Meta vai sempre com o código de evento de teste, e o evento aparece na aba de eventos de teste da própria plataforma, sem contar como conversão.

Fora de produção nada é enviado de verdade

Em ambientes de desenvolvimento e homologação, as entregas vão para um sink interno, não para a Meta, o Google ou o TikTok, e o código de evento de teste é obrigatório na Meta e no TikTok, enquanto o Google fica sempre em "só validar". Só em produção a conversão real é enviada.

Ver entregas e erros

No detalhe da instalação, a aba Entregas lista cada tentativa: estado, número de tentativas, código HTTP e o motivo do último erro. O pedido enviado, que carrega dado pessoal, não é exibido; o trecho da resposta da plataforma sai redigido e segredos são mascarados de qualquer mensagem. O que acontece em falha:

São até 12 tentativas por entrega.

Consultar pela API pública: GET /v1/conversions

Escopo conversions:read (chave de API ou token de app; o usuário do token precisa de acesso ao CRM). Mostra o que o CRM registrou na linha do tempo do lead quando uma jornada enviou (ou deixou de enviar) uma conversão offline e o desfecho da entrega. Não traz e-mail, telefone, corpo do pedido nem token.

curl -s 'https://api.asender.net/v1/conversions?limit=100&created_after=2026-10-01T00:00:00Z' \
  -H "Authorization: Bearer $ASENDER_API_KEY"

{
  "data": [
    { "id": "atv_…", "lead_id": "ctt_…", "type": "sent", "event": "QualifiedLead",
      "event_ref": "", "value": "1500.50", "currency": "BRL", "platform": "meta_capi",
      "delivery_status": "enviada", "reason": "",
      "source": { "utm_source": "meta", "utm_campaign": "outubro" },
      "occurred_at": "2026-10-19T14:02:11Z", "created_at": "2026-10-19T14:02:11Z" },
    { "id": "atv_…", "lead_id": "ctt_…", "type": "result", "event": "",
      "event_ref": "…", "platform": "meta_capi", "delivery_status": "enviado",
      "occurred_at": "2026-10-19T14:02:15Z", "created_at": "2026-10-19T14:02:15Z" }
  ],
  "next_cursor": null
}

• type: sent (a conversão entrou na fila de entrega), ignored (não foi enviada; o reason diz por quê) ou result (o desfecho da entrega, ligado à conversão por event_ref).
• platform: meta_capi, google_ads ou tiktok_events.
• delivery_status no result: enviado, simulado (fora de produção), falhou, morta (esgotou as tentativas) ou ignorada_sem_consentimento.
• Os registros não mudam depois de escritos, então created_after basta para sincronizar. limit de 1 a 200 (padrão 50), next_cursor opaco.
• lead_id é o mesmo id de GET /v1/leads e de GET /v1/conversations.
• Este endpoint reflete as conversões da jornada. As entregas de formulário aparecem no detalhe da instalação, no painel.

Detalhes de autenticação, paginação e sincronização incremental estão no guia da API Platform.

A integração de conversão do CRM (Meta)

O CRM também tem uma rota própria para uma integração de conversão só com a Meta: /v1/integracoes-de-conversao na API do CRM (provedor meta, com pixel_id e o token no campo segredo). Ela existe antes do catálogo de Integrações e continua funcionando; para Google Ads, TikTok e para a conversão offline por jornada, use as instalações de Integrações descritas acima. O endereço da API de destino é fixo no servidor: não há campo de URL, de propósito, para que o token de acesso nunca possa ser apontado para outro lugar.

Conectores de lead

API própria / CRM próprio (HTTP genérico)

Envia o lead capturado a qualquer API HTTPS: o seu CRM, uma planilha com endpoint, um sistema interno. Você configura:

• URL (HTTPS), método (POST, PUT ou PATCH) e formato do corpo (json ou form);
• o corpo por modelo, com os campos do lead (até 32 KB) e cabeçalhos fixos (até 20, sem dados secretos);
• a autenticação: nenhuma, chave de API (em cabeçalho ou na query), Bearer, Basic ou OAuth 2 por client credentials;
• assinar o corpo (HMAC-SHA256), para o seu servidor provar que a entrega veio da Asender;
• o critério de sucesso: 2xx e, se quiser, um campo da resposta com valor esperado (para APIs que respondem 200 mesmo com erro);
• opcionalmente o caminho do id gerado na resposta e um link para o registro remoto.

Cada entrega leva os cabeçalhos Idempotency-Key, X-Asender-Entrega-Id e X-Asender-Tentativa, e, com a assinatura ligada, X-Asender-Assinatura no formato t=<unix>,v1=<hex>, onde v1 é o HMAC-SHA256 de "<t>.<corpo>" com o seu segredo. Use o Idempotency-Key para deduplicar do seu lado: uma entrega pode ser repetida. Como verificar a assinatura está no guia de webhooks.

Limites: 10 s por requisição, resposta até 64 KB, até 12 tentativas. Destinos na rede interna ou sem HTTPS são recusados, e redirecionamentos não são seguidos. Use Testar conexão para enviar um lead de exemplo.

Kommo

O app Kommo cria, na etapa escolhida, o lead (negócio) com o contato, com tags, responsável, UTMs e campos personalizados. Você escolhe a conexão:

• Token de longa duração: gerado na Kommo; opcionalmente informe o vencimento (há aviso 7 dias antes);
• Integração privada (OAuth): ID da integração, segredo e o fluxo de autorização da Kommo; a Asender renova o token sozinha.

Configure o subdomínio (minhaempresa em minhaempresa.kommo.com), o funil e a etapa padrão (o painel os lê da Kommo), o responsável, as tags, o modelo do nome do lead e o mapa de campos (campo da Asender para campo da Kommo, até 40). Para não duplicar contatos, a deduplicação usa e-mail e depois telefone; a opção de completar o contato existente nunca sobrescreve um valor já preenchido. Há um limite de requisições por subdomínio para respeitar o da Kommo.

Kommo, somente leitura (relatórios)

O app Kommo (somente leitura) copia leads, contatos, tarefas, notas e eventos da Kommo para relatórios de funil, ganhos e perdas, tempo por etapa e origem. Nunca escreve na Kommo. Você escolhe os funis a sincronizar (vazio = todos) e precisa declarar ter base legal (LGPD) para copiar os dados à Asender, que atua como operadora. Aceita os mesmos dois modos de conexão do app de escrita (token de longa duração ou integração privada), configurados na própria instalação.

Destinos de lead do CRM (webhooks)

No CRM, destinos de lead (/v1/destinos na API do CRM) entregam cada lead capturado a um webhook seu, com url, segredo (opcional, para assinatura) e ativo. O segredo nunca volta nas respostas, só o indicador tem_segredo. Cada destino tem entregas (diagnóstico por tentativa, sem o conteúdo) e teste (POST /v1/destinos/{id}/testar). Para receber e validar, veja o guia de webhooks.

Zapier, n8n e Make

Não existem conectores nativos da Asender para Zapier, n8n ou Make. O que você pode fazer hoje, e funciona:

• Receber leads e eventos num fluxo do Zapier, n8n ou Make: crie um webhook (gatilho "Catch Hook") na ferramenta e use a URL dele como destino de lead do CRM ou como instalação do app API própria / CRM próprio.
• Ler dados da Asender numa automação: use o módulo HTTP da ferramenta com a API pública e uma chave de API de escopos de leitura (leads:read, conversions:read etc.).
• Enviar mensagens a partir da automação: chame as rotas /v1/*/send com uma chave de escopo de envio, de dentro do servidor da ferramenta.

Conectores nativos (com cadastro de conta e gatilhos prontos) são planejados.

Próximos passos

• Chaves de API e API Platform.
• Webhooks: assinatura e retentativas.
• Navegador: o pixel e o event_id que deduplicam com a conversão do servidor.
• Integrações: o mapa de todos os meios de integrar.