Primeiros passos

A API pública do PassKey entrega os dados de traqueamento por HTTP: as vendas que chegaram dos gateways, os números do período e o ranking de criativos. É a mesma informação do painel, pronta para o seu sistema guardar.

Endereço

Todas as chamadas partem de: https://public-api.passkey.global/v1

A primeira chamada

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

A chave sai da tela de Configurações do painel — o passo a passo está em Autenticação.

O que existe hoje

Rota	Responde
GET /v1/sales	as vendas do período, paginadas, com os totais do recorte
GET /v1/sales/metrics	faturamento por moeda e contagem por status
GET /v1/creatives/ranking	quanto cada criativo vendeu, com gasto e tráfego

Tudo é leitura. Não há rota que crie, altere ou apague nada — as vendas entram pelo postback do gateway.

Três coisas que evitam o erro mais comum

1. Moeda nunca é somada. Todo valor vem com a moeda dele, e as listas de faturamento trazem uma entrada por moeda:

json

"revenue": [
  { "currency": "BRL", "amountCents": 60000 },
  { "currency": "USD", "amountCents": 12000 }
]

Somar amountCents do array inteiro mistura reais com dólares e produz um total errado sem gerar erro nenhum. Para um número só, peça convertTo e leia o campo conversion.

2. Valores são inteiros em centavos. amountCents: 29900 é R$ 299,00. Não há ponto flutuante em lugar nenhum da resposta — dinheiro em float acumula erro de arredondamento.

3. A janela tem teto de 90 dias. Para períodos maiores, faça chamadas encadeadas. Sem from/to, o padrão são os últimos 30 dias.

Convenções

Assunto	Regra
Datas de filtro	YYYY-MM-DD, e to é inclusivo
Datas de resposta	ISO-8601 (2026-08-06T12:00:00.000Z)
Paginação	cursor opaco — devolva o que recebeu, sem interpretar
Campos novos	podem aparecer a qualquer momento; ignore o que não conhece

Identificadores

sale_8f3a… é estável: a mesma venda devolve o mesmo id para sempre. Use-o como chave no seu banco. O mesmo vale para o contentId, que é a chave de cruzamento entre a venda e o criativo.

Eles não são os identificadores internos do PassKey, e isso é de propósito: assim o nosso esquema interno pode mudar sem quebrar o que você já guardou.

Integrando com um agente de IA

Esta mesma documentação existe em JSON, num endereço só e em inglês: /docs.json. Aponte o seu agente para lá em vez de pedir que ele leia estas páginas.

bash

curl https://docs.stg.passkey.global/docs.json

Ela traz a URL base, a autenticação, cada rota com parâmetros e campos de resposta, e os códigos de erro com a orientação de retentar. É um endereço só, sem versão por idioma.

A API e o painel

Pela API você lê as vendas do período, os totais e o ranking de criativos — o suficiente para alimentar o seu sistema com o que entrou e com o que vendeu.

A leitura completa fica no painel do PassKey: é lá que estão as métricas detalhadas, os rankings por produto, o ROI e o funil.