验券准备
收藏接口说明
团购抖音发码的核销需要先调用本接口（三方系统发码无需调用此接口）, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。
- 抖音团购券码的核销，每次都需要先调用本接口，优先查询订单的券列表，选择要验的券，拿到加密券码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 参数。其他的参数、域名、路径等信息请不要感知。以后都有优化和调整的可能。
- 定期清理过期券，在清理前可以获取到已经过期的券，用此券核销会报错。
- 该接口只返回未使用状态的券信息。
- 该接口不返回明文券码，只返回加密券码
- 若当前订单属于“送礼（转赠）”业务场景，且券正处于“转赠中”的流转状态，系统将临时锁定券码，此时该字段将返回空数组（[]）或不返回。须等待转赠流程彻底完成（目标用户成功接收且券状态恢复为待核销）后，再次调用本接口方可获取有效的券码信息。
- 验劵准备不返回全量sku信息，全量sku使用商品查询接口
- 提货券订单，一个订单多张卷只会返回一个certificate_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/?account_id=9lV02xaFzH&can_verify=1&encrypted_data=SIUK2fiFmG&code=9fz5K3sZwe&poi_id=hEOc9XBkVP' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
data必填Struct
展开子属性
extra必填Struct
扩展信息
展开子属性
响应示例
正常响应示例异常响应示例
{ "data": { "certificates": [ { "additional_map": { "1": "6L3Dm8veOF" }, "advance_purchase_struct": { "purchase_type": 1, "time_detail": [ { "time": 3346698736637330400, "time_type": 1 } ] }, "amount": { "brand_ticket_amount": 251749082250661980, "coupon_pay_amount": 599452162610915500, "list_market_amount": 9154845396483005000, "merchant_discount_detail_list": [ { "discount_amount": 4286280122706525000, "discount_id": "jTHJwhnEZn", "discount_name": "GJDSXUatc9" } ], "merchant_ticket_amount": 2395276445993185300, "origin_list_market_amount": 7237784396232741000, "original_amount": 1692705039325870600, "original_currency": "K7ngtiFubw", "pay_amount": 2897345923300301300, "payment_discount_amount": 1281054719132937500, "platform_discount_amount": 7385267051754582000 }, "benefit_card_info": { "left_amount": { "benefit_amount": 4680793999487002000, "brand_discount_amount": 7627135803371695000, "merchant_discount_amount": 8987261309684296000, "pay_amount": 8571676998175014000, "payment_discount_amount": 3544820779945938400, "platform_discount_amount": 4015211733174379500, "principal_amount": 5394804945221785000, "provider_discount_amount": 4334654531088008000, "total_amount": 4103168221474823700 }, "total_amount": { "benefit_amount": 5902826879937684000, "brand_discount_amount": 1417329155860191000, "merchant_discount_amount": 7251523842802393000, "pay_amount": 3684011896091895300, "payment_discount_amount": 6493465348669680000, "platform_discount_amount": 3090547524023234000, "principal_amount": 583327384906087600, "provider_discount_amount": 1541496794731729700, "total_amount": 6166514554349471000 } }, "book_info": { "book_poi_id": "6YHGx3CuTF", "book_product_number": 2999227399265861600, "verify_amount": 7219684123600712000 }, "buyer_reserve_info": { "credential_numb": "Mu6eK8zbyL", "credential_type": 1553757994940516400, "enc_credential_numb": "Xqgim8u9K1", "enc_name": "jryYuF0CFn", "name": "vF0QyH7hA5" }, "can_verify_status": 1, "certificate_id": 4979186569823163000, "code": "SeguXwOWQe", "deduction_info_list": [ { "groupon_type": 1, "is_one_time_buy": false, "order_source": 1, "source_amount": 7240579688763154000, "source_brand_discount_amount": 3763853701669821000, "source_certificate_code": "WlzyRN6Wte", "source_certificate_id": "WTVupye6c6", "source_item_order_id": "rmLzgnmn4H", "source_merchant_discount_amount": 2240029143183924200, "source_order_id": "TYKCf3ttds", "source_payment_discount_amount": 2893683421862929400, "source_platform_discount_amount": 5215923413187854000, "source_provider_discount_amount": 4937668461706487000, "source_selling_price": 3438134845159271000, "source_sku_id": 6959138436131276000, "source_sku_name": "aQmJh8nnpP", "source_user_pay_amount": 6995104446048950000, "voucher_type": 1 } ], "dynamic_code_info": { "code_expire_time": "IHakVfFtKl" }, "encrypted_code": "muBsvgK4bE", "expire_time": 3031116456300549600, "not_available_poi_list": [ "xGyTl81yLr" ], "not_available_time_info": { "can_no_use_date": [ { "end_time": 1219097885578364000, "start_time": 6038494619609803000 } ], "can_no_use_week_day": [ 3827376780422677000 ], "fulfil_enable": false }, "off_peak_discount_info": { "has_off_peak_discount": false, "idle_time_limit_type": 1, "off_peak_time_range": [ { "daily_time_range_list": [ { "end_time": "vT9p0A1EPT", "end_time_is_next_day": false, "start_time": "Datp3vkM6B" } ], "end_time": 7673510009539298000, "start_time": 4950123452396113000, "week_day_list": [ 1 ] } ] }, "pay_bill_info": { "bill_amount": 8318058905098967000, "bill_total_amount": 8032861922448971000, "order_source": 1 }, "period_card": { "period_type": 1 }, "reserve_info": { "order_reserve_user_info_list": [ { "credential_numb": "uxKkWuXjG8", "credential_type": 1, "name": "43jNmysLq0", "phone": "cBW0rP3mtz" } ] }, "sku": { "account_id": "xsqaq6ZDaf", "groupon_type": 1, "market_price": 5846071456429746000, "product_attr": { "sTYB6rURS2": "bUgw8zYZF4" }, "product_id": "ytuKRrhNXr", "product_out_id": "anVp3iX329", "sku_id": "BymwV6rtbv", "sku_out_id": "5xiYXGn0c5", "sold_start_time": 5893940625062217000, "suplier_product_out_id": "vTj23A2SK2", "third_sku_id": "zRHM73MTOq", "title": "Mmelgems5b", "voucher_type": 1 }, "start_time": 4960301336744373000, "status": 1, "time_card": { "serial_amount_list": [ { "amount": { "brand_ticket_amount": 5956311793249693000, "coupon_pay_amount": 2779295129611459000, "list_market_amount": 1832735719596265000, "merchant_discount_detail_list": [ { "discount_amount": 8104395015526842000, "discount_id": "T9JuFlKCsU", "discount_name": "4cb53OxL8b" } ], "merchant_ticket_amount": 3429684217314726400, "origin_list_market_amount": 2186088317581939500, "original_amount": 4984580932754671000, "original_currency": "M8NHUtEne2", "pay_amount": 120647692255439920, "payment_discount_amount": 5696760335024332000, "platform_discount_amount": 4103004077938581500 }, "serial_numb": 7270368854763818000 } ], "time_card_type": 1, "times_count": 7185291580895778000, "times_used": 6697822903936083000 }, "use_time_info": { "time_period_list": [ { "end_time": "iPF5ToMKP9", "end_time_is_next_day": false, "start_time": "7XPsBVLDpG" } ], "use_time_type": 1 }, "used_status_type": 1, "verify": { "can_cancel": false, "certificate_id": "cRMQKetnAc", "poi_id": 4753477145459995000, "times_card_serial_num": 440583884985903600, "verifier_unique_id": "NEWs9dvSG1", "verify_id": "Nu80D0Rpdb", "verify_time": 2485891408733825000, "verify_type": 1 }, "verify_records": [ { "can_cancel": false, "certificate_id": "pEPx3Y6oMr", "poi_id": 4941547138735483000, "times_card_serial_num": 1591292345987463400, "verifier_unique_id": "8ZYbDiHcAZ", "verify_id": "cad2MHMMel", "verify_time": 7823752262095609000, "verify_type": 1 } ] } ], "certificates_v2": [ { "additional_map": { "1": "zu1zCK1RbW" }, "advance_purchase_struct": { "purchase_type": 1, "time_detail": [ { "time": 7687377862876582000, "time_type": 1 } ] }, "amount": { "brand_ticket_amount": 2305436037849156000, "coupon_pay_amount": 6370783791423233000, "list_market_amount": 8421880288929095000, "merchant_discount_detail_list": [ { "discount_amount": 1722982194841164800, "discount_id": "EyeSZZJH2W", "discount_name": "WkBKF3v4zY" } ], "merchant_ticket_amount": 6257210758147164000, "origin_list_market_amount": 5035745032628057000, "original_amount": 3993537677542351400, "original_currency": "D4QDiTioaB", "pay_amount": 3554442129739303000, "payment_discount_amount": 5353376809071881000, "platform_discount_amount": 1213685148267681500 }, "benefit_card_info": { "left_amount": { "benefit_amount": 8020525052821710000, "brand_discount_amount": 3162223821439323000, "merchant_discount_amount": 5358073073155810000, "pay_amount": 2616865248990450700, "payment_discount_amount": 1461988222166096400, "platform_discount_amount": 3764062768248372700, "principal_amount": 8533728710038600000, "provider_discount_amount": 8111120936062641000, "total_amount": 1289403360051646700 }, "total_amount": { "benefit_amount": 234810121147769950, "brand_discount_amount": 1801059103700058600, "merchant_discount_amount": 7700529704205605000, "pay_amount": 6301755878685083000, "payment_discount_amount": 5305036913179419000, "platform_discount_amount": 6217723846110398000, "principal_amount": 1765815342692393000, "provider_discount_amount": 5431331382406544000, "total_amount": 9040593304977697000 } }, "book_info": { "book_poi_id": "HXyYNqoFZ0", "book_product_number": 4936367701908856000, "verify_amount": 4082885834670484500 }, "buyer_reserve_info": { "credential_numb": "KILWYlfxHa", "credential_type": 272160063495958100, "enc_credential_numb": "QOaCJNE9CC", "enc_name": "brp3Cxnfxu", "name": "fGgKBhl1Gh" }, "can_verify_status": 1, "certificate_id": 3839014640118161000, "code": "zdeFj0jzuB", "deduction_info_list": [ { "groupon_type": 1, "is_one_time_buy": false, "order_source": 1, "source_amount": 7082405357091350000, "source_brand_discount_amount": 3324324052670374000, "source_certificate_code": "pgPOlHCGZw", "source_certificate_id": "562wVCqHrW", "source_item_order_id": "F6fqvPCiGk", "source_merchant_discount_amount": 4519246953625142300, "source_order_id": "QHsKb64EMc", "source_payment_discount_amount": 6076768814820869000, "source_platform_discount_amount": 8493020414794663000, "source_provider_discount_amount": 4636123032490952000, "source_selling_price": 8020563715017690000, "source_sku_id": 5389155254890112000, "source_sku_name": "wRlNuMTnJ6", "source_user_pay_amount": 2883316657511104000, "voucher_type": 1 } ], "dynamic_code_info": { "code_expire_time": "IEDSWXmxUb" }, "encrypted_code": "frz60cqyuo", "expire_time": 9179366815738279000, "not_available_poi_list": [ "CQBC8GnghO" ], "not_available_time_info": { "can_no_use_date": [ { "end_time": 6134268184577915000, "start_time": 3837144276450553000 } ], "can_no_use_week_day": [ 8578853079787801000 ], "fulfil_enable": false }, "off_peak_discount_info": { "has_off_peak_discount": false, "idle_time_limit_type": 1, "off_peak_time_range": [ { "daily_time_range_list": [ { "end_time": "wH9MwqpBBX", "end_time_is_next_day": false, "start_time": "VV1bA7FIB1" } ], "end_time": 4906740851227439000, "start_time": 5523544271641498000, "week_day_list": [ 1 ] } ] }, "pay_bill_info": { "bill_amount": 3513187206966717000, "bill_total_amount": 7653225287947781000, "order_source": 1 }, "period_card": { "period_type": 1 }, "reserve_info": { "order_reserve_user_info_list": [ { "credential_numb": "DXGLYagGzQ", "credential_type": 1, "name": "KLndtELEuD", "phone": "aOXOYHGKQ4" } ] }, "sku": { "account_id": "FEO2oZwZU7", "groupon_type": 1, "market_price": 8344726194220466000, "product_attr": { "D5VcHACKbE": "BTySoCAAIG" }, "product_id": "Gza2h04BRV", "product_out_id": "1UvgVqBaWu", "sku_id": "0QGderU3Mj", "sku_out_id": "kLNcn1Osvg", "sold_start_time": 8545336326371355000, "suplier_product_out_id": "BwzH42yFus", "third_sku_id": "XG19VNux4M", "title": "ovCS0r5BiL", "voucher_type": 1 }, "start_time": 3834293539960263700, "status": 1, "time_card": { "serial_amount_list": [ { "amount": { "brand_ticket_amount": 397226336933252900, "coupon_pay_amount": 1168548519509154800, "list_market_amount": 3848954971536913400, "merchant_discount_detail_list": [ { "discount_amount": 6556706619318337000, "discount_id": "urRtvYDFQU", "discount_name": "jahyCaaUVw" } ], "merchant_ticket_amount": 1665186771707164000, "origin_list_market_amount": 5881123646534274000, "original_amount": 1209391714136788200, "original_currency": "vvsxaSYxwo", "pay_amount": 2280720868494154000, "payment_discount_amount": 4992013433413646000, "platform_discount_amount": 4701601315359097000 }, "serial_numb": 699186228333007000 } ], "time_card_type": 1, "times_count": 3248877680228589600, "times_used": 8671855328507860000 }, "use_time_info": { "time_period_list": [ { "end_time": "kvAKfMvivw", "end_time_is_next_day": false, "start_time": "wvxN3Ucsrv" } ], "use_time_type": 1 }, "used_status_type": 1, "verify": { "can_cancel": false, "certificate_id": "rzXMm0gaG9", "poi_id": 2274456866999774700, "times_card_serial_num": 8776477493355673000, "verifier_unique_id": "YQtmvFdLAm", "verify_id": "ZM2mEwKhNn", "verify_time": 8078455864032859000, "verify_type": 1 }, "verify_records": [ { "can_cancel": false, "certificate_id": "Dmv06vI4bV", "poi_id": 6832232461936501000, "times_card_serial_num": 3688515647186827300, "verifier_unique_id": "fwLqXSPEYf", "verify_id": "ToarbOc63W", "verify_time": 9166725335430795000, "verify_type": 1 } ] } ], "order_id": "Dvyhq9Tk4W", "verify_token": "SPKUw5qRMz" }, "extra": { "description": "GhEW75iNhe", "error_code": 2689790995294126600, "logid": "2mvZ4416QU", "now": 1466531681409092900, "sub_description": "MxLR9vrhNc", "sub_error_code": 2470487318893917700 } }
切换单列布局错误码
| 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 | 5000009 | 实名信息查询失败，请重试查询 | |
| 200 | 3000002 | 以实际错误信息为准 | |
| 200 | 5000001 | 服务器打瞌睡了，请稍后再试。 | |
| 200 | 3000001 | 以实际错误信息为准 | |
| 200 | 3000001 | 请求过于频繁，请稍后再试 | 重试解决 |
