API Documentation

Documentacao completa das APIs publicas do TrackForge. Envie eventos, receba webhooks, consulte atribuicao e reconciliacao.

Quick Start

Comece a rastrear eventos em 3 passos.

Obtenha sua API Key

Acesse Settings > API Keys no dashboard e crie uma nova chave. Ela comeca com tf_.

Instale o script de tracking

Adicione o snippet no <head> do seu site. Se configurou um dominio de tracking (CNAME), use-o como base:

HTML SnippetCopiar

<script src="https://t.seudominio.com/api/v1/script?k=tf_SUA_CHAVE" async></script>

O script captura automaticamente pageviews, UTMs, click IDs (gclid, fbclid) e session/visitor IDs.

Envie um evento de teste

Teste a integracao enviando um evento via pixel:

curlCopiar

curl "https://t.seudominio.com/p?k=tf_SUA_CHAVE&e=test_event&rev=1.00&cur=BRL"

Verifique no dashboard em Ops > Event Feed se o evento apareceu.

Configure webhooks (opcional)

Para receber conversoes server-side, configure o webhook da sua plataforma de e-commerce:

WooCommerce Shopify Zapier / Make S2S Postback

Autenticacao

A API do TrackForge suporta tres metodos de autenticacao dependendo do caso de uso.

API Key

Metodo principal de autenticacao para todas as APIs. Envie a chave em um dos formatos:

Header: x-tf-key: tf_abc123

Query param: ?k=tf_abc123

Exemplo com headerCopiar

curl "https://trackforge-nu.vercel.app/api/v1/conversions?from=2024-01-01&to=2024-01-31" \
  -H "x-tf-key: tf_abc123"

HMAC-SHA256

Usado para postbacks S2S. O payload e assinado com a chave secreta do projeto.

Header: x-tf-signature: sha256=HMAC_HEX

Gerando a assinatura (Node.js)Copiar

const crypto = require('crypto');
const body = JSON.stringify(payload);
const signature = 'sha256=' + crypto
  .createHmac('sha256', 'seu_webhook_secret')
  .update(body)
  .digest('hex');

// Envie como header: x-tf-signature: sha256=abc123...

Plataformas (WooCommerce / Shopify)

Webhooks do WooCommerce e Shopify usam suas proprias assinaturas HMAC nativas. O TrackForge valida automaticamente:

WooCommerce: x-wc-webhook-signature

Shopify: x-shopify-hmac-sha256

Tracking

GET/p

Pixel / Event Ingestion

Endpoint principal de coleta de eventos. Retorna uma imagem 1x1 GIF transparente. Usado pelo script tf.js automaticamente, mas pode ser chamado diretamente para tracking server-side.

Auth: API Key via query param `k`

Query Parameters

Param	Tipo	Obrig.	Descricao
k	string	Sim	API Key do projeto
e	string	Sim	Nome do evento (pageview, click, purchase, lead, etc.)
eid	string	Nao	Event ID para deduplicacao
sid	string	Nao	Session ID
vid	string	Nao	Visitor ID (persistente)
url	string	Nao	URL da pagina atual
title	string	Nao	Titulo da pagina
ref	string	Nao	Referrer URL
gclid	string	Nao	Google Click ID
fbclid	string	Nao	Facebook Click ID
wbraid	string	Nao	Google Web-to-App Click ID
gbraid	string	Nao	Google App Click ID
fbc	string	Nao	Facebook Click cookie (_fbc)
fbp	string	Nao	Facebook Browser ID (_fbp)
utm_source	string	Nao	UTM Source
utm_medium	string	Nao	UTM Medium
utm_campaign	string	Nao	UTM Campaign
utm_content	string	Nao	UTM Content
utm_term	string	Nao	UTM Term
rev	number	Nao	Valor da receita (ex: 149.90)
cur	string	Nao	Moeda (ISO 4217, ex: BRL, USD)
oid	string	Nao	Order ID
payload	string	Nao	JSON com dados extras (URL-encoded)

Exemplo de RequestCopiar

curl "https://t.seudominio.com/p?k=tf_abc123&e=purchase&rev=149.90&cur=BRL&oid=ORD-001&vid=v_xyz"

Exemplo de ResponseCopiar

# Retorna 1x1 GIF transparente (image/gif)
# Status: 200 OK
# Headers: Cache-Control: no-store

GET/r/[token]

Redirect Tracking

Redireciona para o destino configurado, capturando todos os query params como click data. Ideal para tracking de links em emails, bio links, etc.

Auth: Nenhuma (token publico)

Query Parameters

Param	Tipo	Obrig.	Descricao
token	string	Sim	Token unico do redirect (path param)
*	string	Nao	Todos os query params sao capturados e encaminhados

Exemplo de RequestCopiar

curl -v "https://t.seudominio.com/r/abc123?utm_source=email&utm_campaign=blackfriday"

Exemplo de ResponseCopiar

# Status: 302 Found
# Location: https://seusite.com/oferta?utm_source=email&utm_campaign=blackfriday

GET/api/v1/script

Tracking Script

Retorna o script tf.js configurado para o projeto. O script captura automaticamente pageviews, clicks, UTMs e click IDs. Menor que 3KB gzip.

Auth: API Key via query param `k`

Query Parameters

Param	Tipo	Obrig.	Descricao
k	string	Sim	API Key do projeto

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/script?k=tf_abc123"

Exemplo de ResponseCopiar

// tf.js minificado com config do projeto
// Content-Type: application/javascript
// Cache-Control: public, max-age=3600
(function(){var e="https://t.seudominio.com",k="tf_abc123";...})()

Webhooks (Inbound)

POST/api/v1/postback

S2S Postback

Endpoint para postbacks server-to-server. Usado para enviar conversoes de plataformas que suportam postback URLs (Keitaro, Voluum, etc.).

Auth: HMAC-SHA256 via header `x-tf-signature`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
event_type	string	Sim	Tipo do evento (purchase, lead, refund)
order_id	string	Nao	ID do pedido
revenue	number	Nao	Valor da conversao
currency	string	Nao	Moeda (BRL, USD, etc.)
customer_email	string	Nao	Email do cliente
customer_phone	string	Nao	Telefone do cliente
items	array	Nao	Lista de itens [{name, sku, quantity, price}]
click_id	string	Nao	Click ID interno do TrackForge
gclid	string	Nao	Google Click ID
fbclid	string	Nao	Facebook Click ID
metadata	object	Nao	Dados extras em formato chave-valor

Exemplo de RequestCopiar

curl -X POST "https://trackforge-nu.vercel.app/api/v1/postback" \
  -H "Content-Type: application/json" \
  -H "x-tf-key: tf_abc123" \
  -H "x-tf-signature: sha256=HMAC_HEX" \
  -d '{
    "event_type": "purchase",
    "order_id": "ORD-001",
    "revenue": 149.90,
    "currency": "BRL",
    "customer_email": "cliente@email.com",
    "click_id": "clk_xyz789"
  }'

Exemplo de ResponseCopiar

{
  "success": true,
  "event_id": "evt_abc123",
  "message": "Postback received"
}

POST/api/v1/webhook/woo

WooCommerce Webhook

Recebe webhooks do WooCommerce para pedidos criados, atualizados e reembolsados. Configure no WooCommerce: Settings > Advanced > Webhooks.

Auth: WooCommerce HMAC via header `x-wc-webhook-signature`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
id	number	Sim	ID do pedido no WooCommerce
status	string	Sim	Status do pedido (processing, completed, refunded)
total	string	Sim	Valor total do pedido
currency	string	Sim	Moeda
billing	object	Sim	Dados de cobranca (email, phone, etc.)
line_items	array	Sim	Itens do pedido

Exemplo de RequestCopiar

# Configurado automaticamente pelo WooCommerce
# Delivery URL: https://trackforge-nu.vercel.app/api/v1/webhook/woo?k=tf_abc123
# Topic: Order created
# Secret: seu_webhook_secret

Exemplo de ResponseCopiar

{
  "success": true,
  "order_id": "WOO-1234",
  "events_created": 1
}

POST/api/v1/webhook/shopify

Shopify Webhook

Recebe webhooks do Shopify para pedidos e reembolsos. Configure via Shopify Admin: Settings > Notifications > Webhooks.

Auth: Shopify HMAC via header `x-shopify-hmac-sha256`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
id	number	Sim	ID do pedido no Shopify
order_number	number	Sim	Numero do pedido
total_price	string	Sim	Valor total
currency	string	Sim	Moeda
email	string	Sim	Email do cliente
line_items	array	Sim	Itens do pedido

Exemplo de RequestCopiar

# Configurado automaticamente pelo Shopify
# URL: https://trackforge-nu.vercel.app/api/v1/webhook/shopify?k=tf_abc123
# Event: orders/create, orders/paid, refunds/create

Exemplo de ResponseCopiar

{
  "success": true,
  "order_id": "SHOP-5678",
  "events_created": 1
}

POST/api/v1/webhook/call

Call Tracking Webhook

Recebe dados de chamadas telefonicas de plataformas de call tracking (CallRail, Phonetrack, etc.).

Auth: API Key via header `x-tf-key`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
caller_number	string	Sim	Numero do chamador
tracking_number	string	Sim	Numero de tracking
destination_number	string	Nao	Numero de destino
call_status	string	Sim	Status (answered, missed, voicemail)
call_duration_seconds	number	Nao	Duracao em segundos
recording_url	string	Nao	URL da gravacao
utm_source	string	Nao	UTM Source da sessao
utm_medium	string	Nao	UTM Medium da sessao
utm_campaign	string	Nao	UTM Campaign da sessao

Exemplo de RequestCopiar

curl -X POST "https://trackforge-nu.vercel.app/api/v1/webhook/call" \
  -H "Content-Type: application/json" \
  -H "x-tf-key: tf_abc123" \
  -d '{
    "caller_number": "+5511999999999",
    "tracking_number": "+551140001234",
    "call_status": "answered",
    "call_duration_seconds": 180,
    "utm_source": "google",
    "utm_campaign": "brand"
  }'

Exemplo de ResponseCopiar

{
  "success": true,
  "event_id": "evt_call_abc",
  "message": "Call event recorded"
}

POST/api/v1/webhook/email

Email Events Webhook

Recebe eventos de email de plataformas como Klaviyo, ActiveCampaign, Mailchimp, etc.

Auth: API Key via header `x-tf-key`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
event_type	string	Sim	Tipo do evento (sent, opened, clicked, bounced, unsubscribed)
email	string	Sim	Email do destinatario
campaign_name	string	Nao	Nome da campanha
link_url	string	Nao	URL clicada (para eventos clicked)
timestamp	string	Nao	Timestamp ISO 8601 do evento

Exemplo de RequestCopiar

curl -X POST "https://trackforge-nu.vercel.app/api/v1/webhook/email" \
  -H "Content-Type: application/json" \
  -H "x-tf-key: tf_abc123" \
  -d '{
    "event_type": "clicked",
    "email": "cliente@email.com",
    "campaign_name": "Black Friday 2024",
    "link_url": "https://seusite.com/oferta",
    "timestamp": "2024-11-29T10:30:00Z"
  }'

Exemplo de ResponseCopiar

{
  "success": true,
  "event_id": "evt_email_abc",
  "message": "Email event recorded"
}

POST/api/v1/webhook/generic

Generic Webhook (Zapier / Make / n8n)

Endpoint generico para integracoes via Zapier, Make (Integromat) ou n8n. Aceita qualquer tipo de evento.

Auth: API Key via header `x-tf-key`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
event_type	string	Sim	Tipo do evento (conversion, refund, customer_update, custom)
order_id	string	Nao	ID do pedido
revenue	number	Nao	Valor
currency	string	Nao	Moeda
customer_email	string	Nao	Email do cliente
items	array	Nao	Lista de itens [{name, sku, quantity, price}]
metadata	object	Nao	Dados extras livres

Exemplo de RequestCopiar

curl -X POST "https://trackforge-nu.vercel.app/api/v1/webhook/generic" \
  -H "Content-Type: application/json" \
  -H "x-tf-key: tf_abc123" \
  -d '{
    "event_type": "conversion",
    "order_id": "ORD-999",
    "revenue": 299.00,
    "currency": "BRL",
    "customer_email": "cliente@email.com",
    "metadata": {
      "source": "zapier",
      "funnel": "webinar"
    }
  }'

Exemplo de ResponseCopiar

{
  "success": true,
  "event_id": "evt_gen_abc",
  "message": "Generic event recorded"
}

REST APIs (Leitura)

GET/api/v1/attribution

Attribution Results

Retorna resultados de atribuicao agregados por canal, campanha ou ad.

Auth: API Key via header `x-tf-key`

Query Parameters

Param	Tipo	Obrig.	Descricao
from	string	Sim	Data inicio (YYYY-MM-DD)
to	string	Sim	Data fim (YYYY-MM-DD)
model	string	Nao	Modelo de atribuicao (last_click, first_click, linear, position_based). Default: last_click
group_by	string	Nao	Agrupamento (source, campaign, ad). Default: source

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/attribution?from=2024-01-01&to=2024-01-31&model=last_click&group_by=campaign" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "data": [
    {
      "group": "Black Friday 2024",
      "conversions": 145,
      "revenue": 21750.00,
      "cost": 5200.00,
      "roas": 4.18,
      "cpa": 35.86
    },
    {
      "group": "Brand - Search",
      "conversions": 89,
      "revenue": 12460.00,
      "cost": 1200.00,
      "roas": 10.38,
      "cpa": 13.48
    }
  ],
  "model": "last_click",
  "period": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET/api/v1/conversions

Conversions List

Retorna lista de conversoes com detalhes de atribuicao.

Auth: API Key via header `x-tf-key`

Query Parameters

Param	Tipo	Obrig.	Descricao
from	string	Sim	Data inicio (YYYY-MM-DD)
to	string	Sim	Data fim (YYYY-MM-DD)
status	string	Nao	Filtrar por status (confirmed, pending, refunded)
limit	number	Nao	Limite de resultados (default: 50, max: 500)
offset	number	Nao	Offset para paginacao

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/conversions?from=2024-01-01&to=2024-01-31&status=confirmed&limit=10" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "data": [
    {
      "id": "conv_abc123",
      "order_id": "ORD-001",
      "revenue": 149.90,
      "currency": "BRL",
      "status": "confirmed",
      "source": "google",
      "campaign": "Brand - Search",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 234,
  "limit": 10,
  "offset": 0
}

GET/api/v1/reconciliation

Reconciliation Data

Compara dados do TrackForge com dados reportados pelas plataformas de ads.

Auth: API Key via header `x-tf-key`

Query Parameters

Param	Tipo	Obrig.	Descricao
from	string	Sim	Data inicio (YYYY-MM-DD)
to	string	Sim	Data fim (YYYY-MM-DD)
platform	string	Nao	Filtrar por plataforma (google, meta, tiktok)
level	string	Nao	Nivel de detalhe (campaign, adset, ad). Default: campaign

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/reconciliation?from=2024-01-01&to=2024-01-31&platform=meta" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "data": [
    {
      "campaign": "Black Friday - Conversao",
      "platform": "meta",
      "platform_conversions": 120,
      "trackforge_conversions": 98,
      "discrepancy_pct": -18.3,
      "platform_revenue": 18000.00,
      "trackforge_revenue": 14700.00
    }
  ],
  "period": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET/api/v1/journey

Journey Explorer

Exibe a jornada completa de um visitante ou pedido — todos os touchpoints.

Auth: API Key via header `x-tf-key`

Query Parameters

Param	Tipo	Obrig.	Descricao
order_id	string	Nao	Buscar por Order ID
visitor_id	string	Nao	Buscar por Visitor ID
conversion_id	string	Nao	Buscar por Conversion ID

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/journey?order_id=ORD-001" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "visitor_id": "v_xyz789",
  "touchpoints": [
    {
      "event": "pageview",
      "source": "google",
      "campaign": "Brand",
      "url": "https://seusite.com",
      "timestamp": "2024-01-10T08:00:00Z"
    },
    {
      "event": "pageview",
      "source": "meta",
      "campaign": "Retargeting",
      "url": "https://seusite.com/produto",
      "timestamp": "2024-01-12T15:30:00Z"
    },
    {
      "event": "purchase",
      "order_id": "ORD-001",
      "revenue": 149.90,
      "timestamp": "2024-01-12T15:45:00Z"
    }
  ]
}

GET/api/v1/health

Data Quality Score

Retorna um score de qualidade dos dados de tracking do projeto.

Auth: API Key via header `x-tf-key`

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/health" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "score": 87,
  "checks": {
    "pixel_installed": true,
    "events_last_24h": 1523,
    "conversion_rate": 3.2,
    "click_id_coverage": 78,
    "utm_coverage": 92,
    "dedup_rate": 2.1
  },
  "recommendations": [
    "Aumente a cobertura de click IDs para >90%"
  ]
}

GET/api/v1/events

Event Feed

Retorna feed de eventos brutos com filtros.

Auth: API Key via header `x-tf-key`

Query Parameters

Param	Tipo	Obrig.	Descricao
from	string	Nao	Data inicio (YYYY-MM-DD)
to	string	Nao	Data fim (YYYY-MM-DD)
event_name	string	Nao	Filtrar por tipo de evento
limit	number	Nao	Limite de resultados (default: 50, max: 500)

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/events?event_name=purchase&from=2024-01-01&limit=5" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "data": [
    {
      "id": "evt_abc123",
      "event_name": "purchase",
      "visitor_id": "v_xyz",
      "session_id": "s_abc",
      "revenue": 149.90,
      "order_id": "ORD-001",
      "source": "google",
      "campaign": "Brand",
      "timestamp": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 234,
  "limit": 5
}

GET/api/v1/reports

List Reports

Lista relatorios customizados salvos do projeto.

Auth: API Key via header `x-tf-key`

Exemplo de RequestCopiar

curl "https://trackforge-nu.vercel.app/api/v1/reports" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "data": [
    {
      "id": "rpt_abc",
      "name": "ROAS Semanal",
      "type": "attribution",
      "config": {
        "model": "last_click",
        "group_by": "campaign",
        "period": "last_7_days"
      },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Management

POST/api/v1/reports

Create / Update Report

Cria ou atualiza um relatorio customizado.

Auth: API Key via header `x-tf-key`

Body Parameters (JSON)

Param	Tipo	Obrig.	Descricao
id	string	Nao	ID do relatorio (se presente, atualiza)
name	string	Sim	Nome do relatorio
type	string	Sim	Tipo (attribution, conversions, reconciliation)
config	object	Sim	Configuracao do relatorio (model, group_by, period, filters)

Exemplo de RequestCopiar

curl -X POST "https://trackforge-nu.vercel.app/api/v1/reports" \
  -H "Content-Type: application/json" \
  -H "x-tf-key: tf_abc123" \
  -d '{
    "name": "ROAS Semanal",
    "type": "attribution",
    "config": {
      "model": "last_click",
      "group_by": "campaign",
      "period": "last_7_days"
    }
  }'

Exemplo de ResponseCopiar

{
  "success": true,
  "report": {
    "id": "rpt_abc",
    "name": "ROAS Semanal",
    "type": "attribution",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

DELETE/api/v1/reports

Delete Report

Exclui um relatorio customizado.

Auth: API Key via header `x-tf-key`

Query Parameters

Param	Tipo	Obrig.	Descricao
id	string	Sim	ID do relatorio a ser excluido

Exemplo de RequestCopiar

curl -X DELETE "https://trackforge-nu.vercel.app/api/v1/reports?id=rpt_abc" \
  -H "x-tf-key: tf_abc123"

Exemplo de ResponseCopiar

{
  "success": true,
  "message": "Report deleted"
}

Rate Limiting

Todas as APIs possuem rate limiting por IP para proteger contra abuso:

Endpoint	Limite	Janela
/p (pixel)	1000 req	1 minuto
/api/v1/* (REST)	100 req	1 minuto
/api/v1/webhook/*	200 req	1 minuto

Quando o limite e atingido, a API retorna 429 Too Many Requests com um header Retry-After.

Codigos de Erro

Codigo	Significado	Acao
200	Sucesso	-
302	Redirect (tracking links)	Seguir o redirect
400	Request invalido	Verificar parametros obrigatorios
401	API key invalida ou ausente	Verificar a chave no header x-tf-key ou param k
403	Assinatura HMAC invalida	Verificar o calculo do HMAC
404	Recurso nao encontrado	Verificar o endpoint e IDs
429	Rate limit excedido	Aguardar e tentar novamente (ver Retry-After)
500	Erro interno	Tentar novamente; contatar suporte se persistir

Pronto para comecar?

Crie sua conta gratuitamente e comece a rastrear em minutos.

Criar Conta Login

Navegacao

Quick Start Autenticacao Tracking Webhooks (Inbound)REST APIs (Leitura)Management