Consulta de dados

Consulte, de forma programática, as métricas de um dashboard — a mesma informação da tela de Resumo. Autenticação por chave de API (sem token que expira). Todos os valores monetários são retornados em centavos, na moeda do dashboard.

Antes de começar

Com uma chave de API gerada dentro da sua Utmify você consulta as métricas de um dashboard. A chave cobre os dashboards que você escolher ao criá-la (uma lista específica ou todos).

Pré-requisitos e acesso

Plano elegível: Monster, Scale ou Enterprise (inclui Monster+ e variantes Global/Latam).
Acesso liberado no beta fechado (allowlist manual da Utmify).
A elegibilidade é revalidada a cada requisição: se o plano cair para um não elegível, ou a conta for bloqueada/desativada, a chave para de funcionar na hora.

Onde pegar seu token

Dentro da Utmify, siga o caminho:

Avançado → card API Oficial → Novo Token

Dê um nome ao token e escolha o escopo: “Todos os dashboards” (inclusive futuros) ou selecione dashboards específicos.
O token é exibido uma única vez na criação. Copie e guarde com segurança — é um segredo; não exponha em código de front-end ou repositórios públicos.
Você pode ter até 3 tokens; dá para ativar/desativar ou revogar cada um a qualquer momento pelo mesmo card.

1. Formato da Requisição

1.1 Base URL

https://query-api.utmify.com.br

1.2 Endpoint

POST /public-api/v1/dashboards/{dashboardId}/summary

Retorna as métricas gerais do dashboard no período/filtros informados. O {dashboardId} precisa estar no escopo da chave e pertencer ao dono dela.

1.3 Headers

Envie a chave em um dos headers abaixo:

{
  "Authorization": "Bearer <sua_chave>"
}

{
  "x-api-key": "<sua_chave>"
}

1.4 Body

Todos os campos são opcionais.

{
  "from?": "ISO 8601",          // ex.: "2026-06-01T00:00:00-03:00"
  "to?": "ISO 8601",            // ex.: "2026-06-23T23:59:59-03:00"
  "productNames?": string[],
  "platforms?": string[],
  "metaAdAccountIds?": string[],
  "googleAdAccountIds?": string[],
  "kwaiAdAccountIds?": string[],
  "tikTokAdAccountIds?": string[],
  "taboolaAdAccountIds?": string[],
  "trafficSource?": "Meta" | "Google" | "Kwai" | "TikTok" | "Taboola"
}

2. Descrição dos Parâmetros

2.1 Headers

Parâmetro	Exemplo	Descrição
Authorization	”Bearer SUA_CHAVE_AQUI”	Chave de API no formato Bearer. Use este ou o `x-api-key`.
x-api-key	”SUA_CHAVE_AQUI”	Chave de API. Alternativa ao header `Authorization`.

2.2 Path

Parâmetro	Exemplo	Descrição
dashboardId	”658d716f7e39b6ea213da344”	ID do dashboard a ser consultado. Deve estar no escopo da chave e pertencer ao dono.

2.3 Body

Parâmetro	Exemplo	Descrição
from	”2026-06-01T00:00:00-03:00”	Início da janela de tempo (ISO 8601). Use junto com `to`. Enviar apenas uma das duas retorna 400.
to	”2026-06-23T23:59:59-03:00”	Fim da janela de tempo (ISO 8601). Sem `from`/`to`, retorna todo o período (all-time).
productNames	[“Guia da Pressao”]	Filtra por nome de produto.
platforms	[“Hotmart”, “Kiwify”]	Filtra por plataforma de venda.
metaAdAccountIds	[“act_123456789”]	Filtra gasto/pedidos por conta de anúncio Meta.
googleAdAccountIds	[“123-456-7890”]	Filtra gasto/pedidos por conta de anúncio Google.
kwaiAdAccountIds	[“kwai_123”]	Filtra gasto/pedidos por conta de anúncio Kwai.
tikTokAdAccountIds	[“tt_123”]	Filtra gasto/pedidos por conta de anúncio TikTok.
taboolaAdAccountIds	[“tab_123”]	Filtra gasto/pedidos por conta de anúncio Taboola.
trafficSource	”Meta”	Filtra por origem de tráfego. Uma de: `Meta`, `Google`, `Kwai`, `TikTok`, `Taboola`.

3. Resposta

3.1 Resposta 200

Valores monetários em centavos (ex.: revenue.gross = 12345 = R$ 123,45). Métricas não calculáveis vêm null (ex.: ROAS sem gasto).

{
  "dashboardId": "658d716f7e39b6ea213da344",
  "currency": "BRL",
  "viewType": "Total",
  "period": { "from": "...", "to": "..." },
  "orders": { "total": 0, "approved": 0, "pending": 0, "refunded": 0, "chargedback": 0 },
  "revenue": { "gross": 0, "net": 0, "pending": 0, "refunded": 0, "chargeback": 0 },
  "ads": {
    "spend": 0,
    "byPlatform": { "meta": 0, "google": 0, "kwai": 0, "tiktok": 0, "taboola": 0 },
    "clicks": 0,
    "pageViews": 0,
    "initiateCheckouts": 0,
    "leads": 0
  },
  "costs": { "fees": 0, "taxes": 0, "metaAdsTax": 0, "productsCost": 0, "customSpent": 0 },
  "result": {
    "profit": 0,
    "roas": null,
    "roi": null,
    "profitMargin": null,
    "avgTicket": null,
    "cpa": null,
    "arpu": null
  }
}

3.2 Campos da resposta

Grupo	Campos	O que é
orders	total, approved, pending, refunded, chargedback	Contagem de pedidos por status.
revenue	gross, net, pending, refunded, chargeback	Receita/comissão. `gross`/`net` e `refunded`/`chargeback` respeitam o `viewType`; `pending` é sempre líquido.
ads	spend, `byPlatform{ ... }`, clicks, pageViews, initiateCheckouts, leads	Gasto total e por plataforma, mais eventos de tráfego.
costs	fees, taxes, metaAdsTax, productsCost, customSpent	Custos que entram no cálculo do lucro.
result	profit, roas, roi, profitMargin, avgTicket, cpa, arpu	Lucro e indicadores derivados (podem vir `null`).
viewType	Total \| Normal	`Total` = valores brutos; `Normal` = líquidos.

4. Limites e Cache (beta)

Limite	Valor
Requisições por minuto	10 / minuto por chave (burst)
Requisições por dia	10.000 / dia por chave
Chaves por usuário	Máximo de 3

Ao exceder o limite: HTTP 429 com header Retry-After (em segundos) — faça backoff.
Dados em tempo real (to = agora): a resposta pode vir de um cache de curta duração (aproximadamente 2 minutos). Períodos já fechados no passado são sempre exatos. Como a defasagem máxima corresponde à janela do cache, consultas em intervalos muito curtos não retornam dados mais atualizados — recomendamos aguardar ao menos alguns minutos entre requisições ao vivo.

5. Erros

Formato da resposta de erro:

{
  "result": "ERROR",
  "reason": "CODIGO",
  "data": { }
}

HTTP	reason	Quando
401	Unauthorized	Sem chave, ou chave inválida/desabilitada.
403	OFFICIAL_API_NOT_AVAILABLE_FOR_USER	Conta não está na allowlist do beta.
403	OFFICIAL_API_REQUIRES_ELIGIBLE_PLAN	Sem plano elegível ativo (downgrade, cancelamento, bloqueio).
403	API_KEY_HAS_NO_ACCESS_TO_DASHBOARD	Dashboard fora do escopo da chave ou de outro dono.
400	INVALID_DASHBOARD_ID	`dashboardId` malformado.
422	DASHBOARD_MISCONFIGURED	Config do dashboard impede o cálculo (ex.: contas Kwai demais).
429	RATE_LIMIT_EXCEEDED	Estourou o limite por minuto. Veja `Retry-After`.
429	DAILY_QUOTA_EXCEEDED	Estourou a cota diária da chave.
429	RATE_LIMIT_UNAVAILABLE	Indisponibilidade momentânea do limitador; tente de novo.

Backoff: trate respostas 429 aguardando o tempo indicado no header Retry-After antes de tentar novamente. Erros permanentes são retornados como 4xx diferentes de 429 e não devem ser reenviados sem antes corrigir a requisição.

6. Exemplos Práticos

6.1 Consulta com filtro de produto (cURL)

curl -X POST \
  'https://query-api.utmify.com.br/public-api/v1/dashboards/658d716f7e39b6ea213da344/summary' \
  -H 'Authorization: Bearer SUA_CHAVE_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2026-06-01T00:00:00-03:00",
    "to": "2026-06-23T23:59:59-03:00",
    "productNames": ["Guia da Pressao"]
  }'

6.2 Node.js (fetch)

const res = await fetch(
  'https://query-api.utmify.com.br/public-api/v1/dashboards/DASH_ID/summary',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.UTMIFY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: '2026-06-01T00:00:00-03:00',
      to: '2026-06-30T23:59:59-03:00',
    }),
  },
);

const data = await res.json();
console.log(data.result.profit); // lucro em centavos

6.3 Python (requests)

import os, requests

r = requests.post(
    'https://query-api.utmify.com.br/public-api/v1/dashboards/DASH_ID/summary',
    headers={'x-api-key': os.environ['UTMIFY_API_KEY']},
    json={
        'from': '2026-06-01T00:00:00-03:00',
        'to': '2026-06-30T23:59:59-03:00',
    },
    timeout=30,
)
r.raise_for_status()
print(r.json()['revenue']['gross'])  # em centavos

7. Perguntas Frequentes

Qual a diferença dessa API para a API de Envio de Vendas?

A API de Envio de Vendas serve para enviar pedidos para a Utmify. Já a API Oficial de Consulta faz o caminho inverso: permite ler de forma programática as métricas consolidadas de um dashboard — o mesmo que você vê na tela de Resumo.

Como faço para gerar minha chave de API?

No site da Utmify, acesse Avançado, localize o card API Oficial e clique em Novo Token. Disponível apenas para planos elegíveis com acesso ao beta fechado. O token é exibido uma única vez — copie e guarde com segurança.

Por que os valores monetários parecem estar 100x maiores?

Todos os valores monetários são retornados em centavos, na moeda do dashboard. Por exemplo, revenue.gross = 12345 equivale a R$ 123,45. Divida por 100 para obter o valor na moeda.

Recebi um erro 403 OFFICIAL_API_REQUIRES_ELIGIBLE_PLAN. O que significa?

Sua conta não possui um plano elegível ativo. A elegibilidade é revalidada a cada requisição, então um downgrade, cancelamento ou bloqueio faz a chave parar de funcionar imediatamente. Verifique se seu plano é Monster, Scale ou Enterprise (ou variantes).

Recebi um erro 429. O que devo fazer?

Você excedeu o limite de requisições (10 por minuto ou 10.000 por dia por chave). A resposta traz o header Retry-After, indicando quantos segundos aguardar antes da próxima tentativa. Implemente uma estratégia de backoff, respeitando esse intervalo antes de reenviar a requisição.

Os dados vêm em tempo real?

Para períodos fechados no passado os dados são exatos. Para consultas “ao vivo” (com to = agora), a resposta pode vir de um cache de curta duração (~2 minutos), então essa é a defasagem máxima esperada.

​Antes de começar

​Pré-requisitos e acesso

​Onde pegar seu token

​1. Formato da Requisição

​1.1 Base URL

​1.2 Endpoint

​1.3 Headers

​1.4 Body

​2. Descrição dos Parâmetros

​2.1 Headers

​2.2 Path

​2.3 Body

​3. Resposta

​3.1 Resposta 200

​3.2 Campos da resposta

​4. Limites e Cache (beta)

​5. Erros

​6. Exemplos Práticos

​6.1 Consulta com filtro de produto (cURL)

​6.2 Node.js (fetch)

​6.3 Python (requests)

​7. Perguntas Frequentes

Antes de começar

Pré-requisitos e acesso

Onde pegar seu token

1. Formato da Requisição

1.1 Base URL

1.2 Endpoint

1.3 Headers

1.4 Body

2. Descrição dos Parâmetros

2.1 Headers

2.2 Path

2.3 Body

3. Resposta

3.1 Resposta 200

3.2 Campos da resposta

4. Limites e Cache (beta)

5. Erros

6. Exemplos Práticos

6.1 Consulta com filtro de produto (cURL)

6.2 Node.js (fetch)

6.3 Python (requests)

7. Perguntas Frequentes