10. 订单、支付与回调 API 10.14 七牛上传回调【未执行，需三方/真实联调】

Table of Contents

10.14 七牛上传回调【未执行，需三方/真实联调】

POST /tieup/api/v1/webhooks/qiniu/upload-callbacks
Content-Type: application/json
Authorization: QBox <qiniu_callback_sign>

请求参数：

参数 类型 必填 说明
key string 是 七牛对象 Key；服务端也兼容 object_key
hash string 否 七牛文件 hash；服务端也兼容 etag、file_hash
bucket string 否 七牛 bucket；为空时使用当前运行时配置
fsize integer 否 文件大小，单位字节；服务端也兼容 size_byte、file_size
mimeType string 否 文件 MIME 类型；服务端也兼容 mime_type
business_module string 否 业务模块，如 avatar
business_id string 否 业务 ID
upload_no string 否 本地上传流水号；有值时优先按该流水幂等更新
origin_name string 否 原始文件名；服务端也兼容 fname、file_name
user_id integer 否 上传用户 ID

请求体示例：

{
  "key": "uploads/2026/06/demo.png",
  "hash": "FqiniuHash",
  "bucket": "tieup-public",
  "fsize": 123456,
  "mimeType": "image/png",
  "business_module": "avatar",
  "business_id": "10001"
}

响应字段：

字段 类型 说明
code integer 响应码，成功为 200；签名失败为 403，参数或业务处理失败为 422
message string 响应提示
data.record_id integer 上传记录 ID
data.upload_no string/null 本地上传流水号
data.storage_provider string 存储供应商，固定为 qiniu
data.bucket string 七牛 bucket
data.object_key string 七牛对象 Key
data.url string 文件访问 URL
data.origin_name string 原始文件名
data.mime_type string 文件 MIME 类型
data.file_ext string 文件扩展名
data.file_hash string 文件 hash
data.size_byte integer 文件大小，单位字节
data.business_module string 业务模块
data.business_id string 业务 ID
data.user_id integer/null 上传用户 ID
data.status integer 上传记录状态
data.created boolean 是否本次新建；false 表示幂等更新已有记录

响应示例：

{
  "code": 200,
  "message": "七牛上传回调处理成功",
  "data": {
    "record_id": 10001,
    "upload_no": "UP202606170001",
    "storage_provider": "qiniu",
    "bucket": "tieup-public",
    "object_key": "uploads/2026/06/demo.png",
    "url": "https://cdn.example.com/uploads/2026/06/demo.png",
    "origin_name": "",
    "mime_type": "image/png",
    "file_ext": "png",
    "file_hash": "FqiniuHash",
    "size_byte": 123456,
    "business_module": "avatar",
    "business_id": "10001",
    "user_id": null,
    "status": 1,
    "created": true
  }
}

说明：

  • 由七牛云调用，不面向 APP。
  • 验签后写入或更新 tieup_upload_record，优先按 upload_no 幂等，没有上传流水时按 storage_provider + bucket + object_key 唯一约束兜底。
  • 回调入口会先写入 tieup_qiniu_upload_callback_log：配置缺失、验签失败、JSON 载荷异常和业务处理失败均可追踪；Authorization 仅保存有限前缀和 SHA-256 摘要，不保存签名明文。
  • 仅 verify_status = 1、handle_status = 2 且存在 normalized_payload 的业务处理失败日志允许 qiniu-replay 重放；验签失败、配置缺失或未标准化载荷不会重放，避免绕过七牛原始验签。
  • 测试状态：已完成代码实现、PHP 语法检查和静态分析，新增 SQL databases/selfbuilt/updates/20260611_tieup_qiniu_upload_callback_log.sql 需手动导入；该脚本会按存在性补齐七牛回调日志字段和关键索引，重复导入或半导入恢复时输出 skip 信息；待七牛真实回调联调。