验券准备
接口说明
抖音团购券码的核销, 需要先调用本接口, 查询订单的券列表,选择要验的券,再调用验券接口,核销券码。
- 抖音团购券码的核销,每次都需要先调用本接口,优先查询订单的券列表,选择要验的券,拿到加密券码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/?account_id=jnl9I3bbeR&encrypted_data=99PI0EtyAZ&code=bT81mlGA6U&poi_id=EGlQDoIYx1' \ --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": "202503251657490B3F0481B256F53E2A33", "now": 1742893069 }, "data": { "order_id": "kqCuW1MqkG", "certificates_v2": [ { "use_time_info": { "time_period_list": [ { "start_time": "qirIs7FxbL", "end_time": "GDZDrIJkSw", "end_time_is_next_day": false } ], "use_time_type": 1 }, "status": 1, "not_available_time_info": { "can_no_use_week_day": [ 397246403947444350 ], "can_no_use_date": [ { "start_time": 142991364140567470, "end_time": 4785848429017777000 } ], "fulfil_enable": false }, "encrypted_code": "6b6mqcBrNz", "verify_records": [ { "poi_id": 3309577234186745300, "times_card_serial_num": 4447361112950352000, "verify_id": "hIPkIafVa5", "certificate_id": "b2CYkRuI55", "verify_time": 95020091089370930, "can_cancel": false, "verify_type": 1, "verifier_unique_id": "Xx7lAcVzwP" } ], "reserve_info": { "order_reserve_user_info_list": [ { "credential_type": 1, "name": "XZsDwAkknh", "phone": "chT9yCC4Rb", "credential_numb": "tluykFRtTC" } ] }, "book_info": { "book_poi_id": "jV9Wg7INnG", "book_product_number": 760930139884301300 }, "additional_map": { "1": "JNDNHqe5gt" }, "verify": { "verify_time": 1125664492411759000, "can_cancel": false, "verify_type": 1, "verifier_unique_id": "mYOlgB90Sq", "poi_id": 7219182698199476000, "times_card_serial_num": 6059460718182560000, "verify_id": "TDouN20WbK", "certificate_id": "0d0Mv4SgSy" }, "period_card": { "period_type": 1 }, "amount": { "payment_discount_amount": 1051366605099966600, "original_currency": "rOJgeCNn78", "pay_amount": 1956493493058576600, "list_market_amount": 5122745288707001000, "origin_list_market_amount": 8313461897106729000, "coupon_pay_amount": 1755854343682330400, "platform_discount_amount": 2045310030577730000, "merchant_ticket_amount": 2702031548423924000, "brand_ticket_amount": 4635208354848043000, "original_amount": 4522043571075593000 }, "time_card": { "times_count": 7001337293205103000, "times_used": 618104977876498200, "serial_amount_list": [ { "serial_numb": 9122632092471196000, "amount": { "original_currency": "2DFVHJPxaY", "merchant_ticket_amount": 3098506150569145300, "coupon_pay_amount": 6442052324660868000, "original_amount": 2889386314131214300, "pay_amount": 4176328263620886500, "brand_ticket_amount": 2460034490421748700, "origin_list_market_amount": 2802285846961762000, "platform_discount_amount": 3656702643105742000, "list_market_amount": 3912813806122635300, "payment_discount_amount": 7640278112155569000 } } ] }, "code": "zs7RSKAoaG", "used_status_type": 1, "certificate_id": 3132754456933244400, "expire_time": 6427430898755189000, "sku": { "account_id": "QGTfEecd0t", "voucher_type": 1, "suplier_product_out_id": "n4voFSHBHH", "sku_id": "JBG4xaqn1V", "groupon_type": 1, "product_out_id": "jv0EhcTzeG", "market_price": 3523567027252788000, "sold_start_time": 6132882712836168000, "third_sku_id": "KB35OyjqqW", "sku_out_id": "ITjjjYrtME", "title": "i3Qw4OitQJ", "product_id": "R9sufMt1zH" }, "not_available_poi_list": [ "ogjfJHGpVc" ], "off_peak_discount_info": { "has_off_peak_discount": false, "off_peak_time_range": [ { "start_time": 8131417644999759000, "end_time": 7869960205793615000, "daily_time_range_list": [ { "end_time_is_next_day": false, "start_time": "gRlNybJl7x", "end_time": "CypZVskGk4" } ], "week_day_list": [ 1 ] } ], "idle_time_limit_type": 1 }, "start_time": 5945063304346879000 } ], "verify_token": "VorfnZNp4J", "certificates": [ { "use_time_info": { "use_time_type": 1, "time_period_list": [ { "end_time": "nJ6m4a8DuK", "end_time_is_next_day": false, "start_time": "BWeZr60oQA" } ] }, "certificate_id": 1790142037065410600, "amount": { "pay_amount": 632655980203811800, "coupon_pay_amount": 8813538915734579000, "merchant_ticket_amount": 5728251368912053000, "platform_discount_amount": 1637971562888596500, "payment_discount_amount": 7953215722553948000, "list_market_amount": 725481898957809800, "origin_list_market_amount": 1379073041653719300, "original_amount": 1728666372461114600, "original_currency": "ockLuL5HFe", "brand_ticket_amount": 3445211287572817000 }, "not_available_poi_list": [ "BEAbPZQVcJ" ], "used_status_type": 1, "book_info": { "book_poi_id": "Kw8jq1YI2x", "book_product_number": 5902610864758487000 }, "encrypted_code": "xbz0OMoHod", "code": "TpuAaFFrFM", "verify": { "can_cancel": false, "verify_type": 1, "verifier_unique_id": "HR14Y6fM8Y", "poi_id": 5924988138758319000, "times_card_serial_num": 1030380899266721700, "verify_id": "9PPp9JeznH", "certificate_id": "IkBFlMhVqk", "verify_time": 2769805503466499600 }, "status": 1, "sku": { "sku_id": "X2nAsiSnUg", "third_sku_id": "0p34Rc4Rho", "sku_out_id": "xVTqlR6Nwt", "product_out_id": "PlpRDZfg9y", "market_price": 1828832056532529700, "groupon_type": 1, "voucher_type": 1, "suplier_product_out_id": "2d4rpflRpR", "account_id": "x0LJRLpsKT", "sold_start_time": 123355281956826800, "product_id": "lUKOJ1YUfR", "title": "GyisHQ6xsd" }, "verify_records": [ { "certificate_id": "upxo69LNDa", "verify_time": 2184987088431342300, "can_cancel": false, "verify_type": 1, "verifier_unique_id": "GqDzMc1guv", "poi_id": 8965399238076740000, "times_card_serial_num": 1664695811266586000, "verify_id": "l5ZDjb7Yql" } ], "period_card": { "period_type": 1 }, "not_available_time_info": { "can_no_use_week_day": [ 3519585039036431000 ], "can_no_use_date": [ { "start_time": 346718422887603600, "end_time": 7248533131165723000 } ], "fulfil_enable": false }, "additional_map": { "1": "IOBslKL2vP" }, "reserve_info": { "order_reserve_user_info_list": [ { "name": "qoJhTGXqHt", "phone": "yYr36EjDZe", "credential_numb": "9kQWhMm6TY", "credential_type": 1 } ] }, "expire_time": 7384245527828760000, "start_time": 2311055873312162000, "time_card": { "times_used": 4227584687168081400, "serial_amount_list": [ { "amount": { "pay_amount": 8232857922949178000, "original_amount": 5310252320898507000, "coupon_pay_amount": 3171499367730756000, "platform_discount_amount": 8350012498831333000, "brand_ticket_amount": 8036884888695847000, "original_currency": "2kQR4A5FR7", "list_market_amount": 3144485430156307000, "origin_list_market_amount": 4899371996718878000, "merchant_ticket_amount": 8250251963335748000, "payment_discount_amount": 6325393577766148000 }, "serial_numb": 8873537558661603000 } ], "times_count": 8415305464567992000 }, "off_peak_discount_info": { "has_off_peak_discount": false, "off_peak_time_range": [ { "daily_time_range_list": [ { "start_time": "WOUHW4MOTt", "end_time": "xno0ebIVgM", "end_time_is_next_day": false } ], "week_day_list": [ 1 ], "start_time": 6424535293360744000, "end_time": 6297207585929785000 } ], "idle_time_limit_type": 1 } } ], "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 | 以实际错误信息为准 |