Consultar analytics pela API

As sete consultas estão em homologação em https://api.staging.agilink.io/v1/analytics/. Use sessão humana ou chave com analytics:read e acesso ao aplicativo. Cada consulta revalida o usuário, a credencial e o app. Outro proprietário ou aplicativo fora da concessão recebe 404. A API de leitura não concede poder de enviar telemetria ou alterar links.

Referência com requests e responses · Significado dos indicadores · OpenAPI administrativo.

Parâmetros comuns

Parâmetro	Regra
appId	Obrigatório; aplicativo autorizado
start, end	Obrigatórios; RFC 3339 com segundos e offset/Z, até três casas decimais; início inclusivo e fim exclusivo
timezone	Nome reconhecido pelo Postgres; padrão America/Sao_Paulo
group	all, main ou operational; classificação atual do link
linkId	ID composto válido de um link atual do mesmo app
domain, prefix	Filtros exatos; prefixo vazio seleciona links sem prefixo
device	android, ios, desktop ou unknown
source	Origem normalizada em minúsculas, sem espaços nas pontas; máximo 200 caracteres
country	Código de duas letras, normalizado em maiúsculas, ou unknown

O período máximo é 366 dias. A recuperação admite somente app, período, timezone, grupo, link, domínio e prefixo; dispositivo/origem/país não existem em sua fonte e são recusados. Query desconhecida ou parâmetro repetido retorna 400. Valores inválidos ou período excessivo retornam 422. Envie URLs com seus parâmetros codificados.

curl --get 'https://api.staging.agilink.io/v1/analytics/summary' \
  --header 'Authorization: Bearer <credencial>' \
  --data-urlencode 'appId=app_loja' \
  --data-urlencode 'start=2026-10-01T00:00:00Z' \
  --data-urlencode 'end=2026-10-02T00:00:00Z' \
  --data-urlencode 'timezone=America/Sao_Paulo'

O exemplo usa IDs fictícios. Instantes são normalizados para UTC na resposta. Nenhuma dessas consultas requer Idempotency-Key ou If-Match. As respostas administrativas usam Cache-Control: no-store, no-transform.

Cada consulta

Endpoint	Resultado e parâmetros próprios
/summary	Totais separados por tipo, únicos globais de cliques, cliques identificados, links com eventos e primeiro/último evento do conjunto
/timeseries	Buckets esparsos e ordenados, com os seis contadores; granularity hour/day/month/year, padrão day. Hour limita o período a 31 dias
/breakdown	dimension obrigatório: device/source/country/eventType/producer/entryMethod. eventType padrão click; pode ser all ou um dos quatro tipos. limit até 100; truncated informa corte
/top-links	Ranking de cliques com únicos por link, ordenado por cliques decrescentes e ID crescente no desempate; cursor e limit
/events	Eventos autorizados, com projeção explícita e sem hash/IP/cidade/payload bruto; eventType padrão click, também aceita all. Ordenação por instante e ID decrescentes; cursor e limit
/native	Aberturas, conteúdo, legado e coorte de confirmação em 24 horas; separa aberturas maduras e provisórias
/recovery	Emissões e etapas de tokens retidos, sem expor token/hash/claim/contexto; não representa toda recuperação do produto

País e origem podem faltar na fonte, especialmente em eventos nativos. Não infira dados ausentes a partir de outros eventos. Dimensões recebem unknown de forma explícita. A semântica completa de coorte, retenção e únicos está no guia das métricas.

Paginação

Ranking e eventos usam limit entre 1 e 100, padrão 50, e retornam pagination.hasMore/nextCursor. Preserve app, período, timezone, filtros e limite ao usar o cursor. Ele é assinado e vinculado à credencial e ao contexto; alteração, adulteração ou expiração retorna 400 invalid_cursor. A continuação de eventos preserva a precisão SQL do instante, incluindo microssegundos, sem perder eventos que compartilham um milissegundo.

A paginação não é um snapshot permanente do banco. Eventos atrasados, alteração do grupo ou exclusão de link podem modificar uma consulta seguinte e a posição do ranking. Para atualizar o resultado, recomece sem cursor. Breakdown fornece um corte por limite e sinaliza truncated; ele não oferece cursor. Uma série vazia é uma lista vazia de buckets, não um erro.

Cálculo, cobertura e carga

A fonte desta versão é event_rows; contadores diários e agregados históricos não são unidos aos eventos. A recuperação usa retained_recovery_tokens. A resposta inclui período/filtros, generatedAt e avisos de cobertura. A API não promete histórico completo, identidade humana ou quantidade de instalações. Contadores são inteiros; contentViewRate24h é uma proporção entre 0 e 1 com a precisão numérica JSON, sem arredondamento para percentual no servidor. Um bucket pode começar antes do início solicitado, mas conta apenas os eventos dentro do intervalo consultado.

Duas consultas pesadas podem calcular simultaneamente na instância SQL. Contenção retorna 503 com Retry-After; quotas da credencial/app/dono retornam 429. Respeite o intervalo e repita a leitura com o mesmo contexto. Falhas de dependência não devem ser tratadas como resultado vazio. Não há cache de resultados compartilhado entre usuários.

A validação usa dados sintéticos. Eventos HTTP reais foram aceitos e deduplicados em homologação e na API pública existente em produção; as consultas e a exportação confirmaram os totais. Isso não comprova atribuição de instalação ou comportamento físico de dispositivos.