API do Trackeado

Como funciona

1. O seller gera o token do Trackeado (começa com sxt_) no painel dele e cola no seu painel, num card "Trackeado" do lado da UTMify.
2. O link do anúncio continua sendo o seu (redirect, presell, t.me/bot?start=). A gente não cria link nenhum, então nada conflita com o seu rastreio.
3. No /start do bot você manda o lead com as UTMs e o clique (POST /leads).
4. A cada mudança da venda (PIX gerado, pago, reembolsado…) você manda o pedido (POST /orders), com o lead_id.
5. A venda aparece no Tracker do seller atribuída a campanha, conjunto e anúncio, com o lucro e o ROAS do dia, e o celular dele toca na venda paga.

URL base (versão 2026-11-01):

https://api.shopixpay.app/functions/v1/tracker

O card no seu painel (do lado da UTMify)

Se o seu painel já tem a tela de Trackeamento com cards (Facebook, UTMify, TikTok, Kwai), o Trackeado é mais um card, com a mesma tela de config da UTMify:

Seller com página própria (script)

Esta API é pra plataformas que mandam os eventos do servidor (bots, checkouts, gateways). O seller que tem página de vendas própria instala também o script do Trackeado: uma linha só, colada no <head> da página, que guarda as UTMs e os ids de clique e leva tudo até a venda. O seller copia o script pronto, já com a conta dele, em trackeado.com/comecar.

Token e autenticação

Igual UTMify: o token vai no header x-api-token. Também aceitamos Authorization: Bearer. Um token por conta. Ele diz de qual seller é a venda.

x-api-token: sxt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /ping: testar conexão

Use no botão "Testar" do seu painel. Devolve o nome da conta, pra mostrar ao seller que o token está certo.

curl https://api.shopixpay.app/functions/v1/tracker/ping -H "x-api-token: sxt_..."

{ "ok": true, "loja": { "id": "1d7e...", "nome": "Conta da Maria" }, "versao": "2026-11-01" }

POST /leads: o /start do bot

Mande quando a pessoa chega no bot (ou entra no canal/grupo). Guardamos a campanha do lead: o pedido que vier depois só com o lead_id já sai atribuído, inclusive as renovações de assinatura meses depois. Se o mesmo lead clicar em outro anúncio, o último clique com campanha vence.

curl -X POST https://api.shopixpay.app/functions/v1/tracker/leads \
  -H "x-api-token: $TRACKEADO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "start",
  "platform": "SeuBot",
  "lead_id": "987654321",
  "created_at": "2026-11-01 14:30:05",
  "telegram": {
    "user_id": 987654321,
    "username": "maria_souza",
    "first_name": "Maria",
    "last_name": "Souza",
    "language_code": "pt-br",
    "is_premium": false,
    "start_param": "c_8f3a91b2",
    "bot_username": "lojadamaria_bot"
  },
  "trackingParameters": {
    "utm_source": "FB",
    "utm_medium": "cpc",
    "utm_campaign": "Campanha X|120210000000000001",
    "utm_content": "Criativo 07|120210000000000003",
    "utm_term": "Conjunto A|120210000000000002",
    "src": null,
    "sck": null
  },
  "click": {
    "ip": "177.10.20.30",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) ...",
    "fbclid": "IwAR2xY...",
    "fbc": "fb.1.1761999000000.IwAR2xY...",
    "fbp": "fb.1.1761998990000.1234567890",
    "landing_page": "https://seubot.com.br/l/abc123"
  }
}'

{ "ok": true, "lead_id": "987654321", "evento": "start", "novo": true }

POST /orders: a venda

Mesmo formato da API da UTMify (api-credentials/orders). Mande uma vez por mudança de status, sempre com o mesmo orderId.

Campos da UTMify (iguais)

Campos extras do Trackeado (opcionais)

curl -X POST https://api.shopixpay.app/functions/v1/tracker/orders \
  -H "x-api-token: $TRACKEADO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "ped_7f3a2c",
  "platform": "SeuBot",
  "paymentMethod": "pix",
  "status": "paid",
  "createdAt": "2026-11-01 14:31:10",
  "approvedDate": "2026-11-01 14:33:42",
  "refundedAt": null,
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com",
    "phone": "5511987654321",
    "document": "12345678909",
    "country": "BR",
    "ip": "177.10.20.30"
  },
  "products": [
    {
      "id": "vip-mensal",
      "name": "Grupo VIP mensal",
      "planId": "mensal",
      "planName": "Mensal",
      "quantity": 1,
      "priceInCents": 2990
    }
  ],
  "trackingParameters": {
    "utm_source": "FB",
    "utm_medium": "cpc",
    "utm_campaign": "Campanha X|120210000000000001",
    "utm_content": "Criativo 07|120210000000000003",
    "utm_term": "Conjunto A|120210000000000002",
    "src": null,
    "sck": null
  },
  "commission": {
    "totalPriceInCents": 2990,
    "gatewayFeeInCents": 150,
    "userCommissionInCents": 2840,
    "currency": "BRL"
  },
  "isTest": false,
  "lead_id": "987654321",
  "flow": {
    "id": "fx_12",
    "name": "Funil VIP"
  },
  "telegram": {
    "user_id": 987654321,
    "username": "maria_souza",
    "start_param": "c_8f3a91b2",
    "bot_username": "lojadamaria_bot"
  },
  "subscription": {
    "subscription_id": "sub_91aa",
    "renewal_index": 0,
    "period_days": 30,
    "expires_at": "2026-12-01 14:33:42"
  }
}'

{ "ok": true, "order_id": "b51f0e1c-...", "numero": 10452, "criado": true, "status": "pago" }

// mesmo orderId de novo, com outro status:
{ "ok": true, "order_id": "b51f0e1c-...", "de": "aguardando_pagamento", "para": "pago" }

// mesmo orderId e mesmo status (reenvio):
{ "ok": true, "noop": "mesmo status", "order_id": "b51f0e1c-..." }

Assinatura, renovação e upsell

• Cada cobrança é um pedido com orderId próprio. A renovação leva o mesmo lead_id e subscription_id, com renewal_index 1, 2, 3…
• A renovação não precisa de UTM: herda a campanha do lead. O anúncio que trouxe o assinante ganha o LTV.
• Upsell, downsell e order bump: pedido próprio com parent_order_id = o orderId do pedido principal.

{
  "orderId": "ped_7f3a2c_r1",
  "platform": "SeuBot",
  "paymentMethod": "pix",
  "status": "paid",
  "createdAt": "2026-12-01 14:30:00",
  "approvedDate": "2026-12-01 14:31:15",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com"
  },
  "products": [
    {
      "id": "vip-mensal",
      "name": "Grupo VIP mensal",
      "quantity": 1,
      "priceInCents": 2990
    }
  ],
  "lead_id": "987654321",
  "subscription": {
    "subscription_id": "sub_91aa",
    "renewal_index": 1,
    "period_days": 30,
    "expires_at": "2027-01-01 14:31:15"
  }
}

Status e datas

• Datas sem fuso ("2026-11-01 14:30:00") são lidas como UTC, igual UTMify. Com fuso (ISO 8601), respeitamos o fuso.
• Venda paga não volta pra "aguardando" nem "recusado": esse aviso fora de ordem é ignorado.
• Valor em centavos, inteiro. Moeda em commission.currency (padrão BRL).

Reenvio, idempotência e volume

• Idempotente: o mesmo orderId com o mesmo status de novo não duplica nada. Pode reenviar sem medo.
• Reenvie em 409 e 5xx (ou timeout), com backoff exponencial: 10 s, 30 s, 2 min, 10 min, 1 h… até 24 h.
• Não trave o bot: mande em fila, assíncrono, timeout de 10 s. O PIX e a entrega do produto nunca dependem da nossa resposta.
• Volume: feito pra centenas de milhares de eventos por dia. Mande um evento por requisição, assim que acontecer (sem lote).
• Corpo até 64 KB. Campos que não conhecemos são ignorados, então pode mandar o seu JSON inteiro.

Erros

Erro vem com "ok": false, "codigo" e "erro" (texto).

O que o Telegram entrega (e o que não)

Pra ninguém prometer dado que não existe: isto é tudo o que a Bot API do Telegram dá a um bot.

Pixels e API de Conversões

• Hoje o Trackeado não dispara pixel nem CAPI com as vendas que você manda. Se você já dispara Purchase pra Meta/TikTok/Kwai, continue: mandar dos dois lados duplicaria a compra.
• Mesmo assim, mande click.ip, click.user_agent, click.fbc e click.fbp: ajudam na atribuição e deixam o seller pronto pra ligar o envio pelo Trackeado no futuro sem você mudar nada.
• Pro Trackeado os dados do cliente vão em texto, sem hash: a gente não repassa nada pras redes. O hash é só no que você manda pra Meta/TikTok (abaixo).

Qualidade do sinal (pra quem dispara pixel e CAPI)

O mesmo padrão que o nosso checkout usa pra subir a qualidade da correspondência dos eventos na Meta. Vale pro seu pixel e pro seu CAPI:

POST https://graph.facebook.com/v21.0/<PIXEL_ID>/events?access_token=<TOKEN_CAPI>

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1761999222,
    "event_id": "ped_7f3a2c",
    "action_source": "chat",
    "user_data": {
      "em": ["<sha256 de maria@email.com>"],
      "ph": ["<sha256 de 5511987654321>"],
      "fn": ["<sha256 de maria>"],
      "ln": ["<sha256 de souza>"],
      "external_id": ["<sha256 de 987654321>"],
      "client_ip_address": "2804:14c:5b80:8a5c::1",
      "client_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) ...",
      "fbc": "fb.1.1761999000000.IwAR2xY...",
      "fbp": "fb.1.1761998990000.1234567890"
    },
    "custom_data": { "currency": "BRL", "value": 29.90 }
  }]
}

LGPD

• Mande só o que você tem e precisa. Nada de pedir CPF, e-mail ou telefone no bot só pra preencher a gente: nenhum campo de cliente é obrigatório.
• Avise no /start que o bot registra dados de navegação e compra pra medir anúncios (link da sua política de privacidade). Pra pixel/CAPI, quem coleta (o seller e você) precisa da base legal certa.
• Hash não é anonimização: e-mail ou telefone em SHA-256 continua sendo dado pessoal.
• Aqui o lead sem atividade há 180 dias é apagado. A venda guarda só o necessário pra relatório do seller.
• Pedido de exclusão de um titular: o seller pede pelo suporte do Trackeado e a gente apaga.
• Nicho sensível (saúde, adulto, apostas): o nome do produto nunca vai pras redes de anúncio.

Checklist do parceiro

1. Campo "Token do Trackeado" no painel do seller, do lado da UTMify, com botão "Testar" (GET /ping).
2. Na página de redirect (antes do t.me): guardar UTMs, fbclid/ttclid/gclid/kwai click_id, _fbp/_fbc, IP, user agent e a URL, amarrados ao start_param.
3. No /start: POST /leads com telegram.user_id, start_param e o clique guardado. Mande o start_param inteiro, exatamente como chegou, também em todo /orders: é ele que liga o clique do anúncio à venda.
4. PIX gerado: POST /orders com status waiting_payment. Pago: o mesmo orderId com status paid.
5. Reembolso, chargeback, recusado: o mesmo orderId com o status novo.
6. Renovação de assinatura: orderId novo, mesmo lead_id e subscription_id, renewal_index + 1.
7. Upsell/downsell: orderId novo com parent_order_id do pedido principal.
8. Fila com reenvio (backoff exponencial, até 24 h) pra 409 e 5xx. Outros 4xx não reenviam: corrija o corpo.
9. Nunca travar o bot nem o PIX esperando a nossa resposta: envio assíncrono, timeout 10 s.
10. Se você dispara pixel/CAPI: event_id = orderId (Purchase) nos dois lados, IPv6 quando houver, fbc/fbp da página de redirect, e-mail e telefone normalizados em SHA-256.