卡密兑换

描述

第三方应用使用此接口为不二云微系统已有会员兑换卡密，并执行卡密配置的奖励。会员可以通过用户ID或手机号识别；使用手机号时不会自动注册新会员。

同一卡密由同一会员重复提交时返回原兑换结果，不会重复发放奖励。同一卡密不能由其他会员再次兑换。

接口说明

授权对象 APP

请求地址 POST /notify/notice

请求规则 请查阅开发必读

请求参数

参数名称	变量名称	参数类型[长度限制]	是否必填	描述
操作类型	type	string[1, 32]	是	body固定为card_code_redeem。
兑换数据	data	string	是	body序列化后的JSON字符串，字段见兑换数据。不能直接传JSON对象。

兑换数据 data

参数名称	变量名称	参数类型[长度限制]	是否必填	描述
用户ID	uid	uint32	条件必填	bodydata内字段。不二云微系统用户ID。uid与mobile至少填写一个。
手机号	mobile	string[11]	条件必填	bodydata内字段。已注册不二云微系统会员的中国大陆手机号。手机号必须匹配唯一会员；uid与mobile同时填写时必须属于同一会员。
卡密	code	string[1, 128]	是	bodydata内字段。完整卡密，兑换时不区分大小写。

请求示例

通过手机号兑换：

{
  "type": "card_code_redeem",
  "data": "{\"mobile\":\"13800138000\",\"code\":\"aB3dE5fG7hJ9kL2mN4pQ6rS8\"}"
}

通过用户ID兑换：

{
  "type": "card_code_redeem",
  "data": "{\"uid\":73,\"code\":\"aB3dE5fG7hJ9kL2mN4pQ6rS8\"}"
}

请求签名必须使用最终发送的JSON原文计算，不能使用转义前的data对象计算。

响应参数

参数名称	变量名称	参数类型	是否必填	描述
卡密信息	item	object	是	已兑换的卡密信息。
奖励发放记录	completion	object	是	本次兑换对应的奖励发放记录。
跳转配置	redirect_url	string	否	卡密活动设置的跳转配置JSON字符串，未设置时为空。

卡密信息 item

参数名称	变量名称	参数类型	是否必填	描述
卡密ID	id	uint32	是	卡密记录ID。
活动ID	activity_id	uint32	是	卡密所属激励活动ID。
卡密	code	string	是	规范化后的完整卡密。
卡密前缀	code_prefix	string	是	卡密前8位，用于后台检索和展示。
状态	status	int32	是	1未兑换，2已兑换，3已过期，4已作废。兑换成功时为2。
过期时间	expire_at	int64	是	Unix时间戳，单位为秒。
批次ID	batch_id	uint32	是	卡密所属批次ID。
卡号	card_no	string	否	导入卡密时设置的外部卡号，未设置时为空。
奖励发放记录	completion	object	是	与响应中的completion对应。

奖励发放记录 completion

参数名称	变量名称	参数类型	是否必填	描述
发放记录ID	id	uint32	是	奖励发放记录ID，可用于问题排查。
活动ID	activity_id	uint32	是	激励活动ID。
用户ID	uid	uint32	是	实际领取奖励的不二云微系统用户ID。
助力用户ID	assist_uid	uint32	是	卡密兑换固定为0。
触发类型	trigger_type	int32	是	卡密兑换固定为1。
发放状态	status	int32	是	1待处理，2处理中，3成功，4待重试，5失败。
奖励类型	reward_type	int32	是	1红包，2券包，3跳转，4积分，5余额，6超级会员天数，7会员等级，8商品套餐。
奖励ID	reward_id	uint32	否	红包、券包、会员等级或商品套餐等奖励的业务ID。
奖励数量	reward_num	uint32	是	奖励发放数量。
奖励值	reward_value	uint32	否	会员天数等整数型奖励值。
奖励金额	reward_amount	double	否	积分或余额等奖励数值。
奖励流水ID	reward_log_ids	string	否	实际奖励流水ID，多个ID使用英文逗号分隔。
重试次数	retry_count	uint32	是	奖励发放重试次数。
失败原因	failed_reason	string	否	奖励发放失败时返回。
完成时间	completed_at	int64	是	Unix时间戳，单位为秒。
发奖时间	rewarded_at	int64	否	Unix时间戳，单位为秒。
创建时间	created_at	int64	是	Unix时间戳，单位为秒。

响应示例

{
  "code": 20000,
  "msg": "success",
  "data": {
    "item": {
      "id": 101,
      "activity_id": 2,
      "code": "aB3dE5fG7hJ9kL2mN4pQ6rS8",
      "code_prefix": "aB3dE5fG",
      "status": 2,
      "expire_at": 1785427200,
      "batch_id": 9,
      "card_no": "",
      "completion": {
        "id": 301,
        "activity_id": 2,
        "uid": 73,
        "assist_uid": 0,
        "trigger_type": 1,
        "status": 3,
        "reward_type": 1,
        "reward_id": 26,
        "reward_num": 1,
        "reward_value": 0,
        "reward_amount": 0,
        "reward_log_ids": "1750",
        "retry_count": 0,
        "failed_reason": "",
        "completed_at": 1784196000,
        "rewarded_at": 1784196000,
        "created_at": 1784196000
      }
    },
    "completion": {
      "id": 301,
      "activity_id": 2,
      "uid": 73,
      "assist_uid": 0,
      "trigger_type": 1,
      "status": 3,
      "reward_type": 1,
      "reward_id": 26,
      "reward_num": 1,
      "reward_value": 0,
      "reward_amount": 0,
      "reward_log_ids": "1750",
      "retry_count": 0,
      "failed_reason": "",
      "completed_at": 1784196000,
      "rewarded_at": 1784196000,
      "created_at": 1784196000
    },
    "redirect_url": ""
  }
}

失败处理

• HTTP状态码为401表示接口签名校验失败，请检查请求头、签名密钥和参与签名的请求原文。
• HTTP状态码为200但响应code不是20000表示业务处理失败，应以code和msg判断结果。
• 卡密不存在、已被其他用户兑换、已过期或已作废时不会发放奖励。
• 同一用户或同一开放应用在5分钟内累计提交10次无效卡密后，将暂时限制继续校验；首次兑换成功后清除失败次数。
• 第三方只需保管开放应用的AppSecret并完成接口签名，不需要获取卡密加密密钥或系统内部奖励密钥。