Skip to main content
GET
Listar transações
GET /transactions Faz parte do recurso Transações — o conceito, o ciclo de vida e a tabela de status estão lá. Retorna uma lista paginada. Todos os filtros são opcionais e podem ser combinados. Os valores aceitos em status são os de Status da transação, e as datas seguem ISO 8601 com timezone (veja Convenções).
Filtro com valor inválido é rejeitado, não ignorado. ?status=xpto responde 400 com error.issues[] apontando o campo e os valores aceitos.O formato do erro e a lista de códigos estão em Erros.
Vários valores no mesmo filtro. status, currency, paymentMethod e recipientIds aceitam uma lista separada por vírgula, e o resultado traz qualquer transação que case com um dos valores. Ex.: ?status=paid,refused&paymentMethod=pix,boleto.
Sincronização incremental. Para trazer só o que mudou desde a última execução, combine dateField=updatedAt com startDate e ordene por updatedAt. O campo updatedAt é atualizado a cada mudança de estado da transação — inclusive um estorno meses depois da venda, que uma busca por createdAt não traria.
Prefira janelas fechadas (startDate + endDate) a varrer muitas páginas de um período ainda em aberto: registros alterados durante a varredura mudam de posição e podem escapar da paginação.

​
Exemplo

A listagem já traz payments e items. Cada item de data vem com os pagamentos (com dados do cartão e os splits, quando houver) e os itens da transação. Para percorrer transações com seus pagamentos não é preciso chamar GET /transactions/{id} de novo para cada uma.Como o payload por transação é grande, prefira limit menor quando estiver varrendo muitos registros.
Os dados do cliente vêm em duas formas. A transação carrega o snapshot do comprador no momento da compra — customerName, customerEmail, customerDocument, customerDocumentType e customerPhone — que não muda depois, mesmo que o cliente atualize o cadastro. É o que você quer para conferir uma venda antiga.Para o cadastro atual (incluindo endereço), use o customerId em GET /customers/{id}. O objeto customer completo vem em GET /transactions/{id}, não na listagem.

Authorizations

​
x-api-key
string
header
required

API Key da Credential (gerada no Backoffice)

Query Parameters

​
page
integer
default:1

Página da listagem. Padrão: 1.

Required range: x >= 1
​
limit
integer
default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100
​
currency
enum<string>[]

Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.

Available options:
BRL
​
status
string[]

Status da transação. Aceita vários valores separados por vírgula.

​
customerName
string | null

Nome do cliente. Busca parcial (contém).

​
customerEmail
string | null

E-mail do cliente. Busca parcial (contém).

​
customerDocument
string | null

Documento do cliente. Match exato — precisa ser idêntico ao cadastrado.

​
referenceCode
string | null

Seu código de referência para a transação. Match exato.

​
recipientIds
string[]

IDs de recebedores (rec_) que devem aparecer em algum split da transação. Aceita vários valores separados por vírgula.

Minimum string length: 1
​
additionalInfoSearch
string | null

Busca textual dentro de additionalInfo. O match é parcial e roda sobre o JSON inteiro, então casa também o nome da chave, não só o valor.

​
startDate
string<date-time> | null

Data inicial, ISO 8601 com timezone. Aplica-se ao campo indicado em dateField.

​
endDate
string<date-time> | null

Data final, ISO 8601 com timezone. Aplica-se ao campo indicado em dateField.

​
paymentMethod
enum<string>[]

Método de pagamento usado na transação. Aceita vários valores separados por vírgula. combined traz as transações com dois ou mais pagamentos ativos.

Available options:
credit_card,
debit_card,
boleto,
pix,
combined
​
dateField
enum<string> | null

Campo de data ao qual startDate/endDate se aplicam. Padrão: createdAt.

Available options:
createdAt,
updatedAt,
paidAt,
refundedAt,
canceledAt,
chargedbackAt,
protestedAt
​
sortBy
enum<string> | null

Campo de ordenação. Padrão: createdAt. Use updatedAt para sincronização incremental (o campo muda a cada alteração da transação).

Available options:
createdAt,
updatedAt
​
sortDir
enum<string> | null

Direção da ordenação. Padrão: desc.

Available options:
asc,
desc

Response

Lista paginada de transações

​
data
object[]

Lista de registros retornados na página atual.

​
pagination
object

Dados de paginação do resultado.