Listar transações

Recupere uma página de transações da sua conta, filtrando por status, método de pagamento, cliente, período e outros critérios. É a principal visão de vendas e pagamentos: use-a para montar relatórios, telas de histórico, conciliação financeira e painéis de acompanhamento.

GET /v1/transactions

Como funciona

Este endpoint retorna uma lista paginada de transações, ordenada da mais recente para a mais antiga por padrão. A resposta não é um array simples: é um envelope de paginação com metadados (offset, limit, total, hasMore, page), o array data com as transações, o bloco merchant (sua conta) e _links (HATEOAS).

Dois detalhes importantes sobre o comportamento:

• Projeção leve. Cada item de data é uma versão resumida da transação — traz os campos essenciais (id, valor, status, método, cliente, datas), mas omite blocos pesados como timeline, receivables, splits e o objeto completo de customer/billing. Para o objeto completo, consulte GET /v1/transactions/{id}.
• Paginação por offset. Você avança nos resultados deslocando a janela com offset e limit. O servidor calcula os deslocamentos de cada página para você em page.offset (não monte essa lógica do zero). Veja Paginação.

Os filtros são combináveis: enviar vários parâmetros de query funciona como um E lógico (todos precisam casar). Filtros muito restritivos podem retornar data: [] com total: 0 — isso é uma resposta válida, não um erro.

Quando usar

• Use para histórico, relatórios, telas de busca, conciliação e exportações pontuais.
• Use com filtros de período (daterange*) para fechamentos diários/mensais.
• Não use para descobrir "se uma transação específica mudou" — para isso assine os eventos transaction.* via webhook.
• Não use como fonte de verdade de um único pedido em tela — para detalhe completo, leia a transação por ID em Read.

Requisição

Headers

Nunca use Authorization: Bearer ou Basic — a autenticação é sempre pelo header SelectKey. Como GET não tem corpo, não envie Content-Type nem X-Idempotency-Key aqui.

Parâmetros de query

Todos são opcionais. Sem nenhum filtro, você recebe as transações mais recentes paginadas.

Valores de status

Para o ciclo de vida completo dos status e suas transições, veja Visão geral de Transações.

Exemplos curl

Transações aprovadas no cartão de crédito, página de 50, mais recentes primeiro:

curl "https://api.selectwin.io/v1/transactions?status=approved&method=credit&limit=50&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Transações de um cliente específico:

curl "https://api.selectwin.io/v1/transactions?customerid=cus_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Conciliação de um intervalo de datas (1 a 30 de abril de 2026, inclusive):

curl "https://api.selectwin.io/v1/transactions?daterangegte=2026-04-01T00:00:00Z&daterangelte=2026-04-30T23:59:59Z&limit=50" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Segunda página de resultados (pulando os 20 primeiros):

curl "https://api.selectwin.io/v1/transactions?limit=20&offset=20" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Sucesso (200 OK)

{
  "offset": 0,
  "limit": 20,
  "total": 142,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 8,
    "offset": { "first": 0, "prev": null, "next": 20, "last": 140 }
  },
  "data": [
    {
      "id": "tra_01hqzvabc",
      "customId": "PEDIDO-1042",
      "customerId": "cus_01hqzvabc",
      "cardBrand": "visa",
      "amount": 1500,
      "originalAmount": 1500,
      "status": "approved",
      "method": "credit",
      "currency": "BRL",
      "fees": 45,
      "approvedAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:32.000Z",
      "images": ["https://cdn.example.com/product.png"]
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions",
      "method": "GET",
      "description": "List all transactions."
    }
  }
}

Envelope de paginação

Item de data[] (projeção leve)

Erros

Trate sempre pelo error.code (estável), não pela message. Veja o Catálogo de Códigos de Erro e o envelope de erro.

Boas práticas

1. Filtre no servidor, não no cliente. Use status, method, customerid e os daterange* para reduzir o volume — é mais rápido e barato do que baixar tudo e filtrar localmente.
2. Pagine pelos offsets da resposta. Use page.offset.next/page.offset.prev (ou hasMore) para navegar, em vez de calcular offsets manualmente.
3. Respeite o teto de 50 por página. Para conjuntos grandes, itere as páginas com backoff leve entre chamadas em vez de aumentar o limit.
4. Use limites inclusivos/exclusivos com cuidado. Para fechamentos, prefira daterangegte + daterangelte; combine com status=approved para conciliar apenas o que foi pago.
5. Não dependa da lista para detalhes. Itens são projeções leves — busque o objeto completo via Read quando precisar de timeline, receivables ou splits.
6. Não faça polling. Para saber quando uma transação muda de estado, assine os eventos transaction.* por webhook.
7. Trate 429/5xx com backoff exponencial e correlacione transações com o seu sistema por referenceid/customId.

Veja também

• Visão geral de Transações — modelo do objeto e ciclo de vida dos status.
• Criar transação — como gerar uma nova cobrança.
• Ler transação — objeto completo por ID.
• Capturar e Reembolsar — operações sobre uma transação.
• Abrir disputa — registrar contestação/chargeback.
• Paginação · Convenções · Proibição de polling