验券

更新时间 2024-09-09 04:04:05

我的收藏

用于核销券码，同时适用于抖音团购券码与三方券码，抖音券码的核销需要先调用准备接口，再调用本接口，三方券码的核销直接调用本接口即可。

使用限制

无

接口说明

同时适用于抖音团购券码与三方券码

抖音团购券码的核销需要先调用验券准备接口, 再调用本接口

三方券码的核销直接调用本接口即可

可支持多个批量验券, 需为同一个订单，不可跨订单验券, 且三方码场景下必传抖音侧订单 ID 参数

error_code、result 均为 0 代表验券成功。error_code非0时则表示调用验券接口失败，建议服务商侧主动发起重试，建议间隔5s发起。第一次调用error_code非0，第二次调用error_code=0且result=1208或2，也可以代表验券成功

三方码同一笔订单下如有多张券，在发起验券的时候，不可同时发起多次请求，需等待前一次请求有响应再发起下次请求

接口报错返回”服务器错误，请稍后重试“、“您的访问过于频繁，请稍后重试”等建议重试的文案后，建议以如下重试策略进行重试，接口成功返回后即可停止重试：

前5次重试以5s间隔进行

之后以40s间隔进行

最高重试14次，如果接口依然报错，请进线反馈

基本信息

HTTP URL	https://open.douyin.com/goodlife/v1/fulfilment/certificate/verify/
HTTP Method	POST
申请权限	团购核销
权限要求	•需要申请权限，路径：抖音开放平台-开发者平台/服务商平台>控制台>应用详情>解决方案 •需要商家授权，路径：抖音来客>店铺管理>第三方应用授权

请求头

参数	描述	必须
content-type	application/json	是
access-token	根据这个地址获取的token	是

请求参数

Body 请求

参数名称	参数类型	参数描述	必需
verify_token	string	一次验券的标识 (用于短时间内的幂等) •针对三方码订单，每次请求都需要保证幂等！（请求维度，非券码/订单维度）	是
poi_id	string	核销的抖音门店id 如何获得抖音门店id，可以参考：门店关联及匹配能力	是
encrypted_codes	list	验券准备接口返回的加密抖音券码 •多次卡商品，如果需要一次核销多份，list中传多个相同encrypted_code	否
codes	list	三方原始券码值列表 (encrypted_codes/codes/code_with_time_list必须三选一) •多次卡商品，如果需要一次核销多份，list中传多个	否
order_id	string	抖音侧的订单号 (非预导码模式的三方券码必需)	否
code_with_time_list	list	带有核销时间的三方码列表备注：如果code_with_time_list 和 codes 同时传，本字段优先级更高	否
.code	string	三方码	否
.verify_time	int64	核销时间戳（秒）	否
.verify_sign_list	list	验签	否
voucher	struct	多项目多凭证的情况备注：景区预售券核销必传，非景点预售券核销可忽略！注：此参数只进行数据同步，不进行真实券核销！待预约结束时间+24小时后，履约单会自动推核销状态为已履约	否
.project_id	string	项目唯一标识（有校验，景区预售券必传）	否
.id_card_list	list	身份证号码（身份证号码、二维码、券号至少填一个）	否
.qrcode_list	list	二维码（身份证号码、二维码、券号至少填一个）	否
.certificate_no_list	list	券号（身份证号码、二维码、券号至少填一个）	否
.verify_time	int64	核销时间戳（秒）（景区预售券必传）	否
vouchers	list	针对团购景区套票	否
.project_id	string	项目唯一标识（有校验，团购景区套票必传）	否
verify_extra	struct	核销额外参数	否
.total_verify	bool	整体核销标识，批量核销时传此参数为true则会在不能全部核销成功时报错（幂等也算核销成功）此字段只支持三方码团购；抖音码团购此字段无效；次卡此字段无效，次卡默认整体核销；	否
.dynamic_coupon_info	struct	动态代金券额外参数（动态代金券必传）	否
..biz_time	int64	开台时间（秒）（动态代金券必传）	否
..actual_deduction_amount	int64	实际抵扣金额（动态代金券必传）	否

请求示例

js复制
https://open.douyin.com/goodlife/v1/fulfilment/certificate/verify/

json复制
{
  "verify_token": "211ecb01-9f97-46e1-98db-b2cbecfbfd7e",
  "encrypted_codes": [
    "CgwIARDhJxjLLyABKAESLgosRSH/OAfU5+MZ9y0u3l/999bpcS5P1zOqn2mxgQXAx3jGpwb+jnqZPTlDldcaAA=="
  ],
  "poi_id": "111111"
}

响应参数

参数名称	参数类型	参数描述
data	struct
.error_code	int64	错误码，0为成功
.description	string	错误码描述
.verify_results	list	验券结果
..result	int32	验券结果码，0表示成功，非0表示失败
..msg	string	验券结果说明
..code	string	代表验券传入的code或encrypted_code
..verify_id	string	代表券码一次核销的标识（撤销时需要，撤销后会变）
..order_id	string	代表一张订单的标识
..certificate_id	string	代表一张券码的标识（撤销时需要），不等于券码但与券码一一对应，验券前可通过订单接口查询
..certificate_no	string	代表验券传入的certificate_no_content
..origin_code	string	代表抖音团购券的12位或15位原始券码（抖音加密券码核销时）
..account_id	string	代表企业号商家总店id（查询验券历史时需要）
..project_id	string	项目唯一标识
..id_card	string	代表验券传入的id_card_content
..qrcode	string	代表验券传入的qrcode_content
..verify_amount_info	struct	核销金额信息（仅次卡核销返回）
...times_card_amount	struct	【deprecated，不建议用，后期会下掉】次卡单笔核销金额
....amount	int64	【deprecated，不建议用，后期会下掉】单次核销金额（当前次卡未接入营销活动，因此原价 = 用户实付）
...times_card_serial_amount	struct	对应核销序号的金额明细
....serial_numb	int32	次序号
....amount	struct	对应次序号的金额信息
.....original_amount	int32	原始金额，单位分
.....pay_amount	int32	用户实付金额，单位分（包含支付优惠/次数）
.....merchant_ticket_amount	int32	商家营销金额，单位分
.....list_market_amount	int32	划线价，单位分
.....platform_discount_amount	int32	平台优惠金额，单位分
.....payment_discount_amount	int32	支付优惠金额，单位分
.....coupon_pay_amount	int32	券实付金额（=用户实付金额+支付优惠金额），单位分
.sub_error_code	int64	（弃用）子错误码
.sub_description	string	（弃用）子错误码描述
.logid	string	请求id
.now	int64	（弃用）接口响应时间，时间戳，单位秒

响应示例

正常示例

json复制
{
  "data": {
    "error_code": 0,
    "description": "success",
    "verify_results": [
      {
        "result": 0,
        "msg": "验券成功",
        "code": "CgwIARDhJxjLLyABKAESLgosTYTOIJFLZx8IaWKdO9ISKSWf4XYaqzt8TU1fhbTpYhIAuA5i5fRYfApwNRMaAA==",
        "verify_id": "7091478021421631519",
        "certificate_id": "7091180835810052103",
        "origin_code": "102539929601",
        "account_id": "123456"
      }
    ]
  },
  "extra": {
    "error_code": 0,
    "description": "success",
    "sub_error_code": 0,
    "sub_description": "",
    "logid": "xxx",
    "now": 1651113600
  }
}

异常示例

参考下述错误码和枚举。

错误码

HTTP 状态码	错误码	描述	排查建议
200	2190002	access_token无效	调用接口重新生成access_token
200	2190004	应用未获得该能力, 请去https://open.douyin.com/申请	应用申请接口权限
200	2190008	access_token过期,请刷新或重新授权	规范token刷新机制，检查是否有测试环境在同步刷新token
200	2119001	参数不合法	更换参数
200	2119002	系统繁忙，请稍候再试	重试
200	2119003	请求太过频繁，请稍后再试	重试
200	2119005	应用未获商家授权	联系合作商家在商家后台发起授权，并在服务商后台同意授权
200	3000001	根据实际业务错误返回	对照接口文档规范参数并重试
200	4000001		补充参数
200	4000002		对照接口文档规范参数并重试
200	5000001		联系抖音处理
200	3000002	核销门店错误	检查核销门店重试
200	3000020	无核销记录可撤销	查看是否核销过再重试

verify_results 枚举

•

核销次卡枚举（三方码）

•

备注：当前三方码次卡未做result非0的错误枚举，0之外，其他一律返回-1，有需求可向对应产运同学反馈，抖音码次卡同团购错误码

verify_results枚举	枚举说明
0	履约成功
-1	券码已核销
-1	券码正在退款中（用户主动退款）
-1	券码未到可使用日期
-1	券码正在退款中（过期自动退）
-1	券码已退款

•

核销团购枚举（三方码&抖音码）

verify_results枚举	枚举说明
0	验券成功
三方码：1205 抖音码：3	券码正在退款中（用户主动退款）
三方码：1206 抖音码：5	券码未到可使用日期或团购有效期尚未开始
三方码：1207 抖音码：32	券码退款中（过期自动退）
三方码：1208 抖音码：2	券码已核销
三方码：1209 抖音码：4	券码已退款
三方码：1211	其他错误
抖音码：31	券码退款中（用户申请）
抖音码：6	券码已过期，系统将自动发起退款