验券准备
收藏接口说明
抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。
- 抖音团购券码的核销，每次都需要先调用本接口，优先查询订单的券列表，选择要验的券，拿到加密券码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 参数。其他的参数、域名、路径等信息请不要感知。以后都有优化和调整的可能。
- 定期清理过期券，在清理前可以获取到已经过期的券，用此券核销会报错。
- 该接口只返回未使用状态的券信息。
- 该接口不返回明文券码，只返回加密券码
使用限制
SLA：支持的最大QPS:200;
基本信息
| 名称 | 描述 |
|---|---|
| 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（云连锁/共管场景下，挂靠商户必传，其余场景可不传）
can_verifyEnum
服务商收银版本号
展开子属性
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/?can_verify=1&encrypted_data=r95PSWl0ya&code=t0RseLUnWn&poi_id=F08awM2pvg&account_id=FC38P2fpTg' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
data必填Struct
展开子属性
extra必填Struct
扩展信息
展开子属性
响应示例
正常响应示例异常响应示例
{ "data": { "verify_token": "HTLRdr4ZAI", "certificates": [ { "code": "jDdIe0KIQV", "additional_map": { "1": "EYMgZ9VD4A" }, "pay_bill_info": { "bill_amount": 1571660046166494500, "bill_total_amount": 5323444522306048000 }, "use_time_info": { "use_time_type": 1, "time_period_list": [ { "end_time_is_next_day": false, "start_time": "TCa648rc9h", "end_time": "Hn4t6j32XE" } ] }, "period_card": { "period_type": 1 }, "can_verify_status": 1, "not_available_time_info": { "fulfil_enable": false, "can_no_use_week_day": [ 728997070491642400 ], "can_no_use_date": [ { "start_time": 4091003197039132000, "end_time": 8157951915898889000 } ] }, "not_available_poi_list": [ "qkx3l6Jrtq" ], "time_card": { "times_count": 2367381423127828000, "times_used": 2642443685596260400, "serial_amount_list": [ { "amount": { "origin_list_market_amount": 739691375546583700, "original_currency": "2mcIYVOUvL", "platform_discount_amount": 8833183353799759000, "coupon_pay_amount": 2029931210458758400, "brand_ticket_amount": 5332242987327686000, "merchant_ticket_amount": 4920563601029159000, "payment_discount_amount": 6936565285714687000, "list_market_amount": 352071544842072900, "pay_amount": 7888389948222047000, "original_amount": 5246115126856992000 }, "serial_numb": 6558647326207516000 } ], "time_card_type": 1 }, "used_status_type": 1, "off_peak_discount_info": { "has_off_peak_discount": false, "off_peak_time_range": [ { "week_day_list": [ 1 ], "start_time": 5744504891738441000, "end_time": 5411595186566817000, "daily_time_range_list": [ { "start_time": "MhH6dW54ou", "end_time": "rXsi6uFnZG", "end_time_is_next_day": false } ] } ], "idle_time_limit_type": 1 }, "dynamic_code_info": { "code_expire_time": "sNEyPq3Uvx" }, "verify": { "verifier_unique_id": "gWm4urxsmb", "verify_id": "JmqRJ3sFX6", "times_card_serial_num": 5467643933293168000, "verify_type": 1, "can_cancel": false, "certificate_id": "qZGPyaBxxs", "poi_id": 977011064683990500, "verify_time": 1694960327651729700 }, "verify_records": [ { "can_cancel": false, "times_card_serial_num": 998687551647910900, "verifier_unique_id": "jL0ZAnYeun", "poi_id": 4525844290262354400, "verify_type": 1, "verify_id": "jQPleAcwSl", "certificate_id": "wNkcHVESk2", "verify_time": 5789963810587703000 } ], "book_info": { "book_product_number": 4467492736572122000, "verify_amount": 957073538814081500, "book_poi_id": "mSOGspZNlg" }, "reserve_info": { "order_reserve_user_info_list": [ { "name": "vm8BJ5tOir", "phone": "fvwj2eDgxp", "credential_numb": "zBhRW6bIbw", "credential_type": 1 } ] }, "sku": { "market_price": 3948129293029538300, "sku_id": "uBr0CuWfWc", "groupon_type": 1, "third_sku_id": "y2UYiw7ct6", "product_out_id": "p6YG7OlVn8", "sku_out_id": "bS2orhuphi", "title": "vGp98Fn0ET", "account_id": "iCFqNtbPEr", "sold_start_time": 8215978586028259000, "product_attr": { "seGLEDTqi2": "VbZUU71Ek7" }, "voucher_type": 1, "product_id": "RpCBYXAsra", "suplier_product_out_id": "6qrtpDil1L" }, "amount": { "payment_discount_amount": 682905685544226800, "original_amount": 524944333699393800, "original_currency": "oK3q2ilXeC", "coupon_pay_amount": 126726342170055710, "list_market_amount": 3649653810593843700, "pay_amount": 5568819679312609000, "merchant_ticket_amount": 6133905489906684000, "platform_discount_amount": 5699559070925159000, "origin_list_market_amount": 6535630205322265000, "brand_ticket_amount": 7609484424590483000 }, "expire_time": 3260790359418271000, "advance_purchase_struct": { "purchase_type": 1, "time_detail": [ { "time": 4295210211481470000, "time_type": 1 } ] }, "buyer_reserve_info": { "name": "tyKzTeka3W", "credential_numb": "OEzHLY1hEs", "credential_type": 3402649249099425300 }, "start_time": 8802870810776088000, "certificate_id": 7479758842827942000, "status": 1, "benefit_card_info": { "total_amount": { "merchant_discount_amount": 297341899925195000, "platform_discount_amount": 2116141164185084700, "brand_discount_amount": 4553232282114217000, "total_amount": 726502776348858900, "pay_amount": 1178527140369139500, "payment_discount_amount": 4995795092868978000, "principal_amount": 6366093950603553000, "provider_discount_amount": 7041502089934564000, "benefit_amount": 8358406267605587000 }, "left_amount": { "platform_discount_amount": 2096893460604028000, "brand_discount_amount": 8317026964217845000, "benefit_amount": 205078109780312450, "total_amount": 929971179960027300, "merchant_discount_amount": 5154174731597608000, "pay_amount": 1698485170336723000, "payment_discount_amount": 5783903220609830000, "provider_discount_amount": 4181941342862271000, "principal_amount": 8355665432401317000 } }, "encrypted_code": "L7lScbLZQv", "deduction_info_list": [ { "source_selling_price": 3589328076585593000, "source_provider_discount_amount": 7777213403829545000, "source_brand_discount_amount": 8692237883819266000, "source_merchant_discount_amount": 1921062571984241700, "source_item_order_id": "NzrEEuW8oG", "groupon_type": 1, "is_one_time_buy": false, "source_platform_discount_amount": 690897058518922200, "source_user_pay_amount": 7822843484579801000, "source_order_id": "iV5dTKWs49", "source_payment_discount_amount": 3148765124752390000, "source_amount": 418477002948565600, "source_certificate_code": "wg0OFApbua", "voucher_type": 1, "source_sku_id": 7117033587057127000, "source_certificate_id": "I0LyHT32gJ", "source_sku_name": "wFsEnasxB2" } ] } ], "order_id": "ts9zlVVBUw", "certificates_v2": [ { "dynamic_code_info": { "code_expire_time": "eUAPrWlu4x" }, "sku": { "sku_id": "t85LlxKmWy", "suplier_product_out_id": "cydrMxS9ua", "product_attr": { "0vLakHmSX1": "YX3UvRLUuD" }, "market_price": 4924054420004184000, "third_sku_id": "TPJIpNP29w", "sku_out_id": "aBIxjNohuZ", "product_id": "7WqvvJreYw", "account_id": "7pMjCEXI0l", "sold_start_time": 4244203320850052600, "groupon_type": 1, "voucher_type": 1, "product_out_id": "s3cetaFte4", "title": "rttm6Wc1ly" }, "expire_time": 5799799761859653000, "verify": { "times_card_serial_num": 7100923331838961000, "certificate_id": "w4cOCaoDWt", "verify_time": 4885996852318813000, "verifier_unique_id": "cHlzuvFlk4", "verify_id": "WCbNTOsave", "verify_type": 1, "can_cancel": false, "poi_id": 7700058467740798000 }, "used_status_type": 1, "amount": { "original_currency": "c2eK0Vld8R", "merchant_ticket_amount": 3158337561281722400, "list_market_amount": 1609773105850342000, "origin_list_market_amount": 3673785578362287000, "brand_ticket_amount": 8842240008767908000, "payment_discount_amount": 7124280205567857000, "pay_amount": 8631626339782423000, "coupon_pay_amount": 6637263635137862000, "platform_discount_amount": 5023103724772218000, "original_amount": 1725865343391780900 }, "time_card": { "times_count": 4055078455295363600, "times_used": 97733666628483310, "serial_amount_list": [ { "serial_numb": 7231273071128841000, "amount": { "list_market_amount": 1526784977767009000, "coupon_pay_amount": 225728593217983420, "original_amount": 4330571822272775700, "original_currency": "MZIY1Ugk9U", "platform_discount_amount": 1320304941574132700, "brand_ticket_amount": 7160842179988449000, "pay_amount": 2652173766376208000, "origin_list_market_amount": 7096036811564460000, "merchant_ticket_amount": 4596989130492855000, "payment_discount_amount": 5193537834133167000 } } ], "time_card_type": 1 }, "advance_purchase_struct": { "purchase_type": 1, "time_detail": [ { "time": 1148201608331886600, "time_type": 1 } ] }, "period_card": { "period_type": 1 }, "can_verify_status": 1, "book_info": { "book_poi_id": "7e8dHyNcNu", "book_product_number": 5445308099695961000, "verify_amount": 7984082028122765000 }, "pay_bill_info": { "bill_total_amount": 5575700489555707000, "bill_amount": 1675817595609771300 }, "code": "TAitMrmCYz", "not_available_poi_list": [ "13Gf0ZPsPP" ], "start_time": 800818756525731800, "reserve_info": { "order_reserve_user_info_list": [ { "credential_type": 1, "name": "N3ZeWKrG3A", "phone": "b7eOVkUS9I", "credential_numb": "bvnhLfjzrc" } ] }, "encrypted_code": "dPAECNHLnC", "deduction_info_list": [ { "source_certificate_code": "FS3v02OlaR", "source_certificate_id": "mmQPjz8BBs", "source_provider_discount_amount": 1191994215983814000, "source_platform_discount_amount": 8971041277876235000, "source_amount": 4432930603076686000, "source_brand_discount_amount": 8340110170242995000, "source_payment_discount_amount": 7014934534101469000, "source_sku_id": 7651678652058132000, "source_item_order_id": "7tkN3V12op", "voucher_type": 1, "source_order_id": "0oHZctHSzE", "source_selling_price": 3175283848319751700, "groupon_type": 1, "is_one_time_buy": false, "source_sku_name": "pJySBgINrk", "source_merchant_discount_amount": 9164921065877497000, "source_user_pay_amount": 5090119695500938000 } ], "verify_records": [ { "certificate_id": "vA2xcVhT66", "verifier_unique_id": "QcP0Uohy2H", "verify_type": 1, "can_cancel": false, "verify_time": 8543470612501652000, "times_card_serial_num": 4772406421298513000, "verify_id": "MJ04hu5YEJ", "poi_id": 7618662961508642000 } ], "certificate_id": 2217069898468384500, "not_available_time_info": { "can_no_use_week_day": [ 430316012489938940 ], "can_no_use_date": [ { "start_time": 2848085994226548700, "end_time": 6752808919769300000 } ], "fulfil_enable": false }, "buyer_reserve_info": { "name": "WO1P3NJTCo", "credential_numb": "awbWndhUn8", "credential_type": 7392996809507555000 }, "off_peak_discount_info": { "has_off_peak_discount": false, "off_peak_time_range": [ { "start_time": 2662062130837739500, "end_time": 8652348499569101000, "daily_time_range_list": [ { "start_time": "MQKNjm9N4D", "end_time": "jBiojW1x2V", "end_time_is_next_day": false } ], "week_day_list": [ 1 ] } ], "idle_time_limit_type": 1 }, "use_time_info": { "use_time_type": 1, "time_period_list": [ { "start_time": "I5YxR3xwfj", "end_time": "zGRvCthkOP", "end_time_is_next_day": false } ] }, "benefit_card_info": { "total_amount": { "benefit_amount": 3254510133115379700, "brand_discount_amount": 522846985785081900, "payment_discount_amount": 426369536712455200, "platform_discount_amount": 3236336034233062400, "total_amount": 3527028545836100000, "pay_amount": 3813130736322584000, "provider_discount_amount": 8933255513813059000, "merchant_discount_amount": 556687027615515600, "principal_amount": 1398075713864647400 }, "left_amount": { "provider_discount_amount": 5679658619754131000, "payment_discount_amount": 2064060601275472600, "benefit_amount": 5320328267442665000, "brand_discount_amount": 3115885814312392000, "principal_amount": 3695871719061192700, "platform_discount_amount": 478369186363608100, "pay_amount": 1780440540527693000, "merchant_discount_amount": 8744424324449646000, "total_amount": 3114318453287342000 } }, "additional_map": { "1": "hHMu5o52KO" }, "status": 1 } ], "error_code": 0, "description": "" }, "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "202601081745158A727A492463D550ADCF", "now": 1767865517 } }
切换单列布局错误码
| 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 | 3000001 | 请求过于频繁，请稍后再试 | 重试解决 |
| 200 | 3000001 | 以实际错误信息为准 | |
| 200 | 5000001 | 服务器打瞌睡了，请稍后再试。 | |
| 200 | 3000002 | 以实际错误信息为准 | |
| 200 | 5000009 | 实名信息查询失败，请重试查询 |
