10. 订单、支付与回调 API 10.5.1 Apple IAP 恢复购买【待真实小票联调】

Table of Contents

10.5.1 Apple IAP 恢复购买【待真实小票联调】

POST /tieup/api/v1/apple-iap/purchases/restore
Authorization: Bearer <access_token>
Content-Type: application/json

请求体：

{
  "receipt_data": "base64-encoded-app-receipt",
  "transaction_id": "1000000123456789",
  "product_id": "com.tieup.sub.month",
  "application_username": "550e8400-e29b-41d4-a716-446655440000",
  "original_transaction_id": "1000000123450000"
}

请求字段：

字段 类型 必填 说明
receipt_data string 是 StoreKit 1 App Receipt Base64 字符串
transaction_id string 是 本次需要恢复的 Apple 交易号
product_id string 是 Apple 商品 ID，必须与验票结果和订单快照一致
application_username string 是 创建订单时返回并提交给 StoreKit 的值；只用于缩小当前用户候选订单范围，不能证明归属
original_transaction_id string 否 Apple 原始订阅链交易号，仅参与验票交易匹配

成功响应与 10.5 Apple IAP 小票确认一致，完整示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "ack": true,
    "duplicate": false,
    "order_no": "TO202607270001",
    "transaction_no": "TP202607270001",
    "delivery": {
      "delivered": true,
      "subscription_no": "SUB2026072715000012345678",
      "expires_at": "2026-08-26 15:00:00"
    },
    "subscription": {
      "subscription_no": "SUB2026072715000012345678",
      "artist_id": 1,
      "status": 1,
      "is_auto_renew": 1,
      "expires_at": "2026-08-26 15:00:00",
      "original_transaction_id": "1000000123450000",
      "latest_transaction_id": "1000000123456789",
      "latest_apple_notification_type": null,
      "latest_apple_subtype": null,
      "auto_renew_status": null
    }
  }
}

候选无法唯一定位响应：

{
  "code": 422,
  "message": "Apple购买无法唯一定位原订单",
  "data": {
    "error_code": "apple_restore_order_ambiguous",
    "candidates": [
      {
        "order_no": "TO202607270001",
        "artist_id": 1,
        "subscription_plan_code": "month_30",
        "sub_type": "month",
        "subscription_action": "initial",
        "payment_method": "apple_iap",
        "payment_amount": "30.00",
        "payment_expires_at": "2026-07-27 15:30:00",
        "remaining_seconds": 0
      }
    ]
  }
}

业务规则：服务端先使用启用的 Apple IAP 支付账号独立验票，再按支付账号和 Apple 交易唯一键、永久订阅链绑定、当前 Tieup 用户及订单商品快照定位原订单。同一用户已绑定交易按幂等成功返回；不同用户统一返回“无法在当前 Tieup 账号恢复”，不泄露对方信息。application_username 和 Apple ID 均不能替代 Tieup 用户归属。