查询 MED 列表

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

可用环境

生产环境

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

端点

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

查询参数

ℹ️ 使用 ISO 日期

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

示例：

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

ℹ️ 查询字符串中的数组

status 字段可接受多个值。

示例：

• status=PENDING&status=APPEALED

ℹ️ snapshot 分页

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

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

名称	类型	必填	说明	校验规则
snapshot	string	否	分页会话的标识（取自第一次响应的 snapshot 字段）；在后续页中与 page 一起原样重发	必须与原始请求的筛选条件及 perPage 一致
startDate	string	否	筛选的起始日期	必须为带时间的 ISO date string
endDate	string	否	筛选的结束日期	必须为带时间的 ISO date string
status	string[] (enum) - PENDING, APPEALED, APPROVED, REJECTED	否	用于筛选的状态列表	必须为非空、唯一且不含重复项的数组
id	string (UUID v4)	否	MED 的标识	必须为有效的 UUID v4
transactionId	string (UUID v4)	否	交易的标识	必须为有效的 UUID v4
endToEnd	string	否	end-to-end 标识	长度须在 8 到 255 个字符之间
amount	number	否	MED 金额（整数，以分为单位）	介于 1 与 10000000 之间的整数
paymentMethod	string (enum) - PIX	否	支付方式	必须为有效的支付方式取值

请求示例（包含全部字段）

cURL

curl --request GET \
--url "https://api.gateway.com.br/core/med?startDate=2026-03-01T00:00:00.000Z&endDate=2026-03-24T23:59:59.999Z&status=PENDING&status=APPEALED&id=553e8400-e29b-41d4-a716-436251480000&transactionId=553e8400-e29b-41d4-a716-446655440000&endToEnd=E2E12345678&amount=1000&paymentMethod=PIX" \
--header 'Authorization: Bearer your-jwt-token'

JavaScript

const params = new URLSearchParams({
  startDate: '2026-03-01T00:00:00.000Z',
  endDate: '2026-03-24T23:59:59.999Z',
  id: '553e8400-e29b-41d4-a716-436251480000',
  transactionId: '553e8400-e29b-41d4-a716-446655440000',
  endToEnd: 'E2E12345678',
  amount: '1000',
  paymentMethod: 'PIX'
});

params.append('status', 'PENDING');
params.append('status', 'APPEALED');

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

const data = await response.json();

成功响应

字段	类型	必填	说明
totalPages	number	是	总页数
currentPage	number	是	当前页
perPage	number	是	每页条数
snapshot	string	否	分页会话的标识；在后续页中原样重发
data	array	是	MED 列表

data 中每一项的字段

字段	类型	必填	说明
id	string	是	MED 的标识
acquirer	string	是	MED 的收单机构
transactionId	string	是	交易的标识
endToEnd	string	是	end-to-end 标识
notificationId	string	否	关联通知的标识
status	string (enum) - PENDING, APPEALED, APPROVED, REJECTED	是	MED 状态
origin	string (enum) - ACQUIRER, ADMIN	是	MED 来源
reason	string (enum) - SCAM, FRAUDULENT_ACCESS, OPERATIONAL_ERROR, OTHER	是	MED 原因
amount	number	是	MED 金额（整数，以分为单位）
paymentMethod	string (enum) - PIX	是	支付方式
payer	object	否	付款方信息（参见子对象 AccountHolder）
customerMessage	string	否	客户留言
user	object	是	用户信息（UserVo）
decisionMessage	string	否	裁决说明
refundStatus	string (enum) - FULL_REFUND, PARTIAL_REFUND, INSUFFICIENT_FUNDS	否	退款状态
appealContent	object	否	申诉内容（AppealContent）
refundAmount	number	否	退款金额（整数，以分为单位）
statusHistory	array	是	状态历史（参见子对象 StatusHistory）
medDate	string (ISO)	是	MED 日期
createdAt	string (ISO)	是	创建日期
updatedAt	string (ISO)	是	最后更新日期

子对象

UserVo

字段	类型	必填	说明
name	string	是	用户名称
email	string	是	用户电子邮箱
createdAt	string (ISO)	是	用户的创建日期

AccountHolder

字段	类型	必填	说明
type	string (enum) - PF, PJ	是	持有人类型
name	string	是	持有人姓名
document	string	是	持有人证件号
bankAccount	object	是	银行信息（参见子对象 BankAccount）
pix	object	是	持有人的 PIX 密钥（参见子对象 PixKeyVo）

BankAccount

字段	类型	必填	说明
type	string	是	账户类型
digit	string	是	账户校验位
ispb	string	是	银行的 ISPB

PixKeyVo

字段	类型	必填	说明
key	string	是	PIX 密钥
type	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	是	PIX 密钥类型

StatusHistory（列表项）

字段	类型	必填	说明
status	string (enum) - PENDING, APPEALED, APPROVED, REJECTED	是	历史记录中的 MED 状态
date	string (ISO)	是	状态变更的日期与时间
durationInMilliseconds	number	否	该状态的持续时长（毫秒）

AppealContent

字段	类型	必填	说明
message	string	否	申诉说明
evidences	array	否	申诉证据（参见子对象 FileVo）

FileVo（evidences 的列表项）

字段	类型	必填	说明
key	string	是	文件的键
isPrivate	boolean	是	标识该文件是否为私有
expirationDate	string (ISO)	否	文件的过期日期
url	string	否	文件的签名 URL

响应示例

{
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 15,
  "snapshot": "b3BhcXVlLXNuYXBzaG90LXRva2Vu",
  "data": [
    {
      "id": "553e8400-e29b-41d4-a716-436251480000",
      "acquirer": "ACQUIRER_EXEMPLO",
      "transactionId": "553e8400-e29b-41d4-a716-446655440000",
      "endToEnd": "E2E12345678",
      "notificationId": null,
      "status": "PENDING",
      "origin": "ACQUIRER",
      "reason": "SCAM",
      "amount": 1000,
      "paymentMethod": "PIX",
      "payer": {
        "type": "PF",
        "name": "Fulano de Tal",
        "document": "***456789**",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "7",
          "ispb": "12345678"
        },
        "pix": {
          "key": "12345678910",
          "type": "CPF"
        }
      },
      "customerMessage": "Cliente informou não reconhecer a cobrança.",
      "user": {
        "name": "Loja Exemplo",
        "email": "contato@lojaexemplo.com",
        "createdAt": "2026-03-01T09:00:00.000Z"
      },
      "decisionMessage": "Decisão administrativa em análise.",
      "refundStatus": "PARTIAL_REFUND",
      "appealContent": {
        "message": "Enviamos comprovante da entrega e da autenticação do pedido.",
        "evidences": [
          {
            "key": "med/evidence-1.pdf",
            "isPrivate": true,
            "expirationDate": "2026-03-25T10:00:00.000Z",
            "url": null
          }
        ]
      },
      "refundAmount": 500,
      "statusHistory": [
        {
          "status": "PENDING",
          "date": "2026-03-24T10:00:00.000Z",
          "durationInMilliseconds": 3600000
        },
        {
          "status": "APPEALED",
          "date": "2026-03-24T11:00:00.000Z",
          "durationInMilliseconds": null
        }
      ],
      "medDate": "2026-03-24T10:00:00.000Z",
      "createdAt": "2026-03-24T10:00:00.000Z",
      "updatedAt": "2026-03-24T11:00:00.000Z"
    }
  ]
}

可能的错误

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