Genérico - Trackup

Utilize esta integração quando sua plataforma de checkout ou vendas não possui integração nativa com o Trackup. Após configurar o webhook conversões, reembolso e chargebacks poderem ser enviado para o Trackup, via POST JSON, permitindo registrar conversões, disparar pixels e alimentar seus relatórios.

Referência rápida

POST https://{dominio}/api/webhook/{code}
Content-Type: application/json

{
  "event": "paid",
  "transaction_id": "order_123",
  "value": 99.9,
  "currency": "BRL",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_method": "credit_card"
}

Criar a integração dentro do TrackUp

Acesse:

Projeto → Integrações → Plataformas de Venda

Clique em:

+ Adicionar Plataforma

Selecione:

Webhook Genérico

Configurar os parâmetros do Checkout

Ao selecionar Webhook Genérico, o Trackup irá sugerir automaticamente os principais parâmetros de rastreamento.O único parâmetro realmente obrigatório é:

request_id = {request.id}

Ele será responsável por identificar o clique original e realizar toda a atribuição da conversão.Você também pode enviar outros parâmetros para utilização dentro do checkout, como:

Preset padrão de parâmetros de checkout

Ao selecionar a plataforma Genérico no dashboard, os seguintes parâmetros são sugeridos automaticamente:

Parâmetro na URL de checkout	Macro (valor)
`request_id`	`{request.id}`
`utm_source`	`{request.utmSource}`
`utm_medium`	`{request.utmMedium}`
`utm_campaign`	`{request.utmCampaign}`
`utm_term`	`{request.utmTerm}`
`utm_content`	`{request.utmContent}`

Esses parâmetros são opcionais e servem apenas para utilização dentro da sua plataforma.

Macros adicionais disponíveis na URL de checkout

Além das UTMs, é possível usar qualquer macro {request.<campo>} na configuração de parâmetros do checkout:

Campo	Descrição
`id`	Request ID (mesmo valor de `request_id`)
`linkId`	ID do link
`clickId`	Click ID
`trafficSource`	Origem do tráfego
`sub1` – `sub8`	Sub IDs 1 a 8
`adPlatform`	Plataforma de anúncios
`adAccountId`	ID da conta de anúncios
`campaignId`	ID da campanha
`adsetId`	ID do conjunto de anúncios
`adId`	ID do criativo
`visitorId`	ID do visitante
`country`	País
`city`	Cidade
`state`	Estado
`browser`	Navegador
`os`	Sistema operacional
`device`	Tipo de dispositivo
`browserLanguage`	Idioma do navegador
`host`	Host da requisição
`path`	Path da requisição

Formato: {request.<campo>} — exemplo: {request.clickId}, {request.sub1}.

Esses campos são injetados na URL de checkout, não no body do webhook. O webhook precisa apenas devolver o request_id para que a atribuição seja resolvida.

Copiar a URL do Webhook

Após salvar a integração, o Trackup irá gerar automaticamente uma URL exclusiva.Exemplo:

Webhook URL

https://trackup.me/api/webhook/xxxxxxxxxxxxxxxx

Copie essa URL.Ela será utilizada pela sua plataforma para enviar as notificações de venda.

Enviar o webhook após cada venda

Sempre que ocorrer um evento de pagamento, sua plataforma deverá realizar um POST para a URL gerada pelo Trackup.

Propriedade	Valor
URL	`https://{dominio-primario}/api/webhook/{code}`
Método recomendado	`POST`
Content-Type recomendado	`application/json`

{dominio-primario} — domínio primário configurado no projeto.
{code} — código único de 16 caracteres gerado ao criar a plataforma de vendas no dashboard.

Nota: a rota aceita qualquer método HTTP. Também é possível enviar application/x-www-form-urlencoded, mas o contrato documentado é JSON via POST.

A URL completa é exibida no dashboard após salvar a plataforma de vendas do tipo Generic.

Payload

Todos os campos são enviados no corpo da requisição (body).

Campos principais

Campo	Tipo	Obrigatório	Descrição
`event`	string	Sim	Evento da transação. Valores reconhecidos: `paid`, `refunded`, `chargeback`.
`transaction_id`	string	Recomendado	ID único do pedido/transação. Usado para deduplicação.
`value`	number	Recomendado	Valor da transação. Arredondado para 2 casas decimais. Default: `0`.
`currency`	string	Opcional	Código da moeda (ex: `BRL`, `USD`). Convertido para uppercase. Vazio → `null`.
`request_id`	string	Recomendado	ID do clique original para atribuição de UTMs e dados de campanha.
`payment_method`	string	Opcional	Método de pagamento utilizado. Ver valores aceitos.

Objeto `customer` (opcional)

Campo	Tipo	Descrição
`customer.name`	string	Nome do comprador
`customer.email`	string	E-mail do comprador
`customer.phone`	string	Telefone do comprador
`customer.address.street`	string	Logradouro
`customer.address.city`	string	Cidade
`customer.address.state`	string	Estado
`customer.address.zip`	string	CEP
`customer.address.country`	string	País

Exemplo completo

{
  "event": "paid",
  "transaction_id": "order_123",
  "value": 99.9,
  "currency": "BRL",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_method": "credit_card",
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+5511999999999",
    "address": {
      "street": "Rua Example 1",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01000-000",
      "country": "BR"
    }
  }
}

Eventos e status

`event`	Status gravado	Comportamento
`paid`	`paid`	Conversão registrada. Dispara triggers e pixels configurados.
`refunded`	`refunded`	Conversão registrada com status de reembolso.
`chargeback`	`chargeback`	Conversão registrada com status de chargeback.
Qualquer outro (`pending`, `cancelled`, etc.)	—	Evento ignorado. Nenhuma conversão é gravada.

Respostas de sucesso (HTTP 200)

Pagamento confirmado:

{
  "ok": true,
  "id": "<conversion-id>"
}

Reembolso ou chargeback:

{
  "ok": true,
  "id": "<conversion-id>",
  "status": "refunded"
}

{
  "ok": true,
  "id": "<conversion-id>",
  "status": "chargeback"
}

Evento não reconhecido (ignorado):

{
  "ok": true,
  "ignored": true
}

Desduplicação

Se a mesma combinação de (projectId, webhookId, transactionId, status) já foi registrada, a API retorna HTTP 409:

{
  "error": "DUPLICATE_CONVERSION",
  "transactionId": "order_123"
}

Recomenda-se sempre enviar transaction_id para evitar registros duplicados e permitir reenvio seguro.

`payment_method` — valores aceitos

Valor enviado	Valor armazenado
`credit_card`	`credit_card`
`pix`	`pix`
`boleto`	`boleto`
`paypal`	`paypal`
`apple_pay`	`apple_pay`
`other`	`other`
ausente ou desconhecido	`null`

Como funciona a atribuição

O Webhook Genérico utiliza o request_id como chave principal de rastreamento. O fluxo funciona da seguinte forma:

O visitante clica em um link do Trackup.\
O Trackup gera um request_id exclusivo.\
Esse request_id chega até o checkout através dos parâmetros da URL.\
Sua plataforma salva esse identificador junto ao pedido.\
Quando a venda acontece, o webhook devolve o mesmo request_id.\
O Trackup recupera automaticamente todas as informações da campanha e registra a conversão.\

Dessa forma não é necessário enviar UTMs no webhook, pois elas já são recuperadas automaticamente pelo sistema.

Boas práticas

Sempre envie o request_id.
Sempre envie um transaction_id único.
Utilize Content-Type: application/json.
Reutilize o mesmo transaction_id para reembolsos e chargebacks.
Em caso de falha temporária, implemente novas tentativas de envio (retry).

Erros HTTP

Status	`error`	Quando ocorre
404	`SALES_PLATFORM_NOT_FOUND`	Código do webhook inválido ou plataforma não encontrada
404	`PROJECT_NOT_FOUND`	Projeto associado não encontrado
404	`TEAM_NOT_FOUND`	Time associado não encontrado
404	`CONFIG_NOT_FOUND`	Configuração do projeto não encontrada
400	`UNKNOWN_NETWORK`	Tipo de plataforma desconhecido
400	`PARSE_ERROR`	Erro ao processar dados da conversão
409	`DUPLICATE_CONVERSION`	Transação com mesmo ID e status já registrada
502	`CURRENCY_CONVERSION_FAILED`	Falha ao converter moeda estrangeira para a moeda do projeto

Integração concluída

Se o webhook estiver configurado corretamente, todas as novas vendas começarão a aparecer automaticamente no painel de Conversões do Trackup.O sistema fará toda a atribuição da venda utilizando o request_id, preenchendo automaticamente UTMs, campanhas, anúncios, click IDs e demais informações de rastreamento.

​Referência rápida

Criar a integração dentro do TrackUp

Configurar os parâmetros do Checkout

​Preset padrão de parâmetros de checkout

​Macros adicionais disponíveis na URL de checkout

Copiar a URL do Webhook

Enviar o webhook após cada venda

​Payload

​Campos principais

​Objeto customer (opcional)

​Exemplo completo

​Eventos e status

​Respostas de sucesso (HTTP 200)

​Desduplicação

​payment_method — valores aceitos

​Como funciona a atribuição

​Boas práticas

​Erros HTTP

​Integração concluída