Skip to main content
GET
/
transaction
Listar transações
curl --request GET \
  --url https://api.bestfy.io/transaction \
  --header 'x-api-key: <api-key>'
{
  "transactions": [
    {
      "transactionId": "8d2b8c64-da20-45b5-a347-6c2b34579265",
      "status": "REFUNDED",
      "product": "Licensed Metal Bike",
      "productType": "NUTRACEUTICAL",
      "customer": "Norman Leannon",
      "customerEmail": "Stuart.Armstrong41@gmail.com",
      "paymentMetadata": {
        "value": 5859.99,
        "method": "CREDIT_CARD"
      },
      "paymentConfirmedAt": "2025-11-19T21:28:21.499Z",
      "createdAt": "2025-03-12T10:01:33.458Z",
      "updatedAt": "2025-11-19T21:49:32.501Z",
      "value": 4857.5,
      "deliveryStatus": "IN_TRANSIT",
      "acquirer": "IUGU",
      "productId": "8a1e2aa3-20e1-4126-822b-af4250cd7e6f",
      "customerId": "89f9a0f5-1029-40b1-a7d4-4ad4c1de8623",
      "companyId": "308f5ecb-80ca-4d40-8a68-1399be4c6918",
      "paymentMetadataId": "e8ce2c40-b9f2-4fa2-99af-2c4183619969",
      "pixEndToEndId": "VMW1y6xer0XNruADXBSh9Wz1kA0PIbV0",
      "refundedAt": "2025-11-19T18:01:32.744Z"
    }
  ],
  "transactionsAmount": 1
}
Use este endpoint para carregar as transações exibidas no Bestfy. Combine paginação (page, limit) com filtros como status, method, deliveryStatus ou faixas de data para restringir o resultado e manter as respostas leves.

​
Regras de uso

  • Sempre informe limit ≤ 40 para evitar erros de validação.
  • Utilize filtros de data em pares (createdFrom/createdTo, etc.) para manter a performance dos índices.
  • Para consultas por identificadores, prefira transactionId ou pixEndToEndId antes de aplicar filtros mais amplos.

​
Exemplo de requisição

curl --request GET 'https://api.bestfy.io/transaction?page=1&limit=20&status=PAID,REFUNDED' \
  --header 'x-api-key: <SUA_CHAVE_AQUI>'

​
Paginação

O campo transactionsAmount indica o total de registros encontrados. Para navegar, incremente page até que transactions retorne vazio.

​
Erros comuns

CódigoMotivo
400Algum filtro inválido (ex.: limit > 40)
500Erro interno — reenvie após alguns segundos

Authorizations

​
x-api-key
string
header
required

Key pública disponibilizada no dashboard Bestfy.

Query Parameters

​
page
integer
default:1

Número da página (começa em 1).

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

Limite de itens por página. Não deve ser maior que 40.

Required range: 1 <= x <= 40
​
transactionId
string<uuid>

Filtra por ID específico de transação.

​
pixEndToEndId
string

Filtra por identificador Pix End-to-End.

​
customerName
string

Filtra por nome do cliente (case insensitive).

​
customerEmail
string<email>

Filtra por e-mail do cliente.

​
customerPhone
string

Filtra por telefone do cliente.

​
customerCpfCnpj
string

Filtra por CPF ou CNPJ do cliente (somente números).

​
cardLastDigits
string

Filtra pelos 4 últimos dígitos do cartão.

Required string length: 4
​
cardBrand
enum<string>

Filtra pela bandeira do cartão.

Available options:
VISA,
MASTERCARD,
ELO,
AMEX
​
method
enum<string>[]

Filtra por métodos de pagamento.

​
amountFrom
integer

Valor mínimo da transação (em centavos).

Required range: x >= 0
​
amountTo
integer

Valor máximo da transação (em centavos).

Required range: x >= 0
​
installmentsAmount
enum<integer>[]

Filtra por número de parcelas.

​
isRejected
boolean

Define se retorna apenas transações recusadas.

​
orderByPaymentDate
boolean

Ordena o resultado pela data de pagamento (descendente).

​
status
enum<string>[]

Filtra por múltiplos status de transação.

​
deliveryStatus
enum<string>[]

Filtra por status logístico.

​
acquirer
enum<string>[]

Filtra por adquirente responsável.

​
createdFrom
string<date-time>

Filtra pela data de criação (início).

​
createdTo
string<date-time>

Filtra pela data de criação (fim).

​
paymentConfirmedFrom
string<date-time>

Filtra pela data de confirmação de pagamento (início).

​
paymentConfirmedTo
string<date-time>

Filtra pela data de confirmação de pagamento (fim).

​
updatedFrom
string<date-time>

Filtra pela data da última atualização (início).

​
updatedTo
string<date-time>

Filtra pela data da última atualização (fim).

​
refundedFrom
string<date-time>

Filtra pela data de estorno (início).

​
refundedTo
string<date-time>

Filtra pela data de estorno (fim).

Response

Lista paginada de transações.

​
transactions
object[]
required
​
transactionsAmount
integer
required

Total de registros encontrados.