回调通知接口

回调通知接口用于平台向商户推送各类实时通知，包括订单状态变更、退款申请等。

# 1. 商户回调地址注册

POST /merchant/callback/register

商户注册接收回调通知的URL地址。

请求参数

参数名 类型 必填 描述
callback_type Integer 是 回调类型：1-订单状态变更，2-退款申请，3-库存变更
callback_url String 是 回调URL地址
description String 否 描述信息

响应参数

字段名 类型 描述
callback_id String 回调配置ID

请求示例

{
  "callback_type": 1,
  "callback_url": "https://api.merchant.com/callback/order-status",
  "description": "订单状态变更回调"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "callback_id": "CB20230615001"
  },
  "timestamp": 1623123456789
}

# 2. 订单状态变更通知

POST {merchant_callback_url}

平台在订单状态发生变化时，向商户推送通知。

请求参数

参数名 类型 必填 描述
notification_id String 是 通知ID
notification_type String 是 通知类型：ORDER_STATUS_CHANGE
order_id String 是 订单ID
previous_status Integer 是 之前状态
current_status Integer 是 当前状态
change_time String 是 状态变更时间，格式：yyyy-MM-dd HH:mm:ss
remark String 否 备注信息

响应参数

字段名 类型 描述
notification_id String 通知ID
success Boolean 处理结果
message String 处理结果描述

请求示例

{
  "notification_id": "NT2023061500001",
  "notification_type": "ORDER_STATUS_CHANGE",
  "order_id": "PO2023061512345678",
  "previous_status": 10,
  "current_status": 20,
  "change_time": "2023-06-15 15:30:25",
  "remark": "订单已发货"
}

响应示例

{
  "notification_id": "NT2023061500001",
  "success": true,
  "message": "通知处理成功"
}

# 3. 退款申请通知

POST {merchant_callback_url}

平台在收到用户退款申请时，向商户推送通知。

请求参数

参数名 类型 必填 描述
notification_id String 是 通知ID
notification_type String 是 通知类型：REFUND_REQUEST
order_id String 是 订单ID
refund_id String 是 退款申请ID
refund_amount Decimal 是 退款金额
refund_type Integer 是 退款类型：1-未收到货，2-质量问题，3-商品与描述不符，4-其他
refund_reason String 是 退款原因
apply_time String 是 申请时间，格式：yyyy-MM-dd HH:mm:ss
images Array 否 凭证图片URL列表

响应参数

字段名 类型 描述
notification_id String 通知ID
success Boolean 处理结果
message String 处理结果描述

请求示例

{
  "notification_id": "NT2023061500002",
  "notification_type": "REFUND_REQUEST",
  "order_id": "PO2023061512345678",
  "refund_id": "RF2023061500001",
  "refund_amount": 30.00,
  "refund_type": 2,
  "refund_reason": "商品有损坏",
  "apply_time": "2023-06-15 16:30:25",
  "images": [
    "https://example.com/images/refund/001.jpg",
    "https://example.com/images/refund/002.jpg"
  ]
}

响应示例

{
  "notification_id": "NT2023061500002",
  "success": true,
  "message": "退款申请通知处理成功"
}

# 4. 回调测试接口

POST /merchant/callback/test

测试商户回调接口是否正常响应。

请求参数

参数名 类型 必填 描述
callback_type String 是 回调类型：order-订单通知，inventory-库存变更通知，refund-退款通知

响应参数

字段名 类型 描述
success Boolean 测试是否成功
http_status_code Integer HTTP状态码
response_time Integer 响应时间(毫秒)
message String 结果说明

请求示例

{
  "callback_type": "order"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "success": true,
    "http_status_code": 200,
    "response_time": 120,
    "message": "回调测试成功"
  },
  "timestamp": 1623123456789
}