Como integrar uma plataforma não listada na Utmize?

�� Visão Geral

O webhook custom permite integrar plataformas personalizadas à UTMIZE para receber dados de conversões e pagamentos. O sistema utiliza autenticação via Bearer Token e processa automaticamente os dados recebidos.

�� Autenticação

Header Obrigatório

Authorization: Bearer {seu_token}

Como Obter o Token

1. Acesse seu Dashboard na UTMIZE

2. Crie uma integração API.

3. Crie uma nova credencial com um nome

4. O sistema gerará automaticamente um token único

5. Use este token no header Authorization

�� Endpoint

POST /api/webhook/{dashboard_id}/custom?product_id={product_id_da_utmize}

Exemplo:

POST /api/webhook/D6840023f8572a0.15411956/custom?product_id=40028922

�� Estrutura do Payload

Campos Obrigatórios

Campos Opcionais

Campos UTM (Opcionais)

�� Exemplo Completo

Request

curl -X POST "https://utmize.com.br/api/webhook/D6840023f8572a0.15411956/custom?product_id=40028922" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu_token_aqui" \
  -d '{
    "plataform": "minha_plataforma",
    "external_id": "order_123456",
    "product_name": "Produto Premium",
    "payment_status": "approved",
    "payment_method": "credit_card",
    "value": 9970,
    "tax": 500,
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "blackfriday",
    "utm_term": "desconto",
    "utm_content": "banner_topo",
    "test_flag": false
  }'

Response de Sucesso

{
  "message": "Dados armazenados com sucesso"
}

Response de Erro

{
  "message": "Payment status not found"
}

🔍 Processamento Automático

Normalização de Valores

• O value é automaticamente dividido por 100 (de centavos para reais)

• Exemplo: 9970 → 99.70

Processamento de UTMs

• Os parâmetros UTM são opcionais mas altamente recomendados

• Quanto mais UTMs enviados, mais detalhado será o rastreamento

• Os UTMs são armazenados para análise de performance

Test Flag

• Use test_flag: true para testes sem impactar relatórios reais

• Dados de teste são marcados e podem ser filtrados no dashboard

🚨 Códigos de Status

�� Integração com Pixels

Envio Automático de Eventos

Se você incluir parâmetros UTM específicos, o sistema pode enviar automaticamente eventos para pixels configurados:

Para Kwai Ads:

utm_source: "kwai|public_pixel_id"
utm_medium: "campaignId|adSETID|creativeId|click_id|pixel_id"

Para Facebook Ads:

utm_source: "FB"
utm_campaign: "campaignName|campaignId"
utm_medium: "adsetName|adsetId"
utm_content: "adName|adId"

�� Testando a Integração

1. Teste Básico

{
  "payment_status": "approved",
  "payment_method": "credit_card",
  "value": 1000,
  "test_flag": true
}

2. Teste com UTMs

{
  "payment_status": "approved",
  "payment_method": "credit_card",
  "value": 1000,
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "teste",
  "test_flag": true
}

3. Teste com Pixel (Kwai)

{
  "payment_status": "approved",
  "payment_method": "credit_card",
  "value": 1000,
  "utm_source": "kwai|P6840023f8572a0.15411956",
  "utm_medium": "campaign123|adset456|ad789|click_id_123|pixel_456",
  "test_flag": true
}

🔧 Configuração no Dashboard

1. Acesse seu Dashboard

2. Vá para Integrações

3. Selecione "Custom"

4. Crie uma nova credencial

5. Copie o token gerado

6. Use o token no header Authorization

📈 Monitoramento

• Todos os webhooks são logados automaticamente

• Dados de teste são marcados e podem ser filtrados

• Erros são registrados para debugging

• Payloads são salvos para auditoria

🆘 Suporte

Em caso de dúvidas ou problemas:

• Verifique se o token está correto no header

• Confirme se todos os campos obrigatórios estão presentes

• Use test_flag: true para testes sem impacto

• Consulte os logs para debugging

Nota: Esta documentação é específica para o webhook custom. Para tracking de eventos com UTMs, consulte a documentação da API de Pixel (/api/send-event).