Checkout sem integração pronta: como mandar as vendas por API e saber qual anúncio vendeu

Hotmart, Kiwify, Cakto e Wiapy têm integração pronta: é colar um endereço e as vendas começam a chegar. Mas muita venda acontece em outro lugar — um checkout feito sob medida, um bot que vende pelo WhatsApp ou pelo Telegram, um sistema interno, uma plataforma nova que ninguém integrou ainda.

Para esses casos existe a API de envio de vendas: o seu sistema avisa o UTMizey a cada mudança num pedido, e a venda entra no painel ligada ao anúncio que a trouxe, como qualquer outra. Este texto explica quando usar, o que mandar e os dois cuidados que separam uma integração tranquila de uma que dá dor de cabeça.

Antes da API: confira se a sua plataforma está na lista

Em Integrações → Webhooks há mais de cem plataformas de venda — a lista aberta está em plataformas compatíveis. Todas podem ser ligadas por webhook, mesmo as que ainda não têm leitura conferida por nós: nesse caso, a primeira venda aparece nos seus avisos para você comparar o valor com o painel da plataforma, e o que não puder ser lido com segurança fica registrado em Eventos em vez de entrar no Resumo.

A API é o caminho quando você controla o que é enviado: o checkout é seu, o bot é seu, ou a ferramenta que você usa permite configurar uma chamada para fora com os campos que quiser.

Já manda vendas para a Utmify?

O contrato da API é compatível com o formato usado pela Utmify: os mesmos nomes de campo e o mesmo cabeçalho de autenticação. Na maior parte dos casos, migrar é trocar o endereço e o token — o resto da integração fica como está. (O UTMizey não tem vínculo, parceria ou endosso da Utmify; a menção serve para dizer o que a integração exige de quem já a construiu.)

Como funciona

• Uma chamada por mudança no pedido. Pix gerado é uma chamada; o pagamento confirmado é outra, com o mesmo orderId; um reembolso, mais uma. O mesmo id atualiza a venda em vez de duplicar.
• O token decide o painel. Ele é gerado em Integrações → Webhooks → Credenciais de API, vai no cabeçalho x-api-token e aparece uma vez só — guarde na hora. Nada no corpo da chamada escolhe para qual painel a venda vai.
• Dinheiro em centavos. R$ 97,00 vai como 9700, sem vírgula nem ponto.

Um status fora dessa lista é recusado, e não interpretado por aproximação: tratar uma recusa como aprovação inflaria o faturamento sem ninguém perceber.

O valor que vira lucro

Cada chamada leva o que o comprador pagou, a taxa da plataforma e o que sobrou para você (userCommissionInCents). É esse último que vira faturamento líquido e lucro no painel. Se o seu sistema não tem a comissão, mande o total e a taxa, e o UTMizey faz a conta. Se não tem nem a taxa, cadastre a taxa por venda na tela de Taxas — senão o lucro sai maior do que é.

Para testar sem sujar o painel, mande isTest: true. A venda é registrada, mas fica fora do Resumo, dos relatórios e da contagem do plano.

A parte que liga a venda ao anúncio

Sem origem, a API vira um extrato: você vê que vendeu, não sabe por quê. O que faz a ligação é o bloco trackingParameters, e há dois jeitos de preenchê-lo.

• Pelo sck. Se o comprador passou por uma página com o script do UTMizey, o script escreve no sck um identificador que começa com u1.. Mandado de volta na chamada, ele liga a venda ao clique registrado — com campanha, conjunto, anúncio e os identificadores que a Meta usa para casar a compra com a pessoa.
• Pelas UTMs. Mande as UTMs com que o comprador chegou. Se o anúncio usa o formato nome|id — o do código de UTMs do painel —, o UTMizey separa o id e coloca a venda na mesma linha do gasto daquele anúncio.

Como fica uma chamada

O corpo de uma venda aprovada, com o mínimo que vale a pena mandar:

{
  "orderId": "PED-10293",
  "platform": "MeuCheckout",
  "status": "paid",
  "paymentMethod": "pix",
  "createdAt": "2026-10-21 14:28:11",
  "approvedDate": "2026-10-21 14:30:02",
  "commission": {
    "totalPriceInCents": 9700,
    "gatewayFeeInCents": 485,
    "userCommissionInCents": 9215,
    "currency": "BRL"
  },
  "trackingParameters": {
    "utm_source": "FB",
    "utm_campaign": "Escala Outubro|1203948",
    "utm_medium": "Publico Frio|9384756",
    "utm_content": "Criativo 12|8837261"
  }
}

O endereço, os campos do comprador, os itens e todos os códigos de resposta estão na documentação da API de envio de vendas.

Reenviar sem duplicar — e sem rajada

Reenviar é seguro: o mesmo orderId atualiza a venda, e um evento antigo que chega depois do novo é registrado e ignorado. Um “pendente” atrasado nunca derruba um “pago” que já entrou.

Toda chamada, com erro ou sem, aparece na tela de Eventos do painel. É o primeiro lugar para olhar quando uma venda não apareceu.

Em uma frase

Se a venda acontece num lugar sem integração pronta, o seu sistema avisa cada mudança do pedido pela API — com a comissão e com a origem — e o painel trata essa venda como trataria uma da Hotmart.