验券准备
接口说明
抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表,选择要验的券,再调用验券接口,核销券码。
- 抖音团购券码的核销,每次都需要先调用本接口,优先查询订单的券列表,选择要验的券,拿到加密券码encrypted_code,再调用验券接口,核销券码,验券准备和验券接口的调用次数需要一一对应,如已经调用验券接口验券成功,则当前二维码会失效,无法继续使用验券准备接口,需要使用刷新的二维码再进行调用。
- 二维码扫出来是一个短链,示例:https://v.douyin.com/eHHc1ft/ (注:短链的长度不固定,不要对长度做限制或截断,结尾不一定是/),扫码后并调用本接口可返回当前订单下可用的全部券码信息,如未返回券码信息,则说明该订单此刻无可用券码。
- 对短链做 HTTP 请求。得到对应的长链接是https://www.iesdouyin.com/share/commerce/coupon/I0ZwZEZpb2U1N0pjQVZxS2NJRTFSQW5WK1c4bmxvbnNWdUQ2Wk85Y1N0eHpRUFpMMmZwNTdFM2NKeWlFNDM2QT0/?schema_type=13&object_id=I0ZwZEZpb2U1N0pjQVZxS2NJRTFSQW5WK1c4bmxvbnNWdUQ2Wk85Y1N0eHpRUFpMMmZwNTdFM2NKeWlFNDM2QT0&utm_campaign=client_scan_share&app=aweme&utm_medium=ios&tt_from=scan_share&iid=&utm_source=scan_share。
- 链接中object_id参数的值即为本接口传入的 encrypted_data 参数 I0ZwZEZpb2U1N0pjQVZxS2NJRTFSQW5WK1c4bmxvbnNWdUQ2Wk85Y1N0eHpRUFpMMmZwNTdFM2NKeWlFNDM2QT0
请仅感知链接中的 object_id 参数。其他的参数、域名、路径等信息请不要感知。以后都有优化和调整的可能。
- 定期清理过期券,在清理前可以获取到已经过期的券,用此券核销会报错。
- 该接口只返回未使用状态的券信息。
- 该接口不返回明文券码,只返回加密券码
基本信息
名称 | 描述 |
---|---|
HTTP URL | https://open.douyin.com/goodlife/v1/fulfilment/certificate/prepare/ |
HTTP Method | GET |
Scope | life.capacity.fulfilment |
权限要求 |
|
请求参数
请求头
access-token必填String
示例:clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
固定值"application/json"
Rpc-Transit-Life-AccountString
来客商户根账户ID
Query
account_idString
核销商户根账户ID(云连锁/共管场景下,挂靠商户必传,其余场景可不传)
codeString
券码明文
常见于使用用户提供的券码手动输入商家后台进行验券的场景
encrypted_data和code二选一必传,两个都不传会报错
encrypted_dataString
从二维码解析出来的标识
(传参前需要先进行URL编码,注意不要有空格)
encrypted_data和code二选一必传,两个都不传会报错
poi_idString
操作核销的抖音门店id(必传)
请求示例
curl --location --request GET 'https://open.douyin.com/goodlife/v1/fulfilment/certificate/prepare/?code=N537Ubc4XT&poi_id=ROLUhTcxyP&account_id=V9rBnrltg4&encrypted_data=xkltalsFGM' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
data必填Struct
展开子属性
extra必填Struct
扩展信息
展开子属性
响应示例
正常响应示例异常响应示例
{ "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "2025050821324153991CC9FB03633B2615", "now": 1746711169 }, "data": { "certificates": [ { "encrypted_code": "Xu6hkPHKGx", "code": "WnXJoZfObE", "not_available_poi_list": [ "3pkrrXYSAA" ], "additional_map": { "1": "M7hxjEBYxy" }, "expire_time": 7818377091128993000, "sku": { "suplier_product_out_id": "HqmjOD7EuG", "account_id": "SIpnwKzwJ0", "voucher_type": 1, "product_out_id": "EZiIJQMnif", "product_id": "piiZAUT7rm", "sku_id": "ELGHTJdpcD", "sold_start_time": 7010127146430793000, "title": "Wl9MqZMITh", "market_price": 6552444782504228000, "sku_out_id": "cICzPLkZrY", "groupon_type": 1, "third_sku_id": "lsGiq1y7pE" }, "time_card": { "times_count": 7341077072983682000, "times_used": 2991667154573062000, "serial_amount_list": [ { "serial_numb": 5809853468833904000, "amount": { "original_currency": "BXJJXkbhvn", "brand_ticket_amount": 2682910706082157600, "platform_discount_amount": 3568258925543213600, "merchant_ticket_amount": 3440688488333550000, "coupon_pay_amount": 487535085856314560, "origin_list_market_amount": 8407795461310335000, "payment_discount_amount": 3370911907039427000, "pay_amount": 7431458765936756000, "original_amount": 3640989900408764400, "list_market_amount": 6712710116953308000 } } ], "time_card_type": 1 }, "verify": { "verify_id": "KfY5wAYylf", "certificate_id": "WYf9zJ9B5B", "verify_time": 5157487933393885000, "can_cancel": false, "verify_type": 1, "verifier_unique_id": "T7OelgMSDO", "poi_id": 8980543424174209000, "times_card_serial_num": 4951357801709500000 }, "reserve_info": { "order_reserve_user_info_list": [ { "credential_numb": "7Sxww4JdZS", "credential_type": 1, "name": "iyDdIj722o", "phone": "C9PvWfhN9j" } ] }, "use_time_info": { "use_time_type": 1, "time_period_list": [ { "end_time": "iXankx3Hv4", "end_time_is_next_day": false, "start_time": "rRJaFpIO0s" } ] }, "used_status_type": 1, "off_peak_discount_info": { "idle_time_limit_type": 1, "has_off_peak_discount": false, "off_peak_time_range": [ { "week_day_list": [ 1 ], "start_time": 8781522752362676000, "end_time": 6049087271449623000, "daily_time_range_list": [ { "end_time": "sjwpsItLq3", "end_time_is_next_day": false, "start_time": "47aEgFRZAT" } ] } ] }, "book_info": { "book_poi_id": "Rn3mJc6Oup", "book_product_number": 1701009918299558400, "verify_amount": 8624193666781394000 }, "verify_records": [ { "verifier_unique_id": "8gHPkSPkhd", "poi_id": 7569316118009650000, "times_card_serial_num": 894686126083235600, "verify_id": "2QmUlv9rA6", "certificate_id": "8zEWMrxPgW", "verify_time": 4010361425287985700, "can_cancel": false, "verify_type": 1 } ], "amount": { "original_currency": "kKGxLxW8RO", "coupon_pay_amount": 4426477721888884000, "platform_discount_amount": 1679012017422169600, "merchant_ticket_amount": 3258837662904169000, "pay_amount": 5224413996200290000, "list_market_amount": 782426958291236900, "original_amount": 1558633471030981000, "origin_list_market_amount": 5138576849699633000, "brand_ticket_amount": 5010858401800570000, "payment_discount_amount": 7195376916892908000 }, "status": 1, "period_card": { "period_type": 1 }, "start_time": 285205641620621920, "not_available_time_info": { "can_no_use_week_day": [ 5156204900449204000 ], "can_no_use_date": [ { "end_time": 6647385929711357000, "start_time": 9053916435133406000 } ], "fulfil_enable": false }, "certificate_id": 7393752223316464000 } ], "order_id": "kaWYzU8BcE", "certificates_v2": [ { "certificate_id": 1795422017702855700, "used_status_type": 1, "additional_map": { "1": "ZXHYow5h7I" }, "code": "dmDTwLAOiu", "amount": { "original_amount": 1306038461128182300, "payment_discount_amount": 4937168967099769000, "original_currency": "fETAQ54LSt", "brand_ticket_amount": 445815535149095040, "merchant_ticket_amount": 1772501566415452000, "platform_discount_amount": 1789983478126361300, "pay_amount": 2463465961171758600, "list_market_amount": 7947462760343565000, "origin_list_market_amount": 1785887856646279200, "coupon_pay_amount": 5147191584610578000 }, "period_card": { "period_type": 1 }, "not_available_time_info": { "fulfil_enable": false, "can_no_use_week_day": [ 4364855462578046500 ], "can_no_use_date": [ { "start_time": 1618628136347424000, "end_time": 424162752257573060 } ] }, "off_peak_discount_info": { "has_off_peak_discount": false, "off_peak_time_range": [ { "end_time": 5787783042788618000, "daily_time_range_list": [ { "end_time_is_next_day": false, "start_time": "Kt1e2To9Nj", "end_time": "Q9KfXU1EZC" } ], "week_day_list": [ 1 ], "start_time": 1128224585202780300 } ], "idle_time_limit_type": 1 }, "reserve_info": { "order_reserve_user_info_list": [ { "name": "uWjbHtnnLI", "phone": "6oWhbZNyR5", "credential_numb": "S954wWp2o2", "credential_type": 1 } ] }, "expire_time": 6752038673038075000, "sku": { "groupon_type": 1, "voucher_type": 1, "suplier_product_out_id": "dLYSsP5PZp", "sku_id": "BD1dW9VIbS", "market_price": 2544098714469101000, "product_out_id": "aYpaAAiOws", "sku_out_id": "jSAY3YBwRk", "product_id": "ZmyVp4gk7x", "title": "hJBKq9cUAF", "sold_start_time": 1115764813407781000, "third_sku_id": "SQJFlFW21q", "account_id": "c3FMWXwfzU" }, "verify": { "verify_type": 1, "verifier_unique_id": "JHVH9WlQ88", "poi_id": 5515807764852414000, "times_card_serial_num": 7903218144159199000, "verify_id": "B1vyjjSH9P", "certificate_id": "03zuCxywxh", "verify_time": 1373610489962209000, "can_cancel": false }, "start_time": 6244776427964630000, "book_info": { "book_product_number": 5320446890868626000, "verify_amount": 4002150937138210300, "book_poi_id": "Y8l7vnLroI" }, "status": 1, "encrypted_code": "w0zATNGHn2", "not_available_poi_list": [ "uUSFcXMvZB" ], "verify_records": [ { "verify_id": "d08stfmIyS", "certificate_id": "k3eishO7Qt", "verify_time": 4330914966081844000, "can_cancel": false, "verify_type": 1, "verifier_unique_id": "q6jcurAQU4", "poi_id": 3675355000312989000, "times_card_serial_num": 8767377811988421000 } ], "use_time_info": { "use_time_type": 1, "time_period_list": [ { "start_time": "U6zVkKIJtz", "end_time": "e3B4NhIF38", "end_time_is_next_day": false } ] }, "time_card": { "times_count": 2690869828800487400, "times_used": 1260869112568459800, "serial_amount_list": [ { "serial_numb": 6981860873016714000, "amount": { "original_currency": "OkyhZq4Lln", "merchant_ticket_amount": 4163354269460414500, "platform_discount_amount": 109946797335701330, "pay_amount": 1866574626019273500, "original_amount": 3461267426413559300, "origin_list_market_amount": 6770637667742714000, "coupon_pay_amount": 1114065531390913900, "list_market_amount": 4213502824904950300, "payment_discount_amount": 6713696108122510000, "brand_ticket_amount": 2664182030953212400 } } ], "time_card_type": 1 } } ], "verify_token": "0KUrlIZwsM", "error_code": 0, "description": "" } }
错误码
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 | 2100001 | 未知错误 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
200 | 2100004 | 系统繁忙,此时请开发者稍候再试 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
200 | 2100005 | 参数不合法 | 更换参数 |
200 | 3000002 | 以实际错误信息为准 | |
200 | 5000001 | 服务器打瞌睡了,请稍后再试。 | |
200 | 3000001 | 以实际错误信息为准 |