IAP 校验接口文档

本服务提供 iOS App Store 与 Android Google Play 内购凭据校验接口。请求与响应均为 JSON，UTF-8 编码。

1. 健康检查

GET /v1/iap/health

用于探测服务是否存活，不校验任何业务参数。

响应示例（200）

{
  "code": 0,
  "status": "ok",
  "timestamp": 1730123456789
}

2. 校验凭据

POST /v1/iap/validate

校验一次内购凭据（iOS 收据或 Android 购买令牌），支持一次性购买与订阅。相同凭据重复提交会走幂等逻辑并返回缓存结果。

请求体（Content-Type: application/json）

字段	类型	必填	说明
`gameId`	string	是	游戏标识，需在服务端配置中已登记（如 `solitaire_2026`）
`platform`	string	是	平台：`ios` 或 `android`
`purchaseType`	string	是	购买类型：`inapp`（一次性）或 `subscription`（订阅）
`userId`	string	否	业务侧用户 ID，仅用于日志与审计
`receiptData`	string	iOS 必填	支持两种格式：App Store 收据 Base64（verifyReceipt）或 StoreKit 2 交易 JWS（`header.payload.signature`）
`purchaseToken`	string	Android 必填	Google Play 返回的购买令牌
`productId`	string	Android 必填	商品 ID（与 Google Play 一致）

请求示例（iOS 一次性购买）

{
  "gameId": "solitaire_2026",
  "platform": "ios",
  "purchaseType": "inapp",
  "userId": "user_123",
  "receiptData": "MIIbogYJKoZIhvcNAQcCoIIbkzCCG48CAQExCz..."
}

请求示例（Android 一次性购买）

{
  "gameId": "solitaire_2026",
  "platform": "android",
  "purchaseType": "inapp",
  "userId": "user_123",
  "purchaseToken": "xxx.google.purchase.token.xxx",
  "productId": "com.example.coins_100"
}

成功响应（200）

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": true,
    "transactionId": "1000000123456789",
    "productId": "com.example.coins_100",
    "purchaseTime": 1730123456789,
    "expiresTime": 1732723456789,
    "environment": "sandbox",
    "platform": "ios",
    "purchaseType": "inapp"
  }
}

expiresTime 仅订阅类型存在；environment 仅 iOS 存在（sandbox / production）。

错误响应（4xx / 5xx）

统一 JSON 格式：

{
  "code": "IAP_xxx",
  "message": "人类可读说明",
  "traceId": "uuid"
}

错误码说明

code	HTTP 状态	说明
`IAP_MISSING_PARAMS`	400	缺少必填参数（如 gameId、receiptData、purchaseToken 等）
`IAP_GAME_NOT_FOUND`	400	gameId 未在服务端配置
`IAP_UNSUPPORTED_PLATFORM`	400	platform 非 ios/android 或 purchaseType 非法
`IAP_PLATFORM_NOT_CONFIGURED`	400	该游戏未配置对应平台（iOS/Android）凭据
`IAP_INVALID_RECEIPT`	400	凭据无效、过期或格式错误（含 Apple 返回的非 0 状态）
`IAP_RECEIPT_EXPIRED`	400	订阅已过期
`IAP_BUNDLE_ID_MISMATCH`	400	iOS 收据的 bundle_id 与配置不一致
`IAP_DUPLICATE_RECEIPT`	409	同一凭据已成功校验过（幂等冲突）
`IAP_APPLE_API_ERROR`	502	调用 Apple 接口异常
`IAP_GOOGLE_API_ERROR`	502	调用 Google Play 接口异常

Game Manager Service · IAP 校验 API