● 文件 · /v1

文件

上传争议举证材料。文件只用于指定用途,不做通用网盘。

上传文件

POST /v1/files

multipart/form-data,单文件 10 MB 以内,只收 pdf / jpg / png / tiff—— 卡组织不接受其他格式,我们提前拦掉而不是让你败诉。

上传后拿 uid 填到争议举证的 file_ids 里。文件保留 180 天。

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

响应 201

uid string
purpose dispute_evidence 文件用途,上传时指定,之后不可改
filename string
size integer 字节数。单文件上限 10 MB
content_type string
created_at string<date-time>
expires_at string<date-time> 举证材料保留 180 天后自动清理

错误

400参数不合法
请求
curl -X POST https://api.baton.example/v1/files \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."
响应 · 201
{
  "uid": "file_9a21c7",
  "purpose": "dispute_evidence",
  "filename": "proof-of-delivery.pdf",
  "size": 284117,
  "content_type": "application/pdf",
  "created_at": "2026-11-16T09:42:00Z",
  "expires_at": "2027-05-15T09:42:00Z"
}

查询文件

GET /v1/files/{uid}

只返回元信息,不返回内容。已提交举证的文件不可删除,审计需要。

路径参数

uid必填 string

响应 200

uid string
purpose dispute_evidence 文件用途,上传时指定,之后不可改
filename string
size integer 字节数。单文件上限 10 MB
content_type string
created_at string<date-time>
expires_at string<date-time> 举证材料保留 180 天后自动清理

错误

404对象不存在,或属于另一个环境 / 另一个商户
请求
curl -X GET https://api.baton.example/v1/files/{uid} \
  -H "Authorization: Bearer sk_live_xxx"