Totais do período

GET

/v1/t/{tenantID}/summary

curl --request GET \
  --url https://dash.owiew.com/v1/t/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/summary \
  --header 'Authorization: Bearer <token>'

• Produção

O agregado da tela inicial numa resposta só: série diária (points), campanhas, contas, conversões, revisões e ritmo de orçamento da janela pedida. É a rota por onde começar.

Blocos restritos são omitidos, não negados. Os que o papel da chave não alcança (account.read, audit.read, budget.read) vêm vazios e listados em omitted: lista vazia não prova ausência de dado.

Exige a permissão insights.read.

Authorizations

• tokenDeAcesso

Parameters

Path Parameters

tenantID

required

string format: uuid

O cliente. Vem SEMPRE do caminho — nunca de cabeçalho, nunca de cookie. Ele é conferido contra o token: um identificador que não bata com o do token devolve 403, e não uma resposta vazia.

Query Parameters

since

string format: date

Primeiro dia, AAAA-MM-DD. Omitido, o servidor escolhe uma janela padrão — não presuma qual: peça explicitamente sempre que o número for comparado com outro.

until

string format: date

Último dia, AAAA-MM-DD. Inclusivo.

Responses

200

OK

Media typeapplication/json

O agregado devolvido por /summary.

object

tenant

O cliente do token.

object

role

string

permissions

Array<string>

omitted

Permissões que a chave não tem; os blocos delas vêm vazios.

Array<string>

since

string format: date

until

string format: date

points

Array

object

spend_micros

Investimento em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

impressions

Impressões.

integer format: int64

clicks

Cliques.

integer format: int64

conversions_micros

Conversões, TAMBÉM EM MICROS. A plataforma reporta conversões fracionárias (atribuição parcial), então a contagem não é inteira. Divida por 1.000.000 para ter o número de conversões. Exibir este campo cru já produziu um painel anunciando ‘75 milhões de conversões’ onde havia 75.

integer format: int64

conversion_value_micros

Valor das conversões reportado pela plataforma em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

currency

Moeda da CONTA, código ISO-4217. Contas de moedas diferentes NÃO podem ser somadas sem conversão — o total viria numericamente certo e semanticamente sem sentido.

string

revisions

Quantas alterações retroativas afetam este recorte. Maior que zero significa que a plataforma mudou números que já havia reportado.

integer

date

O dia, no fuso da CONTA de anúncio e não em UTC. É por isso que o total de um mês pode divergir da soma de trinta dias vindos de contas em fusos diferentes.

string format: date

campaigns

Array

object

spend_micros

Investimento em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

impressions

Impressões.

integer format: int64

clicks

Cliques.

integer format: int64

conversions_micros

Conversões, TAMBÉM EM MICROS. A plataforma reporta conversões fracionárias (atribuição parcial), então a contagem não é inteira. Divida por 1.000.000 para ter o número de conversões. Exibir este campo cru já produziu um painel anunciando ‘75 milhões de conversões’ onde havia 75.

integer format: int64

conversion_value_micros

Valor das conversões reportado pela plataforma em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

currency

Moeda da CONTA, código ISO-4217. Contas de moedas diferentes NÃO podem ser somadas sem conversão — o total viria numericamente certo e semanticamente sem sentido.

string

revisions

Quantas alterações retroativas afetam este recorte. Maior que zero significa que a plataforma mudou números que já havia reportado.

integer

campaign_id

O identificador na plataforma. É a ÚNICA chave estável: nome de campanha muda, e casar por nome já produziu atribuição errada neste sistema quando dois clientes usaram o mesmo nome.

string

campaign_name

string

provider

Rede de anúncio da campanha.

string

budget_kind

Onde mora o orçamento: na campanha (daily/lifetime) ou nos conjuntos (none).

string

Allowed values: daily lifetime none

account_id

Conta de anúncio de origem.

string

days

Quantos dias do período tiveram entrega desta campanha.

integer

accounts

Array<object>

Uma conta de anúncio do cliente. O par last_date / last_observed_at é o que distingue ‘a campanha caiu’ de ‘a coleta parou’ — a segunda hipótese é a mais comum e a que ninguém checa.

object

account_id

string

provider

Rede de anúncio de origem.

string

Allowed values: meta google tiktok

name

Nome da conta na plataforma. Cai no identificador quando a estrutura ainda não foi lida — nunca vem vazio.

string

timezone

Fuso em que os dias desta conta são contados.

string

last_date

Último DIA com dado. Nulo quando a conta nunca entregou nada.

string format: date

nullable

last_observed_at

Quando a coleta falou com esta conta pela última vez. Diferente de last_date: uma conta coletada há dez minutos pode ter dados só até anteontem, e isso é normal.

string format: date-time

nullable

conferida_via

Por onde last_observed_at foi conferido: direta (trilha da API da própria rede) ou ga4 (coleta do Google Analytics 4, enquanto a API do Google Ads não está liberada). Nulo quando a conta nunca foi conferida.

string

nullable

Allowed values: direta ga4

revisions

Array<object>

Uma alteração retroativa: a plataforma mudou um número já reportado.

object

date

string format: date

campaign_id

string

campaign_name

string

field

O campo que mudou.

string

previous

string

nullable

current

string

nullable

delta

integer format: int64

nullable

observed_at

string format: date-time

lag_days

Dias entre o fato e a observação da mudança.

integer

restatement

Verdadeiro para reapuração retroativa; falso para acúmulo do dia corrente.

boolean

reason

A causa provável da alteração.

string

pacing

Array<object>

object

restatements

integer format: int64

total_revisions

integer format: int64

conversions

Array<object>

O total de uma categoria de conversão. Só entram ações canônicas: a mesma venda reportada por mais de um tipo de ação não é contada duas vezes.

object

kind

Como este cliente classificou a ação. O que estiver como não classificado NÃO entra em total nenhum, de propósito.

string

count_micros

Volume, em micros — divida por 1.000.000 em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

value_micros

Valor atribuído em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

currency

Moeda ISO-4217.

string

outcome

Verdadeiro para resultado de negócio (compra, lead, conversa); falso para métrica de meio de caminho (engajamento, clique, vídeo).

boolean

types

Os tipos de ação, com o nome da rede, que compõem o total.

Array<string>

conversion_details

Array<object>

Uma linha do detalhe por tipo de ação, com o papel que explica por que ela soma ou não.

object

action_type

O nome da ação na plataforma.

string

kind

Como este cliente classificou a ação.

string

role

O papel da linha no total (ex.: canônica).

string

count_micros

Volume, em micros — divida por 1.000.000 em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

value_micros

Valor atribuído em MICROS: divida por 1.000.000 para obter o valor na moeda. 1.500.000 é 1,50. Nunca use ponto flutuante para converter — multiplique e divida como inteiro.

integer format: int64

caveats

Selos de qualidade do dado.

object

Example

{
  "campaigns": [
    {
      "budget_kind": "daily"
    }
  ],
  "accounts": [
    {
      "provider": "meta",
      "conferida_via": "direta"
    }
  ]
}

401

Token ausente, malformado ou vencido.

Media typeapplication/json

object

error

object

code

Código estável, seguro para comparar.

string

message

Texto para pessoa. Pode mudar entre versões — não decida nada a partir dele.

string

trace_id

Identificador da ocorrência. Cite-o ao pedir suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "trace_id": "example"
  }
}

403

O token é válido, e o escopo não. Ou ele foi emitido para outro cliente, ou o papel não inclui a permissão da rota. NÃO é 404 de propósito: esconder um erro de escopo atrás de ‘não encontrado’ faz quem integra procurar o problema no lugar errado.

Media typeapplication/json

object

error

object

code

Código estável, seguro para comparar.

string

message

Texto para pessoa. Pode mudar entre versões — não decida nada a partir dele.

string

trace_id

Identificador da ocorrência. Cite-o ao pedir suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "trace_id": "example"
  }
}