常见问题

一、商品券管理

Q：为什么单券-全场的场景下，【优惠力度】single_usage_info是在商品信息中配置，单券-单品场景下又是在【批次】stock 里配置优惠力度？

A：
全场券的【优惠力度】 single_usage_info属于商品信息中的一部分，不同优惠力度的全场券代表不同的商品，批次则主要负责管理的是库存、预算、有效时间等信息。
例：“A饮品全场七折券”、“B饮品全场八折券”，购买不同的饮品就享受不同的折扣优惠。
单品券的【优惠力度】 single_usage_rule属于【批次信息】stock中的一部分，同一个商品在不同批次可以设置不同的优惠力度，以实现将不同优惠力度投放给不同目标人群。
例：“某某饮品优惠券”，创建了不同优惠力度的批次，不同目标人群领券后购买同一单品，能享受到的优惠不同。

Q：【商品券详情图列表】detail_image_url_list会校验尺寸、格式和大小吗？

A：格式支持：jpg、png，以及大小不能超过2M，要求图片宽高比65:77，尺寸不做校验但是商户需关注前端展示效果，推荐尺寸1170*1326

Q：商品券的批次有效期要间隔多久才能用于创建投放计划？

A：【批次开始时间】available_begin_time 与【批次结束时间】available_end_time 间隔大于5天。

更多投放计划字段详情可参考：投放计划配置指引-字段介绍

Q：商品券各个字段在客户端的展示效果是怎样的？

A：可参考产品示例图（单券）和产品示例图（多次优惠）

Q：创建商品券设置【券可核销时间】coupon_available_period 时，设置了多种可核销的时间段，券的实际可核销时间会如何取值？

A：会取各时间段的“交集”时间，具体可参考文档：商品券可核销时间规则说明

Q：调用“创建商品券”接口报错：appid非法

A：请按以下几点排查：

1、appid本身的值是否正确，不能填写不存在的appid

2、appid是否为品牌关联的appid，appid需要通过“交易连接名片”功能进行关联，两种关联方式：

• 方式一：服务商通过商家名片下的“交易连接名片”功能，为品牌方关联appid。（目前只支持服务商模式）

• 方式二：品牌方在【品牌经营平台-商家名片-交易链接名片】关联appid。

二、商品券批次管理

Q：调用“修改商品券批次(组)发放预算”接口减少【目标批次发放次数总上限】target_max_count，若此时已上传的code数量超过批次的减少后的总上限，是否会有影响？

A：无影响，若后续修改扩充批次(组)的【目标批次发放次数总上限】target_max_count，将沿用已上传的券code用于发券。

Q：调用“修改商品券批次(组)发放预算”接口，报错：商品券批次当前每日发放次数上限与真实值不符

A：请求参数中【当前批次发放次数总上限】current_max_count的值与该批次(组)当前实际生效的每日发放次数上限不一致，可调用"查询商品券指定批次"接口确认批次(组)当前的每日发放次数上限。

三、商品券发放

Q：测试人员通过预览投放计划的二维码，扫码进入领券页面，点击领取时提示“领取失败，请稍后再试”是什么原因？

A：请检查以下几点：

1、投放计划配置的商品券批次库存是否充足。
注意：调用“创建商品券/添加商品券批次(组)”接口时设置的 【券Code分配模式】若为: "品牌方预上传Code"（"coupon_code_mode":"UPLOAD"）,则需通过调用【预上传券Code】接口补充库存，code不足将无法发券。

2、测试场景会展示两个同样的领券页面，第一张领取后，接着领取第二张会报该错误（正式环境会展示不同的券，不会有该问题），可重新扫码进入新的测试领券的页面。

四、商品券回调通知

Q：领取商品券后，为什么无法接收到商品券回调通知？

A：请参考以下几点进行排查：

1、回调地址配置类问题

1.1、地址配置错误

• 商户在“设置商品券事件通知地址 ”接口中配置的【通知URL地址】 notify_url存在拼写错误（如域名错写、路径漏填）；

• 地址未使用公网可访问的 HTTPS 协议（微信支付强制要求回调地址为 HTTPS）；

• 使用了内网地址（如192.168.x.x、localhost），微信支付服务器无法穿透内网访问。

1.2、地址未完成备案 / 解析异常

• 回调地址对应的域名未完成工信部 ICP 备案（国内服务器必选，境外服务器虽无需备案，但需确保域名解析正常）；

• 域名 DNS 解析失效（如解析记录过期、未配置正确的 A/AAAA 记录），导致微信支付服务器无法解析到商户服务器 IP。

2.1、商户服务器防火墙 / 安全组拦截

• 商户服务器的防火墙（如 Linux iptables、Windows 防火墙）或云服务商安全组，未开放微信支付回调通知的入站请求，需对微信支付回调IP开通白名单，微信支付回调IP列表可查看：回调处理逻辑注意事项；

• 服务器开启了 CC 攻击防护、WAF（Web 应用防火墙）等安全策略，误将微信支付的回调请求判定为恶意请求并拦截。

2.2、网络链路故障

• 商户服务器所在网络存在链路丢包、延迟过高（如超过 3 秒），导致微信支付发送的通知请求超时；

• 商户使用的 CDN 或反向代理（如 Nginx、Cloudflare）配置异常，未将回调请求正确转发至后端业务服务器。

• 如果商户没有设置apiv3key微信支付不会发送回调通知。

• 调用“创建商品券/添加商品券批次(组)”接口时设置的【事件通知AppID】notify_appid是否正确。