API

Envio de vendas

Uma chamada por evento do pedido. O UTMizey liga a venda ao anúncio que a originou e devolve o resultado no painel.

Já envia vendas para outra ferramenta de rastreamento? Compare os campos abaixo com o que você envia hoje. O contrato segue o padrão mais usado no mercado, e na maior parte dos casos basta trocar o endereço e o token.

Endpoint

POST https://www.utmizey.com.br/v1/orders
Content-Type: application/json
x-api-token: SEU_TOKEN

O token é gerado em Integrações → Webhooks → Credenciais de API, no painel. Ele é exibido uma única vez e não pode ser recuperado depois; se perder, gere uma nova credencial.

É o token que determina em qual dashboard a venda é registrada. O corpo da requisição não define o destino.

Corpo

Campo	Tipo	Obrigatório	O que é
orderId	string	sim	Identificador do pedido na sua plataforma. É a chave: reenviar o mesmo orderId atualiza a venda em vez de duplicar.
platform	string	não	Nome da plataforma de origem, como aparece no painel. Padrão: "api".
status	enum	sim	Estado do pedido agora. Valores abaixo.
paymentMethod	enum	não	Meio de pagamento. Valor fora da lista vira nulo, não erro.
createdAt	data	sim	Quando o pedido foi criado.
approvedDate	data	não	Quando foi aprovado. Obrigatório na prática para status paid: é dele que sai a data do faturamento.
refundedAt	data	não	Quando foi estornado ou sofreu chargeback.
isTest	boolean	não	Marca a venda como teste. Ela entra, mas fica fora do Resumo e dos relatórios.
commission	objeto	sim	Os valores da venda. Detalhado abaixo.
customer	objeto	não	O comprador. Melhora a correspondência do evento na Meta.
trackingParameters	objeto	não	De onde veio a venda. É o que liga o pedido ao anúncio.
products	lista	não	Itens do pedido.

Datas

Dois formatos, os dois em UTC:

"2026-09-02 14:30:00"        data e hora separadas por espaço
"2026-09-02T14:30:00.000Z"   ISO 8601

Data em formato inválido é tratada como ausente. Em createdAt, que é obrigatório, isso devolve 400: uma venda com data incorreta seria contabilizada no dia errado do relatório, sem nenhum sinal de erro.

status

Valor	Quando usar
waiting_payment	Pix ou boleto gerado, aguardando pagamento.
paid	Pagamento confirmado. É o que vira faturamento.
refused	Cartão recusado, pagamento negado.
refunded	Reembolsado.
chargedback	Chargeback.

Valor fora desta lista devolve 400 status_invalido. Um status desconhecido nunca é interpretado por aproximação: tratar uma venda recusada como aprovada inflaria o faturamento sem nenhum sinal.

paymentMethod

credit_card   boleto   pix   paypal   free_price

commission

Todos os valores em centavos, como número inteiro. R$ 97,00 é 9700.

Campo	Tipo	O que é
totalPriceInCents	inteiro	O que o comprador pagou.
gatewayFeeInCents	inteiro	A taxa da plataforma.
userCommissionInCents	inteiro	O que sobra para o produtor. É daqui que sai o Faturamento líquido e o Lucro.
currency	string	Moeda. Padrão "BRL".

Se você não tem a comissão

Omita userCommissionInCents e nós usamos totalPriceInCents menos gatewayFeeInCents. Comissão zero é aceita: recusá-la derrubaria vendas reais de quem só tem o total. Se a sua plataforma não informa taxa nenhuma, cadastre a taxa por venda na tela de Taxas — assim o Lucro desconta o que a plataforma cobra em vez de sair inflado.

customer

Campo	Tipo	O que é
name	string	Nome do comprador.
email	string	E-mail. Guardado só como hash.
phone	string	Telefone. Guardado só como hash.
ip	string	IP do comprador no checkout.
country	string	País, sigla de duas letras ("BR").

Nada aqui é obrigatório, e nada aqui é guardado em texto puro: e-mail e telefone viram hash antes de tocar o banco. Mandá-los melhora a correspondência do evento de compra na Meta, que é o que faz a otimização da campanha enxergar a venda.

trackingParameters

Campo	O que é
utm_source, utm_medium, utm_campaign, utm_content, utm_term	As UTMs que chegaram no checkout.
src	Campo livre de origem.
sck	Campo livre. É o mais importante desta lista — leia abaixo.

Por que o sck decide a atribuição

O script do UTMizey na página de vendas registra o clique e escreve um identificador no sck, no formato u1.<id>. Quando ele volta nesta chamada, a venda é ligada ao clique original — e com ele vêm campanha, conjunto, anúncio e posicionamento, além dos parâmetros que a Meta usa para casar o evento.

Sem o sck, sobram as UTMs que você mandar. Elas resolvem o faturamento, mas a atribuição por anúncio fica pela metade — e devolver o campo livre sem alterá-lo é a coisa mais barata que uma plataforma pode fazer para o cliente dela.

products

Campo	Tipo	O que é
id	string	Identificador do produto.
name	string	Nome do produto.
planId	string	Identificador do plano, em assinatura.
planName	string	Nome do plano.
quantity	inteiro	Quantidade. Mínimo 1.
priceInCents	inteiro	Preço unitário em centavos.

Exemplo

curl -X POST https://www.utmizey.com.br/v1/orders \
  -H "Content-Type: application/json" \
  -H "x-api-token: SEU_TOKEN" \
  -d '{
    "orderId": "PED-10293",
    "platform": "MinhaPlataforma",
    "status": "paid",
    "paymentMethod": "pix",
    "createdAt": "2026-09-02 14:28:11",
    "approvedDate": "2026-09-02 14:30:02",
    "commission": {
      "totalPriceInCents": 9700,
      "gatewayFeeInCents": 485,
      "userCommissionInCents": 9215,
      "currency": "BRL"
    },
    "customer": {
      "name": "Maria Souza",
      "email": "maria@exemplo.com",
      "phone": "5511999998888",
      "ip": "189.4.10.22",
      "country": "BR"
    },
    "trackingParameters": {
      "sck": "u1.9f2c8a1e-4b7d-4c11-9a03-77e5b0d1c2aa",
      "utm_source": "FB",
      "utm_campaign": "Escala Setembro|1203948",
      "utm_medium": "Publico Frio|9384756",
      "utm_content": "Criativo 12|8837261",
      "utm_term": "Instagram_Reels"
    },
    "products": [
      { "id": "curso-01", "name": "Curso Completo", "quantity": 1, "priceInCents": 9700 }
    ]
  }'

Respostas

200  { "ok": true, "order_id": "...", "attribution": "click" }

attribution diz de onde saiu a campanha: click (o sck achou o clique registrado), utm (veio do que você mandou) ou none.

Código	Erro	O que houve
401	missing_api_token	Faltou o cabeçalho x-api-token.
401	invalid_api_token	Token errado, revogado ou desativado.
400	invalid_json	O corpo não é JSON.
400	corpo_invalido	O corpo não é um objeto.
400	campo_obrigatorio	Faltou orderId ou createdAt. O campo vem em "field".
400	status_invalido	O status não é um dos cinco valores.
500	persist_failed	Falha nossa ao gravar. Reenvie.

Reenvio

Reenviar é seguro e esperado. O mesmo orderId atualiza a venda, e a ordem entre as chamadas é decidida pelo estado que cada uma afirma — não pela hora em que chegou. Um evento antigo que chega depois do novo é registrado e ignorado, com { "ignored": "stale_event" } na resposta: um "pendente" atrasado nunca derruba um "pago" que já entrou.

Em 500, reenvie. Em 400, não: o payload precisa mudar antes. Todas as chamadas, com erro ou sem, ficam na tela de Eventos do painel — é lá que o cliente confere se a venda chegou.