> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sinnu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt.
> A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais.
> A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout.
> Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade.
> Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved.
> Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno.
> Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API.

# Rastreie a origem das vendas

> Ligue os pixels de Meta, TikTok e Google Ads ao checkout e saiba de qual campanha veio cada venda.

Com um pixel cadastrado e ligado no link, o checkout avisa a plataforma de anúncios da visita, do início da compra e da compra. Na Meta e no TikTok a compra também sai pelo servidor da sinnu, então o Pix pago depois de fechar a página conta. Em Transações, cada venda mostra de onde veio.

Você precisa de acesso a **Configurações › Rastreamento** no painel. Cadastrar, editar, testar e apagar um pixel exige o papel de Titular ou Administrador da empresa.

**1. Cadastre o pixel**

Em **Configurações › Rastreamento**, use **Novo pixel** e escolha a plataforma: Meta, TikTok ou Google Ads. Dê um nome e informe o identificador.

| Plataforma | Identificador | Para o envio pelo servidor |
| - | - | - |
| Meta | **ID do pixel** | **Token da API de Conversões**, obrigatório ao criar |
| TikTok | **ID do pixel** | **Token da Events API**, obrigatório ao criar |
| Google Ads | **ID de conversão** (`AW-123456789`) e **Rótulo da conversão de compra** | Ainda não disponível. O Google Ads recebe só pelo navegador |

O token fica cifrado e nunca aparece de novo. Para trocar, preencha o campo outra vez.

**2. Teste antes de usar**

Na Meta e no TikTok, preencha **Código de evento de teste** com o código da aba "Eventos de teste" da plataforma. Enquanto ele estiver preenchido, o Pix gerado e a compra enviados pelo servidor, inclusive de vendas reais, vão para essa aba e não contam nas campanhas. Os eventos do navegador não levam o código e seguem normalmente. Use **Testar envio** no card do pixel, confira o evento na plataforma e apague o código.

No Google Ads, **Testar envio** fica indisponível enquanto o envio pelo servidor não estiver liberado. Confira a conversão no Tag Assistant do Google.

**3. Ligue o pixel no link**

No editor do link, o card **Rastreamento** lista os pixels da empresa. Marque os que valem para aquele link. Um pixel ativo marcado como **Padrão nos links novos** já vem selecionado em todo link criado pelo painel ou pela API.

Sem pixel ligado, o checkout do link não carrega o script do Meta, do TikTok nem do Google Ads.

**4. Compartilhe com a campanha marcada**

Em um link salvo, use **Compartilhar**. O painel **Um link para cada canal** copia a URL com os parâmetros de campanha de cada canal:

| Canal | Parâmetros |
| - | - |
| Meta Ads | `utm_source=meta&utm_medium=paid&utm_campaign={{campaign.name}}` |
| TikTok Ads | `utm_source=tiktok&utm_medium=paid&utm_campaign=__CAMPAIGN_NAME__` |
| WhatsApp | `utm_source=whatsapp&utm_medium=social` |
| Bio do Instagram | `utm_source=instagram&utm_medium=bio` |
| Link limpo | nenhum; a venda aparece como "Direto" |

Os marcadores `{{campaign.name}}` e `__CAMPAIGN_NAME__` são trocados pela própria plataforma pelo nome da campanha. **Outro canal…** aceita `utm_source`, `utm_medium` e `utm_campaign` digitados.

## O que o checkout envia

Cada pixel ligado no link recebe os próprios eventos. Os eventos de Pix gerado e de compra levam um identificador único por pagamento, que o navegador e o servidor repetem; a plataforma usa esse identificador para contar a venda uma vez só.

| Momento | Meta | TikTok | Google Ads |
| - | - | - | - |
| Abrir o checkout | `PageView` e `InitiateCheckout` | `page` e `InitiateCheckout` | Visita da tag |
| Escolher Pix ou cartão | `AddPaymentInfo` | `AddPaymentInfo` | Nada |
| Pix gerado | `PixGerado` (evento personalizado) | `PlaceAnOrder` | Conversão no **Rótulo do Pix gerado**, quando informado |
| Pagamento aprovado | `Purchase` | `Purchase` | Conversão no **Rótulo da conversão de compra** |

No início da compra e na escolha do pagamento vai o preço do link (no link de valor livre, o mínimo); no Pix gerado e na compra, o valor bruto cobrado. Sempre em reais, com `BRL`. A compra só dispara com o pagamento confirmado; cartão autorizado ou em processamento não conta.

Com a opção **Pix gerado conta como conversão** ligada no pixel, o Pix gerado já sai como `Purchase` (ou como conversão de compra no Google Ads) e o pagamento do Pix não dispara uma segunda compra.

## O envio pelo servidor

Na Meta e no TikTok, o Pix gerado e a compra também saem do servidor da sinnu, com o mesmo identificador do navegador. É isso que faz a venda contar quando o comprador paga o Pix com a página fechada. Estorno e chargeback não geram evento.

O servidor envia:

| Dado | Como vai |
| - | - |
| E-mail e telefone do comprador | Em hash SHA-256. O telefone recebe o DDI 55. |
| Nome do comprador | Em hash SHA-256, só para a Meta |
| Identificador do cliente | Em hash SHA-256 |
| IP e navegador do comprador | Em claro, como as plataformas pedem para a correspondência |
| Identificador de clique (`fbclid` na Meta, dentro do cookie `fbc`; `ttclid` no TikTok) e cookies da plataforma | Em claro |
| Valor, moeda, pedido e título do link | Em claro |
| Endereço do checkout do link | Em claro |
| CPF ou CNPJ | **Nunca** |

Se a plataforma ficar fora do ar ou pedir para esperar, o envio é tentado de novo até três vezes: depois de 1 minuto, 10 minutos e 1 hora. Uma recusa da plataforma, como token inválido, fica como falhou na hora. A plataforma aceita eventos de até 7 dias; uma venda paga há mais tempo não é enviada.

> [!NOTE]
>
> O envio pelo servidor para o Google Ads depende de uma credencial que a sinnu ainda não habilitou. Até lá, a conversão do Google Ads sai só pelo navegador e conta quando o pagamento é confirmado com a página aberta.

## De onde veio cada venda

Em **Transações**, a coluna **Origem** classifica a venda pelo `utm_source` da URL que o comprador abriu:

| Origem | Valores aceitos em `utm_source` |
| - | - |
| Meta | `meta`, `meta_ads`, `metaads`, `facebook`, `fb` |
| Instagram | `instagram`, `ig` |
| TikTok | `tiktok`, `tik_tok`, `tt` |
| Google | `google`, `google_ads`, `googleads`, `adwords`, `gads` |
| WhatsApp | `whatsapp`, `wa`, `wpp`, `zap` |
| Direto | sem `utm_source` |
| Outra | qualquer outro valor, exibido como veio |

O checkout lê `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `src`, `sck`, `fbclid`, `gclid`, `gbraid`, `wbraid` e `ttclid`. A primeira visita com `utm_*` vence dentro da mesma aba.

No detalhe da venda, o card **De onde veio** mostra canal, campanha, meio, conteúdo e identificador do clique. O card **Conversão enviada** mostra cada envio do servidor: na fila, enviado, falhou ou não enviado. Um envio que falhou pode ser reenviado em **Reenviar**, dentro dos 7 dias, por quem gerencia integrações.

## Privacidade

* O checkout só carrega o script do Meta, do TikTok ou do Google Ads em link com pixel ligado.
* Dados pessoais de atribuição (IP, navegador, identificadores de clique, cookies, página de entrada e site de origem) só são guardados quando o link tem pixel ativo, e são apagados depois de 30 dias. Os parâmetros de campanha ficam na venda.
* E-mail, telefone e nome saem em hash. CPF e CNPJ não saem.
* O token do pixel é cifrado e não aparece na API nem no checkout.

## Pela API

O link criado por [`POST /api/payment-links`](https://docs.sinnu.com.br/api/links/criar) recebe os pixels ativos marcados como **Padrão nos links novos** da empresa. A escolha de pixels por link e o cadastro dos pixels ficam no painel. A origem da venda ainda não é exposta na [API de transações](https://docs.sinnu.com.br/api/transacoes/listar.md).

Para marcar o pedido do seu sistema em cada venda, use `reference` ao [abrir o checkout](https://docs.sinnu.com.br/guias/checkout.md#pedido-de-cada-venda). Parâmetros de campanha e `reference` convivem na mesma URL.

## Se o evento não chegar

> [accordion] A plataforma não mostra nada
>
> Confira se o pixel está **Ativo** e marcado no card **Rastreamento** do link. Use **Testar envio** com o código de evento de teste e procure o evento na aba de teste da plataforma.

> [accordion] A compra conta duas vezes
>
> No Google Ads, use a mesma ação de conversão no rótulo de compra e no envio pelo servidor, quando ele estiver disponível. Na Meta e no TikTok, a plataforma desduplica pelo identificador do pagamento; confira se o evento do navegador e o do servidor aparecem com o mesmo identificador.

> [accordion] A venda aparece como Direto
>
> A URL que o comprador abriu não tinha `utm_source`. Um clique só com `fbclid` ou `gclid` também aparece como Direto. Use os links de **Compartilhar**, que já levam a origem.

> [accordion] O envio pelo servidor falhou
>
> Abra a venda e use **Reenviar** no card **Conversão enviada**. O reenvio vale para envios que falharam em vendas de até 7 dias. Token expirado ou trocado na plataforma é a causa mais comum: atualize o token no pixel.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.