Problemas Comuns

Guia completo para diagnosticar e resolver problemas com a integração nativa UTMify do Rise Bots.

Checklist de verificação

Antes de investigar problemas específicos, verifique cada item desta lista:

Protocolo de teste

Siga estes 4 passos para testar o fluxo completo de ponta a ponta:

Cenários de erro

Token inválido ao ativar

Sintoma: Ao ligar o switch, aparece erro "Token UTMify inválido ou API indisponível".

Soluções:

1. Verifique se o token foi copiado completo (sem espaços no início ou fim)
2. No painel do UTMify, confirme que a credencial está ativa (não expirada ou deletada)
3. Gere uma nova credencial no UTMify e use o botão de editar (ícone de lápis) no card para atualizar
4. Verifique se a API do UTMify está no ar — pode ser uma indisponibilidade temporária

Vendas não aparecem no UTMify

Sintoma: A integração está ativa, pagamentos estão sendo feitos, mas o UTMify não mostra nenhuma venda.

Verifique:

1. A integração está com o switch ligado? (badge "Ativo" no card)
2. O token ainda é válido? Desative e reative o switch para testar
3. No UTMify, verifique se está olhando o período correto (filtro de datas)
4. O pagamento tem menos de 7 dias? O UTMify rejeita pedidos mais antigos

UTMs não aparecem no UTMify (venda sem dados de campanha)

Sintoma: As vendas aparecem no UTMify, mas sem dados de campanha (utm_source, utm_campaign vazio).

Causas possíveis:

1. Link sem redirecionador: O cliente acessou diretamente pelo t.me/SeuBot em vez do /go/{short_id}?utm_source=.... Sem o redirecionador, os UTMs não são capturados.

2. UTMs não estão na URL: Os parâmetros UTM precisam estar na query string do link redirecionador. Verifique se a URL do anúncio contém ?utm_source=....

3. Macros não foram substituídas: Se os valores UTM aparecem como {{campaign.name}} literal (em vez do nome da campanha), a plataforma de ads não substituiu as macros. Verifique se a URL está configurada no nível correto do anúncio.

Solução: Use sempre os links gerados pelo UTM Generator do Rise Bots como URL de destino nos seus anúncios.

Redirecionador retorna 404

Sintoma: Ao acessar /go/{short_id}, retorna erro "Bot não encontrado".

Causas:

1. O short_id está incorreto — verifique o código do bot
2. O bot foi deletado ou desativado
3. A URL tem caracteres extras ou espaços

Vendas duplicadas no UTMify

Sintoma: A mesma venda aparece duas vezes no UTMify.

Causa: Você pode ter configurado outra integração (pixel, webhook externo) que também envia dados para o UTMify, além da integração nativa do Rise Bots.

Solução: Use apenas uma forma de enviar dados ao UTMify. A integração nativa do Rise Bots já cuida de tudo — desative qualquer pixel ou webhook externo duplicado.

Status incorreto no UTMify

Sintoma: O pedido aparece como waiting_payment mas o cliente já pagou.

Possíveis causas:

1. O pagamento pode ter sido processado antes da integração ser ativada — nesse caso o update de status não foi enviado
2. Delay na propagação — aguarde alguns minutos e atualize o painel

Trocar o token da API

Se você precisa trocar o token (expirou, gerou um novo, etc.):

Deletar e recriar

Se nada funcionar, você pode deletar a integração (botão de lixeira) e criar uma nova com um token fresco. Isso não afeta dados históricos no UTMify — os pedidos já enviados permanecem lá.

Otimização de campanhas

Depois que o rastreamento está funcionando, use os dados do UTMify para otimizar seus investimentos em ads.

Métricas para acompanhar

Dicas de otimização

1. Rode por 3-5 dias antes de tirar conclusões — dados de 1 dia podem ser enganosos
2. Compare plataformas: use o utm_source para ver se Meta, TikTok ou Google traz mais vendas para o seu nicho
3. Identifique criativos vencedores: o utm_content mostra qual anúncio converte — escale os bons e pause os ruins
4. Monitore posicionamentos: o utm_term (ou utm_medium) revela se stories, feed ou reels converte melhor
5. Acompanhe reembolsos: vendas com muitos reembolsos podem indicar problema com o produto ou público errado

FAQ — Perguntas frequentes

1. Preciso instalar algum pixel ou script no checkout?

Não. O Rise Bots tem integração nativa com o UTMify. Todos os dados são enviados automaticamente via API. Não é necessário instalar pixels, scripts ou usar ferramentas como Zapier ou Make.

2. Preciso configurar a integração para cada bot?

Não. A integração é por conta (usuário), não por bot. Ao ativar uma única integração com seu token do UTMify, todos os seus bots já enviam dados automaticamente.

3. O que acontece se eu não usar o redirecionador?

A venda será enviada ao UTMify, mas sem dados de campanha (utm_source, utm_campaign, etc. ficam vazios). A venda aparece como "orgânica" — sem atribuição a nenhuma campanha.

4. Posso usar links diretos do Telegram (t.me/SeuBot) com UTMs?

Não diretamente. O Telegram não repassa parâmetros de query string para o bot — ele só entende o parâmetro start. Por isso o redirecionador (/go/{short_id}) é necessário: ele captura os UTMs da URL antes de redirecionar para o Telegram.

5. O que é o salesCode que aparece no campo src do UTMify?

É um código de 8 caracteres aleatórios gerado pelo redirecionador. Ele conecta o clique no anúncio ao checkout e ao pagamento. É o "elo" que permite ao sistema saber que o cliente que pagou veio daquele anúncio específico.

6. E se o cliente acessar o link redirecionador mas só comprar dias depois?

O sistema funciona mesmo assim. Quando o cliente clica no redirecionador, o salesCode é salvo no Telegram (via ?start=). Quando ele comprar — mesmo dias depois — o checkout recupera os UTMs associados àquele salesCode da tabela redirect_clicks.

7. Os UTMs funcionam tanto no Mini App (Telegram) quanto na loja (browser)?

Sim. O checkout captura UTMs em ambos os fluxos. No Mini App, os UTMs são recuperados via salesCode (redirect_clicks). Na loja (browser), os UTMs podem vir diretamente da URL (/app/{short_id}?utm_source=...).

8. O UTMify cobra por pedido enviado?

Consulte os planos do UTMify em app.utmify.com.br. O Rise Bots envia todos os eventos (PIX gerado, pago, reembolsado) — cada mudança de status conta como uma atualização do mesmo pedido (mesmo orderId).

9. Posso usar o UTMify sem anúncios pagos?

Sim, mas o maior valor do UTMify é medir ROI de campanhas pagas. Para tráfego orgânico (Instagram, YouTube, WhatsApp), você pode usar UTMs manuais com o modo Personalizado do UTM Generator, ou simplesmente usar deep links do Telegram que já aparecem no dashboard do Rise Bots.

10. O que acontece se a API do UTMify estiver fora do ar?

O Rise Bots registra o erro internamente. O pagamento é processado normalmente (o cliente recebe acesso), mas os dados não chegam ao UTMify naquele momento. Não há reenvio automático — pedidos perdidos por indisponibilidade da API não são reenviados.

11. Posso ter mais de uma integração UTMify ativa?

Não. O sistema permite apenas uma integração UTMify ativa por conta. Se você precisar trocar o token, edite a integração existente em vez de criar uma nova.

12. As macros do UTM Generator funcionam com qualquer plataforma de ads?

As macros são específicas de cada plataforma. As macros do Meta ({{campaign.name}}) não funcionam no TikTok, e vice-versa. Use sempre o preset correto no UTM Generator. Para plataformas não listadas, use o modo Personalizado com valores manuais.

13. O que significa "organico" no campo sales_code?

Significa que o cliente acessou o bot sem passar por um redirecionador — ou seja, acessou diretamente pelo Telegram. Nesse caso, não há UTMs associados e o sales_code padrão é "organico".

14. Preciso ativar a integração antes de começar a rodar ads?

Sim, idealmente. A integração deve estar ativa antes dos pagamentos acontecerem. Pagamentos feitos antes da ativação não são enviados retroativamente ao UTMify. Além disso, o UTMify tem um limite de 7 dias — pagamentos mais antigos são rejeitados.

15. Como sei se o problema é no Rise Bots ou no UTMify?

Faça o protocolo de teste descrito acima. Se o teste funciona (venda aparece com UTMs no UTMify), o problema está na configuração dos seus anúncios (URL errada, macros não substituídas). Se o teste não funciona (venda não aparece), verifique o token e a integração no Rise Bots.