`/meds/list` 接口介绍

接口背景

/meds/list 提供给商户的 MED 违规报告列表查询接口。接口基于游标分页，返回商户自身的 PIX MED 违规报告，支持按创建时间范围、MED 状态及违规报告状态过滤。

结果按 MED ID（平台案件号）降序排列，最新创建的在前。

接口请求地址

项目	内容
请求方式	`GET`
请求路径	`/meds/list`
Content-Type	`application/json`
接口用途	查询 MED 违规报告列表

认证

使用 ES256 请求签名，必须携带 X-Merchant-Id、X-Timestamp、X-Nonce、Digest 和 Authorization。X-Merchant-Id 填写商户号，keyId 为密钥版本号，默认 v1。签名值为 DER 编码的 ECDSA 签名经标准 Base64 编码后的结果，具体规则见请求签名。

示例中的时间戳、Nonce、摘要和签名占位符需按每次实际请求生成；签名串包含实际路径及原始 query，分页或筛选条件变化后必须重新签名。

接口请求字段

字段名	位置	类型	是否必填	说明
`limit`	Query	int	否	每页记录数，最小 1，最大 100；不传时默认 5。
`id`	Query	string	否	分页游标所在位置的 MED ID，最大长度 64 个字符。
`direction`	Query	string	否	分页方向：`next`（下一页）或 `previous`（上一页），默认 `next`。
`filterStartTime`	Query	string	否	过滤 MED 创建起始时间，ISO 8601 UTC 时间字符串（`yyyy-MM-ddTHH:mm:ssZ`）；可单独使用，与 `filterEndTime` 同时提供时构成闭合区间（包含起止时刻）。
`filterEndTime`	Query	string	否	过滤 MED 创建结束时间，ISO 8601 UTC 时间字符串（`yyyy-MM-ddTHH:mm:ssZ`）；可单独使用，与 `filterStartTime` 同时提供时构成闭合区间（包含起止时刻）。
`status`	Query	string	否	按 MED 状态过滤，取值见下方 `status` 枚举。
`infractionReportStatus`	Query	string	否	按违规报告状态过滤，取值见下方 `infractionReportStatus` 枚举。

`status` MED 状态枚举

值	说明
`WAITING`	待处理：案件等待商户处理（上传证据文件并提交分析）
`EVIDENCE_REQUIRED`	待补充资料：平台打回了商户的异议提交，商户可补充文件后重新提交分析
`UNDER_REVIEW`	平台审核中：商户已提交分析结论（或平台已代为提交），平台审核中，直到出审核结果
`ACCEPTED_BY_USER`	商户已提交同意退款：预留状态，当前流程不出现（历史数据可能存在）
`REJECTED_BY_USER`	商户已提交异议：预留状态，当前流程不出现（历史数据可能存在）
`ACCEPTED_BY_PSP`	审核成立：平台审核结果为 MED 成立并执行退款
`REJECTED_BY_PSP`	审核不成立：平台审核结果为 MED 不成立
`CANCELLED_BY_USER`	用户撤销：付款用户/投诉发起方撤销本次 MED 申请
`CANCELLED_BY_PSP`	平台撤销：平台撤销或终止本次 MED 处理
`CLOSED`	已结案：资金处理（扣款或退还）完毕后结案，终态

`infractionReportStatus` 违规报告状态枚举

值	说明
`RECEIVED`	报告已被接收
`ANALYZED`	报告已完成分析
`CANCELLED`	报告已被取消

过滤规则

时间范围校验： filterStartTime 与 filterEndTime 均可单独使用；同时提供时，filterStartTime 小于等于 filterEndTime，过滤区间为闭合区间，包含起止时刻。
时间格式： 时间参数为 ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ），精确到秒、必须携带 Z 后缀，不接受时区偏移写法。

分页行为

基于游标的分页在底层数据集发生变化时，比基于 offset 的分页更高效、更一致。
首次请求： 省略 id 和 direction 参数。
下一页： 使用响应中 next 字段提供的完整 URL。
上一页： 使用响应中 previous 字段提供的完整 URL。

请求示例

示例 1：获取第一页

http

GET /meds/list?limit=10 HTTP/1.1
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

示例 2：按时间范围过滤

http

GET /meds/list?filterStartTime=2026-01-01T00:00:00Z&filterEndTime=2026-01-31T23:59:59Z&limit=20 HTTP/1.1
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

示例 3：按状态过滤

http

GET /meds/list?status=WAITING&limit=15 HTTP/1.1
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

示例 4：跳转到下一页

http

GET /meds/list?limit=10&id=medc2874510938274639021&direction=next HTTP/1.1
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

示例 5：跳转到上一页

http

GET /meds/list?limit=10&id=medc1029384756102938475&direction=previous HTTP/1.1
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

示例 6：组合复杂过滤条件

http

GET /meds/list?filterStartTime=2026-01-01T00:00:00Z&filterEndTime=2026-01-31T23:59:59Z&status=WAITING&infractionReportStatus=RECEIVED&limit=25 HTTP/1.1
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

接口响应字段

接口使用统一的 status、msg、data 响应结构。分页游标与 MED 记录列表位于 data 中。

每个列表项是查询MED详情的轻量投影，两者结构同构：列表项包含概要字段与 transaction、payer（不含银行账户）、payee、infractionReport 组；details、funds、analysis、chargebacks 仅详情接口返回。

分页字段

字段名	类型	是否必返	说明
`status`	int	是	响应码
`msg`	string	是	与 `status` 对应
`data`	object	成功必返	分页结果；请求在验签或协议解析阶段失败时可能不返回。
`data.next`	string	是	下一页结果的完整 URL；无更多页时为 `null`，最大长度 512 个字符。
`data.previous`	string	是	上一页结果的完整 URL；位于首页时为 `null`，最大长度 512 个字符。
`data.results`	array	是	MED 记录列表。

列表项概要字段（`data.results[]`）

字段名	类型	是否必返	说明
`data.results[].medId`	string	是	MED 唯一标识符，平台案件号（`medc` 前缀 + 数字），最大长度 64 个字符。
`data.results[].subMerchantNo`	string	是	该 MED 所属二级商户号；直连商户固定为空字符串，可忽略。
`data.results[].status`	string	是	MED 当前状态，取值见上方 MED `status` 枚举。
`data.results[].originSituationType`	string	是	引发该 MED 的情形类型，取值见 MED API 总览的枚举值与状态说明。
`data.results[].amount`	decimal	是	MED 涉及的交易金额；整数部分最长 25 位，小数部分最长 4 位，且不为负数。
`data.results[].analysisResult`	string	否	分析结果：`ACCEPTED`（已接受）或 `REJECTED`（已驳回）；尚未作出分析时为 `null`。
`data.results[].dueTime`	string	否	举证截止时间，须在该期限前完成材料上传与分析提交，ISO 8601 UTC 时间字符串（`yyyy-MM-ddTHH:mm:ssZ`）；未设置时为 `null`。
`data.results[].createdAt`	string	是	MED 记录创建时间，ISO 8601 UTC 时间字符串（`yyyy-MM-ddTHH:mm:ssZ`）。
`data.results[].updatedAt`	string	是	MED 记录最后更新时间，ISO 8601 UTC 时间字符串（`yyyy-MM-ddTHH:mm:ssZ`）。

列表项其余分组（`data.results[]`）

字段名	类型	是否必返	说明
`data.results[].transaction`	object	是	引发该 MED 的 Pix 交易信息，字段与详情接口 `data.transaction` 一致。
`data.results[].payer`	object	是	付款方信息（发出 Pix 的一方），字段与详情接口 `data.payer` 一致，但不含 `bankAccount`。
`data.results[].payee`	object	是	收款方信息（接收 Pix 的一方），字段与详情接口 `data.payee` 一致，但不含 `bankAccount`。
`data.results[].infractionReport`	object	是	央行违规报告信息，字段与详情接口 `data.infractionReport` 一致。

响应示例

json

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "next": "https://api.adopay.com.br/meds/list?id=medc2874510938274639021&direction=next&limit=5",
    "previous": null,
    "results": [
      {
        "medId": "medc2874510938274639021",
        "subMerchantNo": "",
        "status": "WAITING",
        "originSituationType": "SCAM_FRAUD",
        "amount": 1000.50,
        "analysisResult": null,
        "dueTime": "2026-01-31T23:59:59Z",
        "createdAt": "2026-01-15T14:30:00Z",
        "updatedAt": "2026-01-15T14:30:00Z",
        "transaction": {
          "e2eId": "E1234567820240115143000123",
          "transactionDate": "2026-01-15T14:30:12Z",
          "merchantOrderNo": "PIX20260816000001",
          "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
        },
        "payer": {
          "name": "João Silva",
          "document": "12345678901",
          "email": "user@example.com",
          "phone": "+5511999999999"
        },
        "payee": {
          "name": "John Doe",
          "document": "12345678000195"
        },
        "infractionReport": {
          "id": "report-456",
          "status": "RECEIVED",
          "createdAt": "2026-01-15T14:30:00Z",
          "creatorPsp": "12345678"
        }
      }
    ]
  }
}

响应错误码

响应状态

返回 MED API 总览

账户

收款

付款

PixKey管理

对账文件

MED

Webhook 事件

`/meds/list` 接口介绍

接口背景

接口请求地址

认证

接口请求字段

`status` MED 状态枚举

`infractionReportStatus` 违规报告状态枚举

过滤规则

分页行为

请求示例

接口响应字段

分页字段

列表项概要字段（`data.results[]`）

列表项其余分组（`data.results[]`）

响应示例

响应错误码

/meds/list 接口介绍 ​

接口背景 ​

接口请求地址 ​

认证 ​

接口请求字段 ​

status MED 状态枚举 ​

infractionReportStatus 违规报告状态枚举 ​

过滤规则 ​

分页行为 ​

请求示例 ​

接口响应字段 ​

分页字段 ​

列表项概要字段（data.results[]） ​

列表项其余分组（data.results[]） ​

响应示例 ​

响应错误码 ​

`/meds/list` 接口介绍

接口背景

接口请求地址

认证

接口请求字段

`status` MED 状态枚举

`infractionReportStatus` 违规报告状态枚举

过滤规则

分页行为

请求示例

接口响应字段

分页字段

列表项概要字段（`data.results[]`）

列表项其余分组（`data.results[]`）

响应示例

响应错误码