> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Configurar pixel de conversão
> Conecte seu Pixel da Meta e deixe a Chargefy enviar cada etapa do checkout pela Meta Conversions API — da abertura à venda aprovada, incluindo pagamentos recusados e checkouts expirados —, direto de servidor para servidor.
Quando alguém compra vindo de um anúncio, a Meta precisa saber que a venda
aconteceu. É assim que ela aprende quem é bom comprador e passa a mostrar seu
anúncio para mais gente parecida. Sem esse retorno, a campanha vai piorando
sozinha — você continua pagando por cliques, mas o algoritmo está no escuro.
O jeito tradicional de contar isso é o Pixel no navegador do comprador. Ele
falha bastante: bloqueador de anúncio, restrição de privacidade do iPhone, aba
fechada antes da página carregar. E falha de vez no Brasil, onde muita gente
paga por Pix ou boleto — o dinheiro cai horas ou dias depois, com o comprador
longe do site.
A Chargefy resolve isso enviando os eventos pela **Meta Conversions API**, do
nosso servidor direto para o seu conjunto de dados, sem depender do navegador de
ninguém. Você conecta seu Pixel uma vez e a Chargefy passa a enviar cada marco
do funil conforme ele acontece de verdade no seu negócio.
**Isso não substitui o Pixel do seu site**
O Pixel instalado nas suas páginas continua útil para o que acontece antes da
compra: visitas, visualizações de produto, navegação. A Chargefy cobre a parte
que ela enxerga — o checkout e o pagamento — e é justamente a parte que o
navegador mais erra.
## O que a Chargefy envia
O funil inteiro que ela enxerga — da abertura do checkout até o carrinho que
morreu sem pagar. Todos os eventos saem do servidor da Chargefy no instante em
que acontecem de verdade.
| Momento no seu negócio | Evento na Conversions API |
| -------------------------------------------------- | -------------------------- |
| O comprador abriu a página de checkout | `InitiateCheckout` |
| O comprador enviou os dados de pagamento | `AddPaymentInfo` |
| Uma compra avulsa foi aprovada | `Purchase` |
| Uma assinatura começou cobrando na hora | `Subscribe` |
| Uma assinatura começou com período de teste grátis | `StartTrial` |
| O pagamento foi recusado | `Chargefy_PaymentFailed` |
| O checkout expirou sem pagamento | `Chargefy_CheckoutExpired` |
O mapeamento é fixo e igual para todas as contas. Ele não é configurável de
propósito: um mapeamento errado estraga a otimização da campanha, e isso é caro
demais para virar um botão que se erra sem perceber.
**Por que dois nomes começam com `Chargefy_`**
A lista de standard events da Meta não cobre pagamento recusado nem checkout
expirado. Esses dois viajam como **custom events**, com nome próprio.
Na prática a diferença é: standard event alimenta a otimização automática da
campanha; custom event serve para você montar **público personalizado** e criar
**conversão personalizada**.
O namespace resolve uma pergunta que o Gerenciador de Eventos não responde. Ele
já mostra quais eventos são custom, mas nunca mostra **quem mandou** — e o seu
conjunto de dados costuma receber de mais de uma fonte: o Pixel do seu site, a
Chargefy, e o que mais você tiver ligado. Com o prefixo, você bate o olho e sabe
a origem; sem ele, um nome genérico se fundiria em silêncio com o de outra
ferramenta e o número deixaria de significar alguma coisa.
### Quando cada um dispara
Dispara no primeiro carregamento da página de checkout, antes de qualquer
tentativa de pagamento. É o sinal de intenção: essa pessoa clicou no
anúncio, chegou até o formulário e está considerando comprar.
Serve para a Meta construir públicos de remarketing e entender quem chega
perto da compra, mesmo sem fechar.
Dispara quando o comprador conclui o formulário e envia o pagamento — antes
de saber se foi aprovado.
É o evento mais importante do meio do funil no Brasil, porque é ele que
marca **o Pix e o boleto no momento em que o código é gerado**. Antes, entre
a abertura do checkout e a aprovação existia um buraco de horas ou dias em
que a Meta não recebia nada — e, se o boleto nunca fosse pago, nada mesmo.
Agora ela recebe na hora o sinal de quem realmente chegou até o fim.
Vale também para a qualidade da correspondência: nesse momento o comprador
já preencheu e-mail, nome, telefone e endereço, então o evento sai com o
conjunto completo de dados de identificação — bem mais do que o
`InitiateCheckout` consegue carregar.
Sai uma vez por checkout. Se o comprador tentar de novo com outro cartão,
ele não "preencheu os dados" duas vezes — e a Meta não recebe duas.
Dispara quando o pagamento é **efetivamente aprovado**, não quando o
comprador clica em "pagar".
A diferença importa muito no Brasil. No cartão, os dois momentos são quase
simultâneos. No Pix e no boleto, não: o comprador gera o código e some. Se o
Pix for pago três horas depois, o `Purchase` sai três horas depois. Se o
boleto for pago no terceiro dia, sai no terceiro dia. A Meta recebe a venda
quando ela virou dinheiro, e não quando alguém demonstrou intenção de pagar.
Dispara quando um checkout de assinatura é aprovado e a cobrança acontece já
na entrada, sem período de teste.
Dispara quando um checkout de assinatura é aprovado e a assinatura entra em
período de teste. Como não houve pagamento ainda, o valor enviado é zero — o
que é correto: você não quer que a Meta otimize para receita que ainda não
existe.
Dispara a cada tentativa de pagamento recusada, com o valor que teria sido
cobrado.
Serve para montar o público de quem **quis comprar e não conseguiu** —
cartão recusado, limite, dado errado. É gente que já decidiu, e costuma
responder muito melhor a uma campanha de recuperação do que um público frio.
Dispara quando a sessão de checkout chega ao fim do prazo sem pagamento,
com o valor que ficou na mesa. É o carrinho abandonado na prática.
Cobre os dois casos: quem abriu e foi embora, e quem gerou o Pix ou o
boleto e nunca pagou. Checkout concluído nunca expira, então uma venda
aprovada jamais aparece aqui.
O nome fala de **expiração**, não de abandono, porque é isso que a Chargefy
de fato observa: um prazo que venceu. Se o comprador desistiu, mudou de
ideia ou só se distraiu, quem sabe é você — não nós.
Só existe evento para o que a Chargefy observa. Ela não inventa eventos de
visita de página ou visualização de produto, porque essas coisas acontecem no
seu site, não no checkout dela.
## O que vai junto com cada evento
Além do nome do evento, a Chargefy manda:
* **O valor e a moeda da compra**, para a Meta saber quanto cada venda rendeu e
otimizar por receita, não só por quantidade;
* **Os produtos comprados** com quantidade e preço unitário;
* **Os dados de identificação do comprador** (`user_data`), para a Meta ligar a
venda à pessoa que viu o anúncio: e-mail, telefone, nome, cidade, estado, CEP
e país;
* **O clique do anúncio** (`fbc`), quando o comprador chegou por um link com
`fbclid`, além do `fbp` quando o Pixel do seu site já tiver marcado aquele
navegador.
**Os dados de identificação são hasheados antes de sair**
E-mail, telefone, nome e endereço nunca saem da Chargefy em texto legível: cada
um vira um hash SHA-256 antes do envio, como a Meta exige para os campos de
`user_data`. Ela compara esse hash com o da base dela e reconhece a pessoa, mas
não consegue ler o dado original.
IP e user agent seguem em claro — a Meta proíbe hashear esses dois, porque são
justamente o que ela usa para casar o evento com a sessão de navegação.
Telefone brasileiro recebe tratamento próprio: DDD, nono dígito e código do
país são normalizados para o formato que a Meta espera. Um número salvo como
`(11) 91234-5678` e outro salvo como `+55 11 91234-5678` chegam do mesmo jeito,
e por isso são reconhecidos como a mesma pessoa.
## Onde configurar
A conexão fica em **Configurações → Marketing**, no Dashboard.
Você precisa do **Pixel ID** (o ID do conjunto de dados) e de um **token de
acesso da Conversions API**, os dois no Gerenciador de Eventos da Meta. O
próprio formulário da Chargefy tem o caminho escrito e um link direto para
cada um.
O nome é só para você se achar na lista. Em seguida escolha se este Pixel
recebe as vendas de **todos os links de pagamento** ou apenas de **links
específicos** — útil quando você roda campanhas separadas e quer cada uma no
seu próprio Pixel.
Use o modo de teste (logo abaixo) para confirmar que a conexão funciona antes
de deixar os eventos reais entrarem na conta.
A própria tela de Marketing lista os eventos enviados, com status de cada
um. É onde você confere se algo falhou.
**O envio começa a valer a partir da conexão**
Checkouts abertos **antes** de você conectar o Pixel ficam de fora, inclusive se
o pagamento deles for aprovado depois. Isso é proposital: uma venda que começou
sem o Pixel conectado não tem como ser atribuída corretamente, e mandá-la assim
sujaria seus relatórios em vez de ajudar.
## Em que o alcance se aplica
O alcance de um Pixel é definido por **link de pagamento**, e você tem duas
opções:
| Opção | O que entra |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| **Todos os links de pagamento** | Toda venda da organização, incluindo checkouts criados pela API, que nascem sem link. |
| **Links específicos** | Só as vendas dos links que você selecionar. |
Vale destacar o que a primeira opção cobre: se o seu sistema cria checkouts pela
API em vez de usar link de pagamento, essas vendas **entram** no alcance amplo.
Elas ficariam de fora se você escolhesse links específicos, simplesmente porque
não passam por link nenhum.
**Um detalhe que evita dor de cabeça**
O alcance é resolvido e **congelado** no momento em que o comprador abre o
checkout. Se um boleto for pago três dias depois, a venda vai para o mesmo
Pixel que recebeu a abertura — mesmo que nesse meio tempo você tenha trocado a
configuração. Abertura e compra sempre contam para o mesmo lugar.
## Modo de teste
Antes de deixar os eventos entrarem para valer, dá para conferir se a conexão
está de pé.
No Gerenciador de Eventos da Meta existe uma aba de eventos de teste que gera um
código. Cole esse código no campo de teste da Chargefy: a partir daí, cada
evento enviado aparece nessa aba em segundos, e você vê chegando exatamente o
que a Chargefy mandou.
Também existe uma ação de **enviar teste** na lista de destinos, que dispara um
`Chargefy_ConnectionTest` sozinho, sem precisar de uma venda de verdade. Esse
evento é inofensivo de propósito — ele não se parece com uma compra, então não
contamina a otimização da sua campanha nem inventa receita nos seus relatórios.
Terminou de validar? Volte no destino e **apague o código de teste**. Ele é
para conferência, não para operação do dia a dia.
## O que acontece quando algo dá errado
A entrega é garantida, não é "tentou uma vez e desistiu".
Se a Conversions API estiver fora do ar ou recusar por rate limit, a Chargefy
tenta de novo, espaçando as tentativas ao longo de cerca de três dias.
Esse limite existe por um motivo: a Meta recusa qualquer evento com mais de sete
dias de idade, e a régua de tentativas foi desenhada para caber dentro dessa
janela até no pior caso — um boleto confirmado no terceiro dia, que ainda
precisa de margem para as tentativas.
Cada envio aparece na lista com um destes estados:
| Estado | O que significa |
| -------------- | -------------------------------------------------------------------------------------------------- |
| **Pendente** | Na fila, ainda vai sair. |
| **Enviado** | A Meta recebeu e confirmou. |
| **Falhou** | Deu erro e vai ser tentado de novo. |
| **Descartado** | Acabaram as tentativas dentro da janela de sete dias. |
| **Ignorado** | Não chegou a ser tentado — normalmente porque o evento já estava velho demais para a Meta aceitar. |
### Token vencido pausa sozinho
Se a Meta responder que o token não vale mais — foi revogado, expirou ou perdeu
permissão —, a Chargefy marca a conexão como inválida e **para de tentar**. Isso evita queimar tentativas contra uma credencial morta e deixa
claro na tela que o problema é seu token, não a integração.
Para voltar a funcionar, gere um token novo no Gerenciador de Eventos e use a
ação de **substituir token**. O token atual nunca é exibido de novo, nem para
você — só os quatro últimos caracteres aparecem, para conferência.
## A mesma venda nunca é contada duas vezes
Uma compra pode ser registrada por mais de um caminho dentro da Chargefy — a
confirmação do checkout e o aviso do banco, por exemplo, podem chegar quase
juntos. Mesmo assim, a Meta recebe **um** evento.
O `event_id` que a Chargefy manda junto de cada evento vem da própria venda, não
do registro interno que disparou o envio. Então os dois caminhos chegam no mesmo
identificador, e o segundo é descartado antes de sair. A deduplicação da Meta
ainda roda por cima disso, como segunda rede de proteção.
É o mesmo `event_id` que permite a deduplicação com o Pixel do seu site: se um
dia os dois enviarem o mesmo evento, a Meta conta uma vez só.
Na prática: seus relatórios não inflam sozinhos.
## Perguntas frequentes
Sim, nas primeiras horas. Os eventos só existem quando houver movimento
novo: um checkout aberto depois da conexão. Vendas anteriores não entram
retroativamente.
Se já houve movimento e mesmo assim não apareceu nada, confira o status da
conexão na lista — se estiver como credencial inválida, o token precisa ser
substituído.
Pode. Cada Pixel é um destino separado, com seu próprio alcance. Dá para ter
um Pixel recebendo tudo e outro recebendo só um link específico, por exemplo —
a mesma venda pode alimentar os dois.
Não. Uma conexão pertence ao ambiente em que foi criada e só recebe vendas
dele. Vendas de teste nunca chegam ao Pixel de produção.
Pode. A ação de pausar interrompe os envios e mantém o Pixel, o alcance e o
token guardados. Ao retomar, volta de onde parou — mas o que aconteceu durante
a pausa não é enviado retroativamente.
O evento sai na entrada da assinatura: `Subscribe` quando há cobrança
imediata, `StartTrial` quando começa em teste grátis. As renovações dos meses
seguintes não geram evento novo — a Meta otimiza para a aquisição, que é o que
o anúncio de fato causou.
Porque ele não ajudaria. Um comprador digitando um cupom não diz nada sobre
intenção de compra que o `AddPaymentInfo` já não diga melhor — e o cupom
acontece antes, com menos dados de identificação junto.
Enviar os dois só encheria o seu Gerenciador de Eventos com um evento que
descreve o mesmo público. A Chargefy registra esse marco internamente, para
os seus relatórios de checkout, mas não o encaminha para a Meta. Se um dia
isso mudar, ele chega como `Chargefy_CheckoutDiscountApplied`.
## Relacionado
O alcance do Pixel é definido por link de pagamento.
Onde a campanha é capturada e o checkout acontece.
Preserve os parâmetros de campanha da sua landing page até o checkout.
Como funcionam teste grátis e cobrança na entrada.