Análise e regras pela API

GET /api/links/:slug/stats retorna um resumo para um intervalo de tempo. Escolha o intervalo com ?range= - um de 1h, 24h, 7d, 30d, 90d, 183d, 365d, mtd ou ytd - ou dê uma janela explícita com ?from=<ms>&to=<ms> em milissegundos de época.

curl "https://qr2r.com/api/links/aA3k9/stats?range=30d" \
  -H "Authorization: Bearer $KILO_API_KEY"

A resposta devolve o intervalo resolvido, seu plano, os totais de cabeçalho, uma série temporal e desmembramentos por dimensão:

{
  "range": { "from": 1716408000000, "to": 1719000000000, "clamped": false, "bucket": "day" },
  "plan": { "slug": "pro", "limits": { /* … */ } },
  "totals": { "opens": 1284, "visitors": 512 },
  "timeseries": [ /* one point per bucket */ ],
  "meta": { "generated_at": 1719000000000, "query_ms": 37, "cache": "miss" }
}

opens conta os redirecionamentos servidos; visitors é a contagem distinta. Quando as dimensões do seu plano permitem, a resposta carrega também blocos de desmembramento (países, dispositivos, referenciadores, qualidade de tráfego e mais). A retenção e quais dimensões você obtém dependem do plano: se você pedir uma janela mais longa do que o seu plano guarda, a resposta volta com range.clamped definido como true e from empurrado até a borda da sua retenção.

GETs companheiros cobrem os mesmos dados em formatos diferentes: /stats/breakdown para uma única dimensão, /stats/timeseries para a série sozinha e /stats/export para um download. Os totais no nível de grupo ficam em GET /api/groups/:id/stats.

As regras de um link decidem para onde um escaneamento realmente vai. Leia-as com GET /api/links/:slug/rules:

{ "rules": [ /* rule objects, in priority order */ ] }

Adicione uma com POST /api/links/:slug/rules. O type de uma regra é geo, device ou ab, e cada uma carrega uma target_url. Uma regra geo segmenta por uma lista de códigos de país ISO-2:

curl https://qr2r.com/api/links/aA3k9/rules \
  -H "Authorization: Bearer $KILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "geo", "condition": { "countries": ["DE", "AT"] }, "target_url": "https://example.com/de" }'

Uma criação retorna 201 com a regra armazenada:

{
  "id": 44,
  "type": "geo",
  "condition": { "countries": ["DE", "AT"] },
  "target_url": "https://example.com/de",
  "weight": 1,
  "priority": 0,
  "created_at": 1719000000000
}

Atualize o alvo, o peso ou a prioridade de uma regra com PUT /api/rules/:id, e remova uma com DELETE /api/rules/:id (que retorna { "ok": true }). Reordene as regras de um link de forma atômica com POST /api/links/:slug/rules/reorder.

As regras se avaliam na borda dentro do próprio redirecionamento, sem jamais tocar um banco de dados no caminho quente - a mecânica está no guia de regras de roteamento. Essa é a superfície da API: chaves e escopos, links, estatísticas e regras, até o fundo.