# 📖 Como Enviar UTMs para o Kwai via Webhook na Utmize

VISÃO GERAL

Para que a Utmize envie corretamente eventos de pixel para o Kwai, é fundamental
enviar os parâmetros UTM no formato esperado.
O backend valida e descompacta esses campos, e em caso de erro (especialmente em
modo de teste), retorna mensagens detalhadas para facilitar o ajuste da
integração.

--------------------------------------------------------------------------------


🎯 FORMATO ESPERADO DOS UTMS


UTM_SOURCE

 * Formato esperado:

  ad_delivery_platform|public_pixel_id

 * ad_delivery_platform: Nome da plataforma de entrega do anúncio (ex: kwai)

 * public_pixel_id: O identificador público do pixel cadastrado na Utmize (ex:
   P6840023f8572a0.15411956)

 * Exemplo válido:

  kwai|P6840023f8572a0.15411956


UTM_MEDIUM

 * Formato esperado:

  campaignId|adSETID|creativeId|click_id|pixel_id

 * campaignId: ID da campanha

 * adSETID: ID do conjunto de anúncios

 * creativeId: ID do criativo

 * click_id: ID do clique (usado para rastreamento e validação de teste)

 * pixel_id: ID do pixel (não é o public_id)

 * Exemplo válido:

  123456|654321|999888|CLIQUE123|PIXELID123

--------------------------------------------------------------------------------


🧪 RETORNOS EM MODO DE TESTE (TEST_FLAG: TRUE)

Quando você envia test_flag: true, o backend valida os campos e retorna
mensagens detalhadas caso algo esteja fora do padrão:

 * Se o utm_source estiver incorreto:

  {
    "message": "O teste foi identificado, mas o pixel não foi encontrado.",
    "notes": "Os dados do webhook foram armazenados, mas o evento não foi enviado porque o pixel não pôde ser localizado. No parâmetro `utm_source`, esperamos o formato `ad_delivery_platform|public_pixel_id`. Note que o `public_pixel_id` é diferente do `pixel_id`; ele é o identificador usado para localizar o pixel em nosso banco de dados. Por favor, envie parâmetros válidos de `ad_delivery_platform` e `public_pixel_id`."
  }


 * Se o utm_medium estiver incorreto ou faltar algum campo:

  {
    "message": "O teste foi identificado, mas o click_id não foi informado.",
    "notes": "Os dados do webhook foram armazenados, mas o evento não foi enviado porque o click_id não foi informado. Se estiver usando Kwai Ads, esperamos o seguinte formato em utm_medium: campaignId|adSETID|creativeId|click_id|pixel_id."
  }


 * Se tudo estiver correto:

  {
    "message": "Evento de teste enviado com sucesso para o Kwai.",
    "notes": "O payload do webhook foi armazenado e o evento foi enviado para o Kwai em modo de teste. Certifique-se de que o parâmetro `click_id` contém o valor correto de `test_id` para validação do rastreamento."
  }


--------------------------------------------------------------------------------


📋 RESUMO DOS CAMPOS

Campo

Obrigatório

Formato/Exemplo

utm_source

Sim

kwai|P6840023f8572a0.15411956

utm_medium

Sim

123456|654321|999888|CLIQUE123|PIXELID123

test_flag

Opcional

true/false

--------------------------------------------------------------------------------


🕵️‍♂️ ONDE ENCONTRAR O PUBLIC_PIXEL_ID?

 * No painel Utmize, na área de Pixels, copie o campo Public ID do pixel Kwai
   desejado.

--------------------------------------------------------------------------------


⚠️ OBSERVAÇÕES

 * O backend descompacta os campos automaticamente, separando por | e atribuindo
   cada parte ao seu respectivo campo.

 * Se algum campo estiver fora do padrão, o retorno de erro explicará exatamente
   o que está faltando ou incorreto.

 * Sempre utilize o formato exato para garantir o rastreamento correto e
   facilitar a homologação.

--------------------------------------------------------------------------------


🆘 SUPORTE

Em caso de dúvidas, envie o payload de teste e a resposta recebida para o
suporte Utmize.
Assim, nossa equipe pode ajudar a ajustar rapidamente sua integração!

--------------------------------------------------------------------------------

Seguindo este padrão, sua integração com o Kwai via Utmize será validada e
rastreada corretamente!