API externa - Trackup

Todas as rotas exigem autenticação via API Key. O corpo das requisições é JSON. Respostas de sucesso retornam status 201.

URL base

Produção: https://dash-api.trackup.me/v1 Monte a URL completa concatenando o endpoint ao base. Exemplo: https://dash-api.trackup.me/v1/visitors.

Método	Endpoint
`POST`	`/visitors`
`POST`	`/conversions`
`POST`	`/requests`

Autenticação

Envie a chave no header X-Api-Key em cada requisição.

Status	Condição
`401`	Header ausente ou chave inválida
`403`	Chave revogada ou expirada

POST /visitors

Cria um visitante no projeto vinculado à API Key.

Corpo da requisição

Todos os campos são opcionais.

Campo	Tipo	Obrigatório	Descrição
`utmSource`	string	não	Origem UTM
`utmMedium`	string	não	Meio UTM
`utmCampaign`	string	não	Campanha UTM
`utmTerm`	string	não	Termo UTM
`utmContent`	string	não	Conteúdo UTM
`clickId`	string	não	ID de clique
`name`	string	não	Nome
`email`	string	não	E-mail
`phone`	string	não	Telefone
`addressStreet`	string	não	Rua
`addressCity`	string	não	Cidade
`addressState`	string	não	Estado
`addressZip`	string	não	CEP
`addressCountry`	string	não	País

Resposta

Campo	Tipo	Descrição
`id`	string	ID do visitante
`createdAt`	string	Data de criação (ISO 8601)
`name`	string \| null	Nome
`email`	string \| null	E-mail
`phone`	string \| null	Telefone
`address`	object	Endereço
`address.street`	string \| null	Rua
`address.city`	string \| null	Cidade
`address.state`	string \| null	Estado
`address.zip`	string \| null	CEP
`address.country`	string \| null	País
`utmSource`	string	Origem UTM
`utmMedium`	string	Meio UTM
`utmCampaign`	string	Campanha UTM
`clickId`	string	ID de clique

Exemplo

curl -X POST 'https://dash-api.trackup.me/v1/visitors' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
    "name": "Maria Silva",
    "email": "maria@example.com",
    "utmSource": "google",
    "utmCampaign": "black-friday"
  }'

POST /conversions

Registra uma conversão no projeto vinculado à API Key. O campo value é convertido para a moeda configurada no projeto.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`value`	number	sim	Valor da conversão
`transactionId`	string	não	ID da transação
`currency`	string	não	Moeda de origem (ex.: `BRL`, `USD`)
`paymentMethod`	string	não	Método de pagamento
`ip`	string	não	Endereço IP
`userAgent`	string	não	User agent
`visitorId`	string	não	ID do visitante
`trafficSource`	string	não	Fonte de tráfego
`utmSource`	string	não	Origem UTM
`utmMedium`	string	não	Meio UTM
`utmCampaign`	string	não	Campanha UTM
`utmTerm`	string	não	Termo UTM
`utmContent`	string	não	Conteúdo UTM
`clickId`	string	não	ID de clique
`sub1`	string	não	Sub ID 1
`sub2`	string	não	Sub ID 2
`sub3`	string	não	Sub ID 3
`sub4`	string	não	Sub ID 4
`sub5`	string	não	Sub ID 5
`sub6`	string	não	Sub ID 6
`sub7`	string	não	Sub ID 7
`sub8`	string	não	Sub ID 8
`status`	string	não	Status da conversão (padrão: `"paid"`) — ver valores abaixo

Valores aceitos para status:

Valor	Descrição
`paid`	Pagamento confirmado (padrão)
`refunded`	Reembolso
`chargeback`	Chargeback

Resposta

Campo	Tipo	Descrição
`id`	string	ID da conversão
`timestamp`	string	Data/hora (ISO 8601)
`transactionId`	string	ID da transação
`value`	number	Valor convertido
`currency`	string	Moeda do projeto
`paymentMethod`	string	Método de pagamento
`status`	string	Status da conversão
`visitorId`	string	ID do visitante

Exemplo

curl -X POST 'https://dash-api.trackup.me/v1/conversions' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
    "value": 199.90,
    "currency": "BRL",
    "transactionId": "txn_abc123",
    "visitorId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
  }'

POST /requests

Registra um evento ou requisição no projeto vinculado à API Key. Requisições criadas via API Key não disparam triggers ou pixels — apenas persistem o registro.

Corpo da requisição

Todos os campos são opcionais.

Campo	Tipo	Obrigatório	Descrição
`host`	string	não	Host da requisição (padrão: `""`)
`path`	string	não	Caminho da requisição (padrão: `""`)
`event`	string	não	Nome do evento (padrão: `""`)
`ip`	string	não	Endereço IP
`userAgent`	string	não	User agent
`visitorId`	string	não	ID do visitante
`trafficSource`	string	não	Fonte de tráfego (padrão: `"direct"`)
`utmSource`	string	não	Origem UTM
`utmMedium`	string	não	Meio UTM
`utmCampaign`	string	não	Campanha UTM
`utmTerm`	string	não	Termo UTM
`utmContent`	string	não	Conteúdo UTM
`clickId`	string	não	ID de clique
`sub1`–`sub8`	string	não	Sub IDs 1 a 8
`customData`	object	não	Dados customizados (ver abaixo)

customData

Objeto plano com pares chave-valor.

Regra	Valor
Máximo de chaves	15
Tamanho máximo	8 KB (JSON serializado)
Violação	Resposta `400`

Valores aninhados são permitidos. Se omitido, armazena {}.

Resposta

Campo	Tipo	Descrição
`id`	string	ID da requisição
`timestamp`	string	Data/hora (ISO 8601)
`host`	string	Host
`path`	string	Caminho
`event`	string	Nome do evento
`visitorId`	string	ID do visitante
`trafficSource`	string	Fonte de tráfego
`utmSource`	string	Origem UTM
`utmMedium`	string	Meio UTM
`utmCampaign`	string	Campanha UTM
`utmTerm`	string	Termo UTM
`utmContent`	string	Conteúdo UTM
`clickId`	string	ID de clique
`sub1`–`sub8`	string	Sub IDs 1 a 8
`customData`	object \| null	Dados customizados

Exemplo

curl -X POST 'https://dash-api.trackup.me/v1/requests' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
    "event": "purchase",
    "host": "loja.example.com",
    "path": "/checkout/success",
    "visitorId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "customData": {
      "orderId": "ord_123",
      "value": 299.90
    }
  }'

Erros

Status	Causa
`400`	Corpo inválido ou `customData` fora dos limites
`401`	API Key ausente ou inválida
`403`	API Key revogada ou expirada
`404`	Projeto não encontrado
`500`	Falha ao persistir o registro
`502`	Falha na conversão de moeda (`POST /conversions`)

​URL base

​Autenticação

​POST /visitors

​Corpo da requisição

​Resposta

​Exemplo

​POST /conversions

​Corpo da requisição

​Resposta

​Exemplo

​POST /requests

​Corpo da requisição

​customData

​Resposta

​Exemplo

​Erros

URL base

Autenticação

POST /visitors

Corpo da requisição

Resposta

Exemplo

POST /conversions

Corpo da requisição

Resposta

Exemplo

POST /requests

Corpo da requisição

customData

Resposta

Exemplo

Erros