Listar vendas

GET/v1/sales

As vendas recebidas dos gateways no período, paginadas, com os totais do recorte inteiro — não só da página.

Parâmetros

Parâmetro	Tipo	Padrão	Observação
`from`	YYYY-MM-DD	30 dias atrás	início da janela
`to`	YYYY-MM-DD	hoje	inclusivo
`limit`	1–200	50	tamanho da página
`cursor`	opaco	—	veio do nextCursor anterior
`convertTo`	ISO-4217	—	converte os totais para uma moeda só — ver abaixo

Exemplo

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

json

{
  "sales": [
    {
      "id": "sale_3f8a1c2e9b7d4a6f5e01",
      "gateway": "digistore24",
      "status": "DISPATCHED",
      "eventStatus": "paid",
      "amountCents": 29900,
      "currency": "BRL",
      "orderId": "DS-88213",
      "contentId": "A7K2M9P4",
      "advertiser": {
        "id": "7291845003219",
        "name": "Conta Principal",
        "businessCenter": "BC Matriz"
      },
      "receivedAt": "2026-08-06T12:00:00.000Z",
      "dispatchedAt": "2026-08-06T12:00:03.412Z"
    }
  ],
  "total": 168,
  "nextCursor": "MjAyNi0wOC0wNlQxMjowMDowMC4wMDBa",
  "from": "2026-08-01",
  "to": "2026-08-31",
  "totals": { "paidCount": 152, "waitingCount": 9, "refundedCount": 6, "failedCount": 1 },
  "revenue": [{ "currency": "BRL", "amountCents": 4544800 }],
  "refundedRevenue": [{ "currency": "BRL", "amountCents": 179400 }],
  "netRevenue": [{ "currency": "BRL", "amountCents": 4365400 }],
  "conversion": null
}

Campos

Campo	Observação
`id`	estável e prefixado. Use como chave no seu banco
`gateway`	qual gateway mandou a venda. A lista vive em `GET /v1/gateways`
`amountCents`	inteiro em centavos, sempre com currency ao lado
`orderId`	id do pedido no gateway. Pode ser nulo
`contentId`	item de catálogo da venda: sku_id no TikTok, retailer_id no Meta. Nulo = não atribuída
`advertiser`	conta de anúncio que gerou o clique. name nulo = conta não conectada aqui, mas o id ainda rastreia
`dispatchedAt`	nulo enquanto não houve disparo

Os totais são da janela

total, revenue, refundedRevenue e netRevenue contam o recorte inteiro, não a página. É o que permite o seu painel fechar com o do gateway sem paginar tudo.

O recorte é o período que você pediu, não a página que veio na resposta. Pediu 1 a 31 de agosto e a janela tem dez páginas? Os quatro números são dos 31 dias, iguais em todas as dez — só sales[] muda de uma para a outra.

netRevenue pode ser negativo — uma janela que só recebeu estorno de venda mais antiga tem líquido negativo. Truncar em zero seria mentir sobre o período.

convertTo

O valor é o código ISO-4217 de três letras da moeda de destino — o mesmo padrão que você já vê no campo currency de cada venda. Basta acrescentar à querystring:

text

GET /v1/sales?from=2026-08-01&to=2026-08-31&convertTo=BRL

Moeda	Código
Real	`BRL`
Dólar	`USD`
Euro	`EUR`
Libra	`GBP`
Peso mexicano	`MXN`
Peso argentino	`ARS`

A tabela é só um atalho: qualquer código ISO-4217 de três letras é aceito, e a fonte de cotação cobre cerca de 160 moedas. Código fora do formato é 400.

Na resposta, revenue, refundedRevenue e netRevenue deixam de ter uma entrada por moeda e passam a ter uma só, e conversion diz de onde vieram as cotações:

json

{
  "revenue": [{ "currency": "BRL", "amountCents": 5216300 }],
  "refundedRevenue": [{ "currency": "BRL", "amountCents": 201800 }],
  "netRevenue": [{ "currency": "BRL", "amountCents": 5014500 }],
  "conversion": { "target": "BRL", "quotedFrom": "2026-08-01", "quotedTo": "2026-08-31" }
}

A conversão é dos totais. Cada venda de sales[] continua com o amountCents e a currency que o gateway informou — o valor da venda é fato, não apuração.

Vale a mesma régua das outras rotas: cotação do dia de cada venda e tudo ou nada — faltando a cotação de um dia, a conversão inteira é descartada e a resposta volta por moeda, com conversion: null. Nulo nunca significa taxa 1.

Paginação

nextCursor é opaco: devolva exatamente o que recebeu. null significa que acabou.

Não tente montar o cursor. Cursor ilegível é 400, nunca "primeira página em silêncio" — assim um bug do seu lado aparece, em vez de duplicar dados.