Ranking de criativos

GET/v1/creatives/ranking

Quanto cada criativo vendeu no período, com o gasto da campanha e o tráfego medido. É o cruzamento que o gateway sozinho não responde: ele sabe que houve venda, não sabe qual anúncio a gerou.

Parâmetros

Parâmetro	Tipo	Padrão
`from`	YYYY-MM-DD	30 dias atrás
`to`	YYYY-MM-DD	hoje
`limit`	1–100	20
`convertTo`	ISO-4217	—

O convertTo é o mesmo das outras rotas: código ISO-4217 de três letras (BRL, USD, EUR), cotação do dia de cada venda e tudo ou nada — sem cotação para algum dia, o ranking volta por moeda e conversion vem nulo, que nunca significa taxa 1.

Exemplo

curl "https://public-api.passkey.global/v1/creatives/ranking?from=2026-08-01&to=2026-08-31&limit=20" \
  -H "Authorization: Bearer passkey_prd_..."

json

{
  "from": "2026-08-01",
  "to": "2026-08-31",
  "creatives": [
    {
      "contentId": "A7K2M9P4",
      "name": "Video1",
      "fileName": "criativo-agosto-01.mp4",
      "currency": "BRL",
      "revenueCents": 890000,
      "salesCount": 31,
      "landingClicks": 4820,
      "checkoutClicks": 612,
      "landingVisitors": 3970,
      "checkoutVisitors": 548,
      "previousPosition": 4,
      "campaigns": [
        {
          "platformCampaignId": "1800000000000000",
          "campaignName": "AGO — Catálogo",
          "advertiserId": "7291845003219",
          "salesCount": 31,
          "revenueCents": 890000,
          "spendCents": 214000,
          "impressions": 182400,
          "clicks": 5100,
          "ctr": 2.79,
          "currency": "BRL"
        }
      ]
    }
  ],
  "conversion": null,
  "platformMetrics": {
    "collectedAt": "2026-09-17T11:42:00.000Z",
    "status": "fresh",
    "nextAttemptInSeconds": 620
  }
}

Métricas de plataforma

spendCents, impressions, clicks e ctr não são medidos por nós: vêm do TikTok e do Meta. O bloco platformMetrics diz quando eles foram buscados pela última vez.

Campo	O que diz
`collectedAt`	quando a plataforma mais atrasada foi consultada. Nulo = nunca
`status`	`fresh`, `refreshing` ou `never`
`nextAttemptInSeconds`	quanto falta até uma leitura poder agendar a próxima atualização

A atualização é automática, e é a sua leitura que a dispara. Não há rota para forçar nem configuração a fazer: basta a conta de anúncio estar conectada no PassKey. Se os números vierem nulos ou parados, espere de 15 a 30 minutos e leia de novo — parte desse tempo é a plataforma, que não entrega o dado do dia na hora.

status: "never" não é espera: é conta de anúncio que nunca foi coletada. Conecte-a no painel.

Nulo não é zero

É a convenção mais importante desta rota, e a que mais muda decisão:

Campo nulo	Significa
`spendCents`, `impressions`, `clicks`, `ctr`	não apurado: a campanha não teve coleta de métrica na janela. Nunca "gastou zero"
`landingClicks`, `checkoutVisitors`…	sem medição: nenhum beacon na janela — script não instalado ou sem tráfego
`previousPosition`	o criativo não vendeu no período anterior (é novo no ranking)

Tratar nulo como zero produz ROI infinito e CTR falso. Se você calcula razões, teste o nulo primeiro.

O que esta rota não devolve

Nome de workspace, nome de campanha do PassKey e tipo de mídia ficam de fora. Essa é a estrutura com que o PassKey organiza o trabalho, não o que você precisa para cruzar dados: para isso bastam o contentId, o nome do criativo e o arquivo original.

O campaignName de dentro de campaigns[] continua: aquele é o nome da campanha na plataforma, o mesmo que você vê no gerenciador de anúncios.

Cliques × visitantes

São duas réguas do mesmo evento, lado a lado de propósito: landingClicks conta carregamentos de página, e landingVisitors conta visitantes distintos no dia.

Medido em produção: 18,4% de inflação entre as duas, e esse é o piso. Para funil e conversão, visitors é a régua honesta; clicks serve para volume bruto.

O mesmo criativo em várias campanhas

O array campaigns quebra o resultado por campanha da plataforma, e platformCampaignId é o id do TikTok/Meta — é por ele que você cruza com os relatórios da sua própria conta de anúncio.

spendCents é o gasto da campanha inteira, não a fatia deste criativo. A plataforma não entrega gasto por criativo: se a campanha anuncia dez criativos, o valor aparece igual nos dez. Agrupe por platformCampaignId antes de dividir.