更新时间：2025-03-12 15:20:57收藏订阅更新我的文档设置返回文档完成 接入准备 后，商家/服务商可根据本文指引快速接入 私域营销。说明：●私域营销 支持自研商家/isv 通过 自研应用 或 第三方应用 自调用（不传 app_auth_token）或代调用（传 app_auth_token）方式，调用 api 接入。●私域营销 支持沙箱调试。●私域营销 仅支持 2021-12-01 日后创建的支付券或商家券活动。1 完整接口时序图2 接入代运营授权服务商代商家接入 私域营销 前，需根据商家身份确定是否进行代运营授权。注意：自研商家无需进行代运营授权。2.1 代运营授权适用商家：间连商家、直连商家。服务商需向商家发起营销代运营授权，商家在支付宝上授权后，服务商能代商家进行券发放等营销活动操作，详情可查看 接口代运营授权。注意：代运营授权：●支持服务商使用自研应用及第三方应用自调用（即无需传入 app_auth_token）方式进行接入。●（向商户发起代运营操作接口）operate_type（操作类型）参数需传入 operation_auth（授权操作）类型。3 接入私域营销3.1 查询营销活动商家/服务商可按如下指引调用接口，接入活动批量查询、参与咨询、详情查询等接口。3.1.1 条件查询活动列表商家/服务商需调用 批量查询营销活动（支持商家券、支付券），获取活动列表。注意：●该接口为准实时接口，变更活动后到该接口可以查询出变更后的活动数据中间存在一定延迟，正常情况下平均延迟时间小于 1 分钟，最长不超过 1 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。●该接口只能查询出有效数据，若商家主动终止活动或者活动已过期则该接口无法查询到该活动，暂停的活动仍然可以查询。●服务商与商家建立代运营授权关系后，可以通过 merchant_id 参数，查询指定商家的活动。请求示例响应示例3.1.2 活动参与咨询通过条件查询活动后，商家/服务商可调用 alipay.marketing.activity.consult（活动领取咨询接口）判断当前用户是否可以参与此活动。接口根据活动创建时设置的活动参与规则与风控规则判断当前用户是否可以参与活动。注意：●本接口支持批量传入活动，每次传入数量不得超过 10 个。●调用接口完成后，可以通过返回的结果决定活动是否要展示给当前用户（不可参与的活动展示给用户会影响用户体验）。请求示例响应示例3.1.3 活动详情查询商家/服务商需调用 查询活动详情信息。注意：该接口可以查询出商家/服务商在 、 或通过 支付券、商家券 api 创建的活动。请求示例响应示例3.2 活动适用范围商家/服务商可按如下指引调用接口，接入私域营销 活动适用商户、活动适用小程序、活动适用门店、活动适用商户 接口，灵活判断指定活动适用范围。3.2.1 接口调用流程3.2.2 活动适用商家商家/服务商可调用 查询指定活动适用商户范围或判断某活动在商家处是否可用。注意：●该接口为准实时接口，变更活动适用商家到该接口查询出变更后的适用商家范围中间存在一定延迟，正常情况下平均延迟时间小于 1 分钟，最长不超过 1 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。●无论间连商户还是直连商户必须有蚂蚁门店该接口才会返回对应的适用商家范围。●商家券场景下只有指定蚂蚁门店可用才会返回对应的适用商家范围。请求示例响应示例3.2.3 活动适用小程序商家/服务商可调用 查询指定活动适用小程序范围或判断某活动在小程序是否可用。注意：该接口为准实时接口，变更活动适用小程序到该接口查询出变更后的适用小程序范围中间存在一定延迟，正常情况下平均延迟时间小于 1 分钟，最长不超过 1 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。请求示例响应示例3.2.4 活动适用门店商家/服务商可调用 查询指定活动适用门店范围或判断某活动在门店是否可用。注意：该接口为准实时接口，变更活动适用门店到该接口查询出变更后的适用门店范围中间存在一定延迟，正常情况下平均延迟时间 30 分钟，最长不超过 3 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。请求示例响应示例3.2.5 活动适用商品商家/服务商可调用 查询指定活动适用商品范围或判断某活动该商品是否可用。注意：●该接口为准实时接口，变更活动适用商品到该接口查询出变更后的适用商品范围中间存在一定延迟，正常情况下平均延迟时间 30 分钟，最长不超过 3 小时。商家/服务商在开发时应充分考虑延迟可能带来的问题。●因为目前商家券创建未上传商品编码所以该接口暂不支持商家券。请求示例响应示例3.3 用户领券核销商家/服务商需要接入私域营销领券插件，用户触发领券操作后商家/服务商小程序前端调用领券插件为用户发券，发券成功后支付宝会发送领券消息给当前发券 appid。3.3.1 领券插件支付宝为商家小程序提供了 领券组件插件 可在小程序内向指定用户发放指定券活动 id 支付宝优惠券。用户通过该插件领取优惠券后，将自动加入支付宝卡包，提升用户领券感知及核销率。接入详情参见 领券组件插件接入流程。3.3.2 用户券核销用户领券成功后，支付券通过支付宝支付时核销，商家券通过商家/服务商自身系统核销后。支付宝将会发放核销消息给领券时的 appid。3.4 商户卡包商家/服务商可按如下指引调用接口，接入私域营销 条件查询用户券、查询用户券详情 接口，实现商户自定义卡包。注意：商户卡包相关接口 条件查询用户券、查询用户券详情 目前 不支持三方应用自调用 方式接入。3.4.1 接口调用流程3.4.2 用户授权商家/服务商查询用户券信息需要获取用户授权，用户授权通过后才能调用用户券查询接口查询用户券信息。注意：用户券查询请求授权 scope 为 voucher_query，调用 my.getauthcode 获取 authcode，更多详情见 用户授权 流程。3.4.3 条件查询用户券商家/服务商可调用 按条件批量查询用户券信息。注意：该接口目前 不支持三方应用自调用 方式接入。请求示例响应示例3.4.4 查询用户券详情商家/服务商可调用 查询指定用户券详细信息。注意：该接口目前 不支持三方应用自调用 方式接入。请求示例响应示例4 消息通知用户领券、核销、券过期等场景，支付宝都将通过 from 蚂蚁消息通知 向 商家应用 或 第三方应用 应用网关 推送异步通知消息，同步对应操作结果。若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。4.1 第一步：订阅消息商家/isv 需根据 订阅消息 指引，为接入私域营销的 商家应用 或 第三方应用 订阅如下消息接口。注意：●仅完成订阅后才会收到支付宝发送的对应异步通知消息。●商家/服务商可通过消息通知中 msg_method 参数判断消息类型。消息接口英文名消息接口中文名作用alipay.marketing.activity.message.received券领取消息同步用户领券及对应券信息。alipay.marketing.activity.message.used券核销消息同步用户券核销及对应券信息。alipay.marketing.activity.message.expired券过期消息同步用户券过期及对应券信息。4.2 第二步：验签商家/服务商可使用支付宝 sdk 根据 使用生成密钥验签 指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。4.3 第三步：反馈消息接收结果收到异步通知后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其他值，表示消息获取失败，支付宝会根据 投递重试策略 重新发送消息到应用网关地址。说明：在接收异步消息后进行验签，如果验签成功输出 success，验签失败返回 fail，重新接收异步消息进行处理。响应值描述是否重试fail消息获取失败重试success消息获取成功不重试4.4 用户券消息通知4.4.1 用户领券通知无论是 pc 端或 api 创建的活动，只要是用户通过私域营销领券插件领取的优惠券，支付宝将通过 alipay.marketing.activity.message.received（券领取通知接口）同步领券用户 receive_user_id 或 receive_open_id（支付宝用户 id）、voucher_code（优惠券码）等信息到领券的 appid。消息示例4.4.2 用户券核销通知无论是 pc 端或 api 创建的活动，只要是用户通过私域营销领券插件领取的优惠券，支付宝将通过 alipay.marketing.activity.message.used（券核销消息接口）同步券核销用户 user_id 或 open_id（ 支付宝用户 id）、voucher_code（优惠券码）等信息到领券的 appid。消息示例4.4.3 用户券过期通知无论是 pc 端或 api 创建的活动，只要是用户通过私域营销领券插件领取的优惠券，支付宝将通过 alipay.marketing.activity.message.expired（券过期消息接口）同步券过期用户 user_id 或 open_id（支付宝用户 id）、voucher_code（优惠券码）等信息到领券的 appid。消息示例
