utmiro

Registre uma venda com uma chamada.

Quando a venda acontece, seu sistema avisa o utmiro. Ele encontra o criativo, a campanha, a conta e o BM de onde ela veio.

Integrando com um agente de IA? Entregue a ele /llms.txt (texto puro) ou a especificação OpenAPI. Só a chave precisa vir de você.

Comece em 3 passos

  1. Crie uma chave em Chaves de API. Ela começa com utm_live_.
  2. Cole as UTMs de cada criativo no anúncio (em Estrutura). Guarde o utm_content do visitante até a compra.
  3. Envie a venda quando ela for confirmada:
curl -X POST https://SEU-DOMINIO/api/v1/conversions \
  -H "Authorization: Bearer $UTMIRO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_url":"https://loja.com/obrigado?utm_content=video-dep-v3-a1b2","value":199.9,"external_id":"pedido_1042"}'

Resposta 201:

{
  "data": {
    "id": "cnv_12",
    "status": "attributed",
    "value": 199.9, "currency": "BRL", "event": "purchase",
    "attribution": { "bm": "Loja Norte", "account": "Conta 14", "campaign": "Lookalike BR", "creative": "Vídeo depoimento v3" }
  }
}

Confirme a chave antes de tudo com GET /api/v1/me.

Em outras linguagens

Node

await fetch("https://SEU-DOMINIO/api/v1/conversions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.UTMIRO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ utm_content, value: 199.9, external_id: order.id }),
});

Python

requests.post(
    "https://SEU-DOMINIO/api/v1/conversions",
    headers={"Authorization": f"Bearer {os.environ['UTMIRO_KEY']}"},
    json={"utm_content": utm_content, "value": 199.9, "external_id": order.id},
)

Campos da venda

CampoO que é
utm_contentCódigo do criativo. É o que atribui a venda por completo.
page_urlAlternativa: a URL da página de compra. As utm_* da query são lidas sozinhas.
utm_campaignSe só ele vier, a venda fica atribuída até a campanha (partial).
valueEm unidades da moeda: 199.9 é R$ 199,90.
currencyCódigo de 3 letras. Padrão BRL.
external_idId do pedido no seu sistema. Enviar de novo devolve 200 com duplicate: true, sem duplicar.
occurred_atISO 8601. Padrão: agora.

O status da resposta é attributed, partial ou unattributed. Vendas sem origem são guardadas mesmo assim, e a resposta traz um hint.

Erros

Todo erro tem o mesmo formato, com uma dica de como corrigir:

{ "error": { "code": "validation_failed", "message": "Alguns campos são inválidos.",
    "hint": "Corrija os campos listados em fields e envie de novo.",
    "fields": { "value": "Número maior ou igual a 0" }, "docs": "/docs#validation_failed" } }
missing_api_key401Faltou o header Authorization: Bearer … Crie uma chave em Chaves de API e envie no header.
invalid_api_key401Chave errada ou revogada. Copie de novo ou crie outra chave.
invalid_json400O corpo não é um objeto JSON. Envie Content-Type: application/json.
validation_failed422Um campo está inválido. Veja `fields`: cada chave diz o que corrigir.

Outros endpoints

GET /api/v1/meConfirma que a chave funciona.
GET /api/v1/structureCriativos com as UTMs de cada um.
GET /api/v1/conversionsVendas, mais recentes primeiro. limit e before para paginar.