UTMs e integrações

Saiba qual anúncio trouxe cada venda. A SuyPay guarda as UTMs de cada cobrança e avisa as suas ferramentas de anúncio a cada mudança, seja qual for a conta que recebeu o dinheiro.

UTMs na cobrança

Mande tracking ao criar a cobrança:

{
  "method": "pix",
  "amount": 9700,
  "customer": { "name": "Ana Lima", "email": "ana@exemplo.com" },
  "tracking": { "utm_source": "FB", "utm_campaign": "BLACK|1203", "utm_medium": "CONJUNTO|88", "utm_content": "VIDEO_2", "fbclid": "IwAR..." }
}

Campo
`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`	UTMs do anúncio
`src`, `sck`	parâmetros de rastreio usados pela Utmify e por plataformas de infoproduto
`fbclid`, `gclid`, `ttclid`	id do clique no anúncio (Meta, Google, TikTok)
`fbp`, `fbc`	cookies `_fbp` e `_fbc` do pixel da Meta, quando você tem
`ttp`	cookie `_ttp` do pixel do TikTok, quando você tem

Cada valor tem até 500 letras. A cobrança devolve o que foi guardado em tracking.

No link de pagamento

No anúncio, coloque as UTMs no próprio link de pagamento:

https://checkout.SEU-DOMINIO/pay_3kXy...?t=...&utm_source=FB&utm_campaign=BLACK

Quando o cliente escolhe como pagar, a SuyPay guarda as UTMs do endereço, além do IP e do navegador dele, que as ferramentas usam para achar o clique. Se você mandou tracking ao criar o link, o que você mandou vale mais.

Do seu site até o link

Muitas vezes o anúncio leva o cliente para o seu site, e só depois ele clica no link de pagamento. Para as UTMs não se perderem no caminho, cole esta linha no <head> do seu site (em Integrações → UTMs do seu site o painel mostra a linha pronta):

<script src="https://www.suypay.com/utm.js" defer></script>

O script:

guarda as UTMs e os ids de clique da visita no navegador do cliente, por 30 dias, só no seu site. Uma visita nova com UTMs troca as antigas (vale o último clique, como nas plataformas de anúncio);
coloca esses valores, mais os cookies _fbp, _fbc e _ttp dos pixels do seu site, em todo link para a página de pagamento da SuyPay, inclusive botões que aparecem depois;
não cria cookie e não manda nada para lugar nenhum: os valores só viajam no próprio link.

Se o link já tem uma UTM, a do link vale. Para usar no seu código, por exemplo num redirecionamento: SuyPay.withUtm(url) devolve o endereço com as UTMs, e SuyPay.utm() devolve os valores. Com domínio de pagamento próprio, avise o script: data-hosts="pagar.minhaloja.com". Para outro prazo, data-days="7".

Conte na política de privacidade do seu site que ele guarda a origem da visita para medir os anúncios.

Nas assinaturas

tracking na criação da assinatura vai para todos os ciclos, no Pix Automático e no cartão.

Integrações

Em Integrações, no painel, conecte a ferramenta e escolha se ela recebe vendas reais, de teste ou as duas.

Ferramenta	O que recebe	Quando
Utmify	o pedido com as UTMs, o valor, a taxa e o que sobra para você	ao gerar (Pix ou boleto esperando), ao aprovar, recusar, cancelar e devolver. Sempre o mesmo pedido, atualizado
Meta (Facebook e Instagram)	uma compra no seu pixel, pela API de Conversões, com e-mail e celular cifrados	ao aprovar
TikTok	uma compra (`CompletePayment`) no seu pixel, pela Events API, com e-mail e celular cifrados	ao aprovar

Utmify: gere a credencial em Integrações › Webhooks › Credenciais de API. Vendas de teste vão como teste e não aparecem nos relatórios. A Utmify pede o e-mail do cliente e não aceita vendas com mais de 7 dias (45 dias para devoluções). O que não cabe nisso aparece como "não enviado", com o motivo.

Meta: no Gerenciador de Eventos, abra o pixel e vá em Configurações › API de Conversões para gerar o token. A compra vai com o id da cobrança como event_id. Se o seu site também dispara Purchase no navegador com o mesmo id, a Meta conta uma vez só. Para vendas de teste, informe o código de teste da aba Eventos de teste: sem ele, a SuyPay não envia, para não sujar os relatórios.

TikTok: no TikTok Ads Manager, abra Ferramentas › Gerenciador de eventos, escolha o pixel e vá em Configurações › Events API para gerar o token. O código do pixel fica no topo da mesma página. A compra vai com o id da cobrança como event_id, com o ttclid do anúncio e o cookie _ttp, quando houver. Para vendas de teste, informe o código de teste da aba Eventos de teste.

"Cifrados" quer dizer resumo SHA-256, que é o que a Meta e o TikTok pedem: eles comparam o resumo com os da própria base, sem receber o e-mail ou o celular em texto.

Envios e novas tentativas

Abra a integração para ver os últimos envios e a resposta da ferramenta. Se ela estiver fora do ar, a SuyPay tenta de novo em 1, 5 e 30 minutos, depois em 2, 6, 12 e 24 horas. Uma recusa por dado errado (4xx) não é repetida. Enviar teste manda a última venda aprovada como teste.

As credenciais ficam criptografadas e não voltam pela API: aparecem só os 4 últimos caracteres.

Pela API: GET /v1/integration-kinds, GET/POST /v1/integrations, PATCH/DELETE /v1/integrations/{id}, GET /v1/integrations/{id}/deliveries e POST /v1/integrations/{id}/test, com chave completa.