> ## Documentation Index > Fetch the complete documentation index at: https://docs.utmify.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Consulta de dados > Leitura programática das métricas de um dashboard — o equivalente ao Resumo da Utmify. > 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 ```text theme={null} https://query-api.utmify.com.br ``` ### 1.2 Endpoint ```text theme={null} 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: ```json theme={null} { "Authorization": "Bearer " } ``` **Ou** ```json theme={null} { "x-api-key": "" } ``` ### 1.4 Body Todos os campos são **opcionais**. ```json theme={null} { "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). ```json theme={null} { "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: ```json theme={null} { "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) ```bash theme={null} 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) ```javascript theme={null} 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) ```python theme={null} 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 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. 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. 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. 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). 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. 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.