Integre sua operação.
API v1 · Pixel próprio · Integração com o Router
1. Dashboard e chave
Crie um dashboard por oferta ou operação. Em Integrações & API, crie uma integração e copie sua chave privada. Cada integração mantém um espaço próprio de pedidos. Uma nova chave da mesma integração preserva esse espaço; uma integração diferente representa outro sistema de pedidos.
POST /v1/orders x-api-token: itr_sk_SUA_CHAVE Content-Type: application/json
A chave pertence a um único dashboard. Guarde no servidor, nunca no pixel, navegador ou endereço da página. Para trocar a chave, gere uma nova na mesma integração, atualize o Router e revogue a antiga.
2. Envie uma venda
Valores monetários são inteiros em centavos. Datas exigem ISO 8601 UTC com Z. Envie o estado completo do pedido, não diferenças. Não some taxas ou custos à receita. O campo userCommissionInCents é recebido para compatibilidade, mas o painel usa totalPriceInCents como faturamento bruto.
{
"eventId": "router:loja-a:pedido-123:versao-2",
"sourceUpdatedAt": "2026-10-27T15:02:00.000Z",
"orderId": "loja-a:pedido-123",
"platform": "commerce-router",
"paymentMethod": "pix",
"status": "paid",
"createdAt": "2026-10-27T15:00:00.000Z",
"approvedDate": "2026-10-27T15:02:00.000Z",
"refundedAt": null,
"refundedAmountInCents": 0,
"isTest": false,
"customer": {"email": "cliente@example.com", "country": "BR"},
"products": [{"id": "produto-1", "name": "Produto", "quantity": 1, "priceInCents": 12990}],
"commission": {"currency": "BRL", "totalPriceInCents": 12990, "gatewayFeeInCents": 500, "userCommissionInCents": 12490},
"trackingParameters": {
"utm_source": "meta", "utm_campaign": "Campanha|123456789",
"utm_medium": "Conjunto|234567890", "utm_content": "Anuncio|345678901",
"utm_term": "Instagram_Reels", "src": null, "sck": null
},
"trackingContext": {"trackingId": "trk_IDENTIFICADOR_DA_VISITA", "pixelId": "px_ID_DO_PIXEL"}
}
A API recebe somente vendas reais; isTest é opcional e deve ser false. O valor true retorna PRODUCTION_ONLY (422). Substitua as datas pela versão real da venda e os identificadores pelos do seu pixel. Se não tiver contexto de visita, omita trackingContext. Nunca invente cookies, origem ou dados de clientes.
Status: waiting_payment, paid, refused, refunded e chargedback. Pagamentos: credit_card, pix, boleto, paypal e free_price. Moedas: BRL, USD, EUR, GBP, ARS, CAD, MXN, PEN e PLN.
Para usar o filtro Tipo de venda, envie o campo opcional
saleType com one_time (venda única) ou
recurring (recorrência). Sem esse campo, o pedido aparece
em Todas, sem classificação presumida. O parâmetro opcional
trackingParameters.keyword permite agrupamento por
palavra-chave; o pixel também preserva esse parâmetro quando presente na
URL. O Router pode encaminhar ambos os campos junto do pedido.
Envie commission.currency com a moeda original da cobrança e todos os valores em centavos dessa moeda, incluindo produtos, taxas e reembolsos. A moeda não é inferida pelo país, idioma ou símbolo $. Exemplo: uma venda de US$ 100 usa USD e totalPriceInCents: 10000. Não converta antes de enviar. O dashboard converte vendas, custos, despesas e gastos Meta para sua moeda configurada (BRL por padrão). A notificação mostra VENDA APROVADA e o bruto convertido nessa mesma moeda. A barra de faturamento do usuário usa BRL.
Usamos a cotação diária mais recente de ExchangeRate-API, inclusive em períodos anteriores. A data fica no relatório; os totais podem mudar quando a cotação atualiza. O valor original é preservado e exportado junto da cotação. Conversões não representam a taxa de liquidação do checkout. Sem cotação válida, o relatório informa indisponibilidade e os avisos aguardam nova tentativa. Os eventos enviados à Meta preservam a moeda original da venda.
3. Atualizações e reembolsos
eventId identifica uma atualização e deve permanecer igual em cada tentativa. sourceUpdatedAt é o horário da mudança na origem e também deve permanecer igual nas tentativas. Um novo estado recebe novo eventId e versão mais recente. createdAt, moeda, ambiente, plataforma e primeira approvedDate não podem mudar. Use identificadores de pedido únicos por loja. A aprovação pode preceder a criação do registro do pedido na Shopify; preserve o horário real do pagamento. Criação e aprovação não podem ser posteriores a sourceUpdatedAt, e o reembolso não pode preceder a aprovação.
Reembolso parcial mantém status paid, informa refundedAt e refundedAmountInCents acumulado. Reembolso total usa refunded e o total do pedido. Chargeback usa chargedback e reverte toda a receita no painel. O valor reembolsado não pode diminuir. Reembolsos atualizam o painel e cancelam envios pendentes; não desfazem automaticamente um Purchase já recebido pela Meta.
O período financeiro usa a data de aprovação no fuso do dashboard. Uma reversão recalcula a venda na data original de aprovação, não cria uma despesa no dia da devolução. Custos de produto e taxa de gateway enviada permanecem nas reversões. Regras têm vigência; editar a vigência pode alterar o histórico.
4. Respostas, repetição e recibo
202 {"success":true,"result":"accepted","receiptId":"rcp_...","orderId":"loja-a:pedido-123","deliveryStatus":"check_receipt"}
200 {"success":true,"result":"duplicate", ...}
200 {"success":true,"result":"ignored_stale", ...}
GET /v1/order-events/SEU_EVENT_ID
x-api-token: SUA_CHAVE
202 confirma persistência no iTracker. A fila entrega à Meta separadamente; consulte o recibo ou a tela de eventos. 409 aponta conflito de identificador, versão ou transição. 422 indica campo inválido, 401 chave inválida, 429 limite de requisições. Em erros de rede, 429 ou 5xx repita o mesmo evento com o mesmo conteúdo e aguarde progressivamente. Não repita automaticamente 4xx de validação.
A primeira aprovação gera um Purchase com identificador estável, uma vez por destino configurado. Dados antigos de teste não são enviados para a Meta. Um pedido que chega pela primeira vez já parcialmente reembolsado não gera Purchase. Cadastre o destino antes de receber as vendas; adicionar um destino não reenvia o histórico automaticamente. Se houver vários pixels no dashboard, informe trackingContext.pixelId; não há escolha aleatória de pixel.
5. Instalação do pixel
Em Pixels → Adicionar Pixel, cadastre o nome, os destinos Meta (ID e token) e os domínios da oferta. O cadastro e todos os destinos são salvos juntos; depois, copie o script gerado. O token não aparece no script nem na configuração pública. Os pixels antigos continuam usando o mesmo identificador e script.
Habilite Lead e AddToCart para usar iTracker.track('Lead') e iTracker.track('AddToCart'). InitiateCheckout aceita regras por texto, seletor CSS ou URL, com um valor por linha, e detecção opcional por palavras-chave. No modo explícito, chame iTracker.track('InitiateCheckout'). Purchase continua exclusivo da API e apenas para vendas aprovadas.
A regra de produtos determina quais pedidos enviam Purchase ao destino; sem seleção, qualquer produto é aceito. O valor do evento corresponde ao total bruto do pedido ou à comissão, conforme a configuração do pixel. Essa escolha não altera o faturamento e as notificações de vendas do iTracker. Para enviar o IP real do comprador, informe trackingContext.ip (IPv4 ou IPv6) na API e habilite a opção no pixel. Não informe o IP do servidor do checkout. Sem um IP válido recebido, ele não é enviado; o script não faz consulta externa de IP.
<script src="https://SEU-ITRACKER/sdk.js" data-pixel-id="px_SEU_PIXEL" defer></script>
Cadastre exatamente os domínios autorizados da oferta e checkout, incluindo protocolo e porta se houver. O pixel inicia em produção. Se exigir consentimento, chame a API abaixo somente depois do aceite do visitante e do evento itracker:ready.
// Execute após sua gestão de consentimento e após carregar o pixel:
window.iTracker.consent(true);
window.iTracker.track('Lead');
window.iTracker.track('InitiateCheckout');
const contexto = window.iTracker.getContext('px_SEU_PIXEL');
// Salve contexto.trackingId e contexto.pixelId junto ao pedido.
// Revogação: window.iTracker.consent(false)
PageView e ViewContent são registrados por página. AddToCart, Lead e InitiateCheckout podem ser enviados explicitamente. Configure detecção de botão por texto, trecho de URL ou seletor CSS para InitiateCheckout. O navegador não aceita Purchase. Para a mesma página e operação, use uma única instalação.
Os links e formulários de checkouts autorizados recebem UTMs, itrk e itrk_pixel. O Router deve preservar esses campos desde a entrada até a venda; mapeie itrk para trackingContext.trackingId e itrk_pixel para trackingContext.pixelId. No pagamento fora do navegador, como confirmação posterior de Pix, recupere o contexto salvo no pedido.
Uma visita com trackingId válido tem preferência sobre as UTMs enviadas na venda, em janela de sete dias. Fora da janela, usam-se as UTMs. Para identificar campanha, conjunto e anúncio, utilize IDs numéricos puros ou no final de um nome separados por |. utm_term representa o posicionamento.
6. Meta
O pixel próprio agrupa destinos Meta. Para cada destino, cadastre ID Meta, token CAPI e versão Graph habilitada no seu aplicativo. Em produção, o navegador e o servidor compartilham event_name e event_id nos eventos de navegação. Purchase é exclusivamente servidor. Os destinos ativos enviam eventos reais; para interromper o envio, desative o destino.
O login por perfil exige META_APP_ID, META_APP_SECRET, META_GRAPH_VERSION e META_LOGIN_CONFIG_ID configurados no servidor e a URL /meta/callback cadastrada na Meta. A configuração Business Login deve conceder somente ads_read para leitura de anúncios. Permissões e acesso às contas dependem do aplicativo e da Meta. O link para outro navegador dura quinze minutos e autoriza apenas a operação onde foi criado. Nunca solicita senha do Facebook no iTracker.
Contas selecionadas alimentam os gastos. Sincronize até 31 dias por vez; o fuso dos insights é o da conta Meta. Consulte campanhas, conjuntos, anúncios, status e orçamentos. Esta versão é de leitura e monitoramento; alterações de campanhas são feitas no Gerenciador de Anúncios da Meta. O pixel próprio, a API de vendas, a atribuição e as notificações continuam disponíveis em cada dashboard.
7. Router
O projeto inclui o adaptador integrations/commerce-router.mjs. Configure ITRACKER_URL e ITRACKER_API_KEY no servidor do Router. O cliente não deve usar a chave da UTMify no endpoint do iTracker. Configure um novo destino e preserve a associação da visita com o pedido. O Router em produção só passa a enviar após essa integração ser instalada e habilitada.