验券准备
收藏接口说明
团购抖音发码的核销需要先调用本接口（三方系统发码无需调用此接口）, 查询订单的券列表，选择要验的券，再调用验券接口，核销券码。
- 抖音团购券码的核销，每次都需要先调用本接口，优先查询订单的券列表，选择要验的券，拿到加密券码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=9ZQ9eg0Pv5&can_verify=1&encrypted_data=mWqeN7wmmH&code=aJBMk0F1YQ&poi_id=qi70pSBkbU' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
data必填Struct
展开子属性
extra必填Struct
扩展信息
展开子属性
响应示例
正常响应示例异常响应示例
{ "data": { "certificates_v2": [ { "benefit_card_info": { "total_amount": { "provider_discount_amount": 9219277872248370000, "benefit_amount": 1284417418165562600, "payment_discount_amount": 57259259162769560, "total_amount": 1607006370008660000, "platform_discount_amount": 3430558871855959000, "principal_amount": 364266599039016700, "brand_discount_amount": 5509763087890052000, "pay_amount": 5915222060524550000, "merchant_discount_amount": 4929858992366053000 }, "left_amount": { "brand_discount_amount": 4496202522210148400, "pay_amount": 999140766556793500, "provider_discount_amount": 4586546267982243000, "benefit_amount": 1047317742708299800, "total_amount": 2229817765087023400, "principal_amount": 7777095886537422000, "payment_discount_amount": 4338590426384721400, "platform_discount_amount": 2441847672298772500, "merchant_discount_amount": 5628595561925954000 } }, "can_verify_status": 1, "certificate_id": 4175416747751639000, "code": "SVOfaKskxP", "buyer_reserve_info": { "credential_numb": "MBvaSlqNh4", "credential_type": 5729478924831043000, "name": "SagdZr4hOo", "enc_credential_numb": "qrXhM2Oih6", "enc_name": "a8h95H8sIv" }, "deduction_info_list": [ { "source_certificate_code": "XkPQ4hZy82", "source_user_pay_amount": 8625888792732993000, "is_one_time_buy": false, "source_selling_price": 4698489998023599000, "source_order_id": "cgqx1iQUKN", "source_sku_id": 2218340628968656100, "source_brand_discount_amount": 1706480975291744000, "source_amount": 8885192230210800000, "source_payment_discount_amount": 4644888679802708000, "source_certificate_id": "6Dy3jIbgFh", "source_item_order_id": "gpEnC72y5o", "groupon_type": 1, "source_provider_discount_amount": 6205810851577287000, "voucher_type": 1, "source_platform_discount_amount": 3355457245828736000, "order_source": 1, "source_sku_name": "Mu9tUCOn24", "source_merchant_discount_amount": 2400841304962662000 } ], "used_status_type": 1, "period_card": { "period_type": 1 }, "expire_time": 8802388798784113000, "off_peak_discount_info": { "idle_time_limit_type": 1, "has_off_peak_discount": false, "off_peak_time_range": [ { "week_day_list": [ 1 ], "start_time": 3881134586719543300, "end_time": 4037450720219182000, "daily_time_range_list": [ { "end_time": "zw4MInO9kS", "end_time_is_next_day": false, "start_time": "brBbZ2R0cM" } ] } ] }, "sku": { "sku_out_id": "XsETaJJFtZ", "product_attr": { "S92ATDoVUu": "HMhTBrvsDx" }, "sold_start_time": 3015034689994982000, "voucher_type": 1, "sku_id": "W6LQdbnd9G", "product_id": "b23adpe6aV", "suplier_product_out_id": "SrwJAxi4ck", "title": "LoX4uhI3Yg", "account_id": "XfWhsaAuif", "groupon_type": 1, "product_out_id": "0FSJ0yfoe9", "market_price": 1418574038970249500, "third_sku_id": "JNw1T9ZGxO" }, "dynamic_code_info": { "code_expire_time": "sjpgTPsBwc" }, "verify": { "poi_id": 1214730383761795300, "extra": { "open_order_id": "Jax6OOjFSZ" }, "verify_id": "c5qvPKVNtT", "can_cancel": false, "verify_type": 1, "certificate_id": "Pd1mQLFwfH", "verify_time": 1694938519902180400, "verifier_unique_id": "YqQ4ZiCuuH", "times_card_serial_num": 6471617160281242000, "benefit_amount": { "brand_discount_amount": 7495305479821489000, "benefit_amount": 1865545889373246000, "payment_discount_amount": 7125720599588446000, "total_amount": 788261185798151200, "pay_amount": 3185265795972346000, "merchant_discount_amount": 3413119422913132000, "provider_discount_amount": 6457548908377321000, "principal_amount": 7885133905170195000, "platform_discount_amount": 7219679703207788000 } }, "additional_map": { "1": "rnvcNWJIUI" }, "reserve_info": { "order_reserve_user_info_list": [ { "credential_type": 1, "name": "TIpDzLOxVl", "phone": "FCBm9qX9l4", "credential_numb": "y5XTvG1F91" } ] }, "book_info": { "verify_amount": 1289651061276017000, "book_poi_id": "tyt0pBQkbv", "book_product_number": 1768653809025713200 }, "verify_records": [ { "verify_type": 1, "certificate_id": "tj687gmV60", "times_card_serial_num": 8000057574116987000, "verify_time": 3954890871078436400, "verifier_unique_id": "fsDxEQrQbf", "poi_id": 5716188406979565000, "benefit_amount": { "benefit_amount": 6182846956547354000, "provider_discount_amount": 2149599391828911000, "platform_discount_amount": 8304827702927113000, "brand_discount_amount": 3818903547639711000, "merchant_discount_amount": 6321603218659351000, "principal_amount": 5828048113654320000, "total_amount": 1502248934496177200, "pay_amount": 835699355628580600, "payment_discount_amount": 5905891140068538000 }, "can_cancel": false, "extra": { "open_order_id": "kkXvMDGKFl" }, "verify_id": "6x6J6BtxEA" } ], "amount": { "origin_list_market_amount": 1315135124570561500, "original_amount": 992062131265362800, "platform_discount_amount": 9095530343582372000, "original_currency": "2fnYLomezD", "pay_amount": 6121468629420127000, "brand_ticket_amount": 6968831131502493000, "payment_discount_amount": 8336649402917470000, "list_market_amount": 457393173360920000, "merchant_ticket_amount": 8795105668721513000, "coupon_pay_amount": 4491493869178947600 }, "not_available_poi_list": [ "OFYp1usyF3" ], "use_time_info": { "use_time_type": 1, "time_period_list": [ { "end_time": "Pngmv6QfnP", "end_time_is_next_day": false, "start_time": "n8Bz0hwFez" } ] }, "pay_bill_info": { "bill_total_amount": 4907598902289802000, "bill_amount": 1186573642586856400, "order_source": 1 }, "not_available_time_info": { "fulfil_enable": false, "can_no_use_week_day": [ 4159812968478934000 ], "can_no_use_date": [ { "end_time": 991619150805916700, "start_time": 5548642808031465000 } ] }, "encrypted_code": "ZzSuAUCLkO", "status": 1, "start_time": 5750690577219421000, "time_card": { "times_count": 5567701707369733000, "times_used": 9216019953663283000, "serial_amount_list": [ { "amount": { "platform_discount_amount": 3740645526778491400, "original_currency": "cyVTQ1bLIN", "original_amount": 2202099078151546400, "coupon_pay_amount": 4881014050341261000, "list_market_amount": 5957107515962767000, "brand_ticket_amount": 8988800784715691000, "merchant_ticket_amount": 165852658963700740, "payment_discount_amount": 7195876286569854000, "origin_list_market_amount": 2257460462227629300, "pay_amount": 2508164979056397300 }, "serial_numb": 6165952291362689000 } ], "time_card_type": 1 }, "cancel_verify_records": [ { "certificate_id": "POrWTDmK85", "verify_time": 4671074941882834000, "verifier_unique_id": "rMYJdvLXCA", "extra": { "open_order_id": "HZfVWIV0A3" }, "verify_id": "KtegVM2fKl", "benefit_amount": { "brand_discount_amount": 2828517548860233700, "pay_amount": 5239050574926895000, "merchant_discount_amount": 31618129807842836, "total_amount": 4345421830671411000, "provider_discount_amount": 4129904944904348700, "platform_discount_amount": 822785807802693900, "payment_discount_amount": 2564094841902224000, "principal_amount": 6840633843781994000, "benefit_amount": 3417814453668905000 }, "can_cancel": false, "poi_id": 5825347159962624000, "times_card_serial_num": 9150847595222994000, "verify_type": 1 } ], "advance_purchase_struct": { "time_detail": [ { "time": 8899082438613935000, "time_type": 1 } ], "purchase_type": 1 } } ], "verify_token": "omUmq74iJ8", "certificates": [ { "status": 1, "deduction_info_list": [ { "source_user_pay_amount": 967133874601857900, "groupon_type": 1, "is_one_time_buy": false, "source_sku_name": "GyAeHX8C9U", "order_source": 1, "source_provider_discount_amount": 403432458023916100, "voucher_type": 1, "source_certificate_code": "60MeS1majh", "source_payment_discount_amount": 5048775391744303000, "source_sku_id": 6342589404629254000, "source_amount": 7247760686563015000, "source_platform_discount_amount": 5957914639199647000, "source_selling_price": 3520983531275916000, "source_brand_discount_amount": 6248446556277220000, "source_item_order_id": "DKpJCIWSup", "source_certificate_id": "8yGkJ41dgY", "source_order_id": "2hosZsgPVT", "source_merchant_discount_amount": 4370645241747912700 } ], "reserve_info": { "order_reserve_user_info_list": [ { "credential_numb": "VLmeKuTdNb", "credential_type": 1, "name": "ACbGc7E7bJ", "phone": "kQghtrDcS8" } ] }, "start_time": 1235294839583222300, "time_card": { "time_card_type": 1, "times_count": 6606166604066887000, "times_used": 5881930047642137000, "serial_amount_list": [ { "serial_numb": 1951859927954471000, "amount": { "merchant_ticket_amount": 3575232721844441000, "original_amount": 6769065933534681000, "payment_discount_amount": 4644651375029648000, "list_market_amount": 9094787619991705000, "pay_amount": 5361927308152189000, "original_currency": "1cwjDvWNyx", "brand_ticket_amount": 677968849192293900, "coupon_pay_amount": 193747611930951460, "platform_discount_amount": 7805603911024093000, "origin_list_market_amount": 6867706143202502000 } } ] }, "verify_records": [ { "certificate_id": "upT5DvVraf", "poi_id": 247841363236256480, "verify_type": 1, "verifier_unique_id": "BnBpgkVvSd", "extra": { "open_order_id": "mojmH0HBiB" }, "benefit_amount": { "payment_discount_amount": 4508940323793089500, "pay_amount": 7013205236798705000, "principal_amount": 9015037899102056000, "platform_discount_amount": 7506021186453574000, "merchant_discount_amount": 6812532207829166000, "brand_discount_amount": 9040053362735239000, "provider_discount_amount": 7078216231930348000, "total_amount": 5778737409928092000, "benefit_amount": 173125164366883900 }, "times_card_serial_num": 7528595771127405000, "verify_id": "uryCJKI0Gd", "verify_time": 2516890231471040500, "can_cancel": false } ], "period_card": { "period_type": 1 }, "cancel_verify_records": [ { "verify_type": 1, "verify_id": "VGDkJtdz43", "extra": { "open_order_id": "4JRgvYaRl4" }, "times_card_serial_num": 8523351500561029000, "benefit_amount": { "brand_discount_amount": 7402582410462238000, "principal_amount": 5571928406770359000, "merchant_discount_amount": 7881216174163252000, "benefit_amount": 3249041982383280000, "platform_discount_amount": 1739670987665455900, "total_amount": 8759959897766223000, "pay_amount": 6123688563384842000, "payment_discount_amount": 4640893771338382000, "provider_discount_amount": 3494712466259088400 }, "verify_time": 5014998971327094000, "can_cancel": false, "certificate_id": "zBEv8AAzL3", "verifier_unique_id": "hWRX9vdFFq", "poi_id": 4039738174530119000 } ], "additional_map": { "1": "0RyipWOtBM" }, "amount": { "pay_amount": 2753651310837727000, "list_market_amount": 1587571339339729200, "origin_list_market_amount": 5986943856388611000, "coupon_pay_amount": 7738917902788327000, "original_currency": "RozUnLAuyH", "merchant_ticket_amount": 7369054602155226000, "original_amount": 9030770614586123000, "platform_discount_amount": 8696138562514732000, "payment_discount_amount": 5050331834905471000, "brand_ticket_amount": 4824073364847019000 }, "encrypted_code": "xCoU2GG5ny", "pay_bill_info": { "bill_amount": 235441832229677150, "order_source": 1, "bill_total_amount": 7607840364249712000 }, "buyer_reserve_info": { "credential_numb": "T4Fp1FfS65", "credential_type": 6319631118765916000, "name": "g06EP5ZpGQ", "enc_credential_numb": "xE6GT3DxXi", "enc_name": "V2yPFKgGnw" }, "not_available_poi_list": [ "8897Pyf5wM" ], "advance_purchase_struct": { "time_detail": [ { "time_type": 1, "time": 1560904744366908700 } ], "purchase_type": 1 }, "off_peak_discount_info": { "has_off_peak_discount": false, "off_peak_time_range": [ { "start_time": 6730096635777532000, "end_time": 4024009897141312000, "daily_time_range_list": [ { "end_time": "EdfuicokgE", "end_time_is_next_day": false, "start_time": "hhFnyQ0nJ6" } ], "week_day_list": [ 1 ] } ], "idle_time_limit_type": 1 }, "sku": { "sku_out_id": "reC5iYkGYc", "suplier_product_out_id": "5UjQYR0gWc", "account_id": "xYV6ule7UX", "sold_start_time": 8196019519012134000, "title": "ByxZu9elZ5", "third_sku_id": "x9R40E7aYh", "voucher_type": 1, "groupon_type": 1, "market_price": 6849805173808298000, "product_id": "XhqDirhfKc", "product_attr": { "R8VI1VZIW9": "FbsjQJNf9W" }, "product_out_id": "0oT2jnRgdh", "sku_id": "TnSVMEcuC4" }, "benefit_card_info": { "total_amount": { "brand_discount_amount": 1571501791860220200, "pay_amount": 1445866810097913600, "total_amount": 3976615840815661600, "platform_discount_amount": 4544883269849658000, "provider_discount_amount": 5972255344135444000, "merchant_discount_amount": 6404588571026844000, "principal_amount": 3192774196172600300, "benefit_amount": 3594642441453189000, "payment_discount_amount": 9160400194319234000 }, "left_amount": { "total_amount": 6993384894635235000, "merchant_discount_amount": 4581305244932722700, "provider_discount_amount": 8825041825552713000, "principal_amount": 2066224103744923000, "pay_amount": 312467710983304770, "brand_discount_amount": 4750453548179019000, "payment_discount_amount": 3132849602038934000, "benefit_amount": 8278179060003458000, "platform_discount_amount": 3911751329664627000 } }, "verify": { "poi_id": 3954636536266983400, "benefit_amount": { "merchant_discount_amount": 8027724744796076000, "pay_amount": 2392310683118935600, "payment_discount_amount": 3817654861554796500, "brand_discount_amount": 3236151366757708300, "platform_discount_amount": 2974069879591971000, "principal_amount": 7349454182575022000, "total_amount": 8183328085448059000, "benefit_amount": 3535657730517210600, "provider_discount_amount": 466253586450822600 }, "extra": { "open_order_id": "2aDJddXZOV" }, "certificate_id": "j9luhsthEo", "times_card_serial_num": 6402488879115133000, "verify_time": 3413788254617921500, "can_cancel": false, "verify_type": 1, "verifier_unique_id": "Pon99USJ21", "verify_id": "eepKOgl0Xy" }, "expire_time": 8065109185072164000, "certificate_id": 6733766774018255000, "used_status_type": 1, "not_available_time_info": { "can_no_use_week_day": [ 2415258630522998000 ], "can_no_use_date": [ { "start_time": 3943131980732752400, "end_time": 3304397882643672000 } ], "fulfil_enable": false }, "dynamic_code_info": { "code_expire_time": "OwYQEb9fQB" }, "code": "Ys1pMbLR3c", "use_time_info": { "use_time_type": 1, "time_period_list": [ { "start_time": "Xfw7kNBRoz", "end_time": "WMU5eERJqX", "end_time_is_next_day": false } ] }, "can_verify_status": 1, "book_info": { "book_poi_id": "6JT0XphH7m", "book_product_number": 3990317112465196500, "verify_amount": 9160676028454692000 } } ], "order_id": "UoMkbwusTc", "error_code": 0, "description": "" }, "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "20260630161350022DD8A3CCAA143A11F2", "now": 1782807230 } }
切换单列布局错误码
| 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 | 实名信息查询失败，请重试查询 |
