查询报表列表

使用此端点按筛选条件查询报表列表。

可用环境

生产环境

https://api.gateway.com.br/core

端点

• 方法：GET
• 端点：/report
• 认证方式：Bearer token

查询参数

ℹ️ 使用 ISO 日期

startDate 和 endDate 必须以带时间的 ISO date string 格式传入。

示例：

• 2026-03-06T12:00:00.000Z

ℹ️ snapshot 分页

snapshot 不是指向“下一页”的指针：它是分页会话的固定标识，与 page（仍需照常传入并递增）配合使用，即使在翻页过程中产生了新记录，也能保持结果一致。

请从第一次响应中取得 snapshot 的值（第一次请求不传 snapshot），并在后续页面的请求中原样重新传回该值，同时保持与最初请求相同的筛选条件和相同的 perPage。如果在重新传回旧的 snapshot 时其中任一值发生变化，接口会返回错误。

名称	类型	必填	说明	校验规则
snapshot	string	否	分页会话的标识（取自第一次响应的 snapshot 字段）；后续页面请随 page 一起原样传回	必须与最初请求的筛选条件和 perPage 一致
startDate	string	否	筛选的起始日期	必须为带时间的 ISO date string
endDate	string	否	筛选的结束日期	必须为带时间的 ISO date string
status	string[] (enum) - PENDING, PROCESSING, FAILED, PROCESSED	否	状态列表	必须为非空且不含重复项的数组
type	string[] (enum) - TRANSACTION, DEPOSIT, WITHDRAWAL, MED, WALLET, ACCOUNT, ACCOUNT_FINANCIAL_SUMMARY, WALLET_DAILY_BALANCES	否	报表类型列表	必须为非空且不含重复项的数组
origin	string[] (enum) - ADMIN, USER	否	报表来源	必须为非空且不含重复项的数组
id	string (UUID v4)	否	报表的标识	必须为有效的 UUID v4
userName	string	否	用户名称	最多 255 个字符
userEmail	string	否	用户邮箱	必须为有效的邮箱

请求示例

cURL

curl --request GET \
--url "https://api.gateway.com.br/core/report?status=PROCESSED&type=TRANSACTION&origin=USER" \
--header 'Authorization: Bearer your-jwt-token'

JavaScript

const params = new URLSearchParams({
  status: 'PROCESSED',
  type: 'TRANSACTION',
  origin: 'USER'
});

const response = await fetch(`https://api.gateway.com.br/core/report?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
});
const data = await response.json();

成功响应

字段	类型	必填	说明
totalPages	number	是	总页数
currentPage	number	是	当前页
perPage	number	是	每页条数
snapshot	string	否	分页会话的标识；后续页面请原样传回
data	array	是	报表列表（参见子对象 ListItem）

子对象

ListItem

字段	类型	必填	说明
id	string	是	报表的标识
status	string (enum)	是	报表状态（PENDING、PROCESSING、FAILED、PROCESSED）
type	string (enum)	是	报表类型（TRANSACTION、DEPOSIT、WITHDRAWAL、MED、WALLET、ACCOUNT、ACCOUNT_FINANCIAL_SUMMARY、WALLET_DAILY_BALANCES）
user	object	是	用户信息（参见子对象 User）
origin	string (enum)	否	报表来源（ADMIN、USER）
filters	object	是	报表使用的筛选条件（参见子对象 Filters）
file	object	否	报表文件（参见子对象 File）
expirationDate	string (ISO)	否	文件的过期时间
errorMessage	string	否	错误信息
createdAt	string (ISO)	是	创建时间
updatedAt	string (ISO)	是	最后更新时间

User

字段	类型	必填	说明
id	string	是	用户的标识
name	string	是	用户名称
email	string	是	用户邮箱

Filters

字段	类型	必填	说明
startDate	string	是	筛选的起始日期
endDate	string	是	筛选的结束日期
storeId	string (UUID v4)	否	店铺的标识
userId	string (UUID v4)	否	用户的标识
status	string[]	否	已应用的状态列表
paymentMethod	string[]	否	支付方式
acquirer	string[]	否	报表涉及的收单机构

File

字段	类型	必填	说明
key	string	是	文件的键
isPrivate	boolean	是	标识文件是否为私有
url	string	是	访问文件的地址

响应示例

{
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 15,
  "snapshot": "b3BhcXVlLXNuYXBzaG90LXRva2Vu",
  "data": [
    {
      "id": "553e8400-e29b-41d4-a716-436251480000",
      "status": "PROCESSED",
      "type": "TRANSACTION",
      "user": {
        "id": "553e8400-e29b-41d4-a716-436251480111",
        "name": "Loja Exemplo",
        "email": "contato@lojaexemplo.com"
      },
      "origin": "USER",
      "filters": {
        "startDate": "2026-03-06T00:00:00.000Z",
        "endDate": "2026-03-06T23:59:59.999Z",
        "status": ["PAID"],
        "paymentMethod": ["PIX"]
      },
      "file": {
        "key": "report-2026-03-06-553e8400-e29b-41d4-a716-436251480000-CSV",
        "isPrivate": true,
        "url": "signed-url"
      },
      "expirationDate": null,
      "errorMessage": null,
      "createdAt": "2026-03-06T12:49:04.681Z",
      "updatedAt": "2026-03-06T12:49:04.681Z"
    }
  ]
}

可能的错误

状态码	说明	处理方式
401	凭据无效	请检查您的凭据
403	无权限或未授权	请联系技术支持
422	数据无效或缺失	请检查数据格式
422	校验失败	请联系技术支持
500	内部错误	请联系技术支持