验券准备
接口说明
团购抖音发码的核销需要先调用本接口(三方系统发码无需调用此接口), 查询订单的券列表,选择要验的券,再调用验券接口,核销券码。
- 抖音团购券码的核销,每次都需要先调用本接口,优先查询订单的券列表,选择要验的券,拿到加密券码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/?can_verify=1&encrypted_data=I9XbZ61tN4&code=TF3ePdBryk&poi_id=z4CyC58xBB&account_id=tU7o1ChzM6' \ --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": "20261104113843B734E1778AF49192776B", "now": 1793763524 }, "data": { "certificates": [ { "status": 1, "buyer_reserve_info": { "credential_numb": "jcgXdHQ8vK", "credential_type": 3806446153602362400, "name": "rqTMswnEfl", "enc_credential_numb": "c8phVd2s0C", "enc_name": "IP2DqT8as7" }, "period_card": { "period_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": 421805918349085060, "end_time": 6762343387411283000, "daily_time_range_list": [ { "end_time_is_next_day": false, "start_time": "DIGEU3rtzr", "end_time": "wtd1UVsH5W" } ] } ], "idle_time_limit_type": 1 }, "certificate_id": 3272978642982016500, "deduction_info_list": [ { "source_payment_discount_amount": 5037350093281217000, "source_sku_name": "SLdO9Q33v2", "source_sku_id": 5937593405461419000, "source_merchant_discount_amount": 4580653118799190500, "source_provider_discount_amount": 6303537602279197000, "source_certificate_id": "wG1JM15TFT", "source_brand_discount_amount": 1122224555859210500, "voucher_type": 1, "source_certificate_code": "WmcLPSizZb", "source_item_order_id": "6mUdt59Y3I", "order_source": 1, "source_order_id": "AyHZWvPNIT", "is_one_time_buy": false, "source_platform_discount_amount": 317177011153294660, "source_selling_price": 3691344685664764400, "groupon_type": 1, "source_user_pay_amount": 3293755800254854700, "source_amount": 4408916608474731500 } ], "use_time_info": { "use_time_type": 1, "time_period_list": [ { "start_time": "2EpeQ4U6t5", "end_time": "eTRelAPAt0", "end_time_is_next_day": false } ] }, "not_available_poi_list": [ "QisFlft71n" ], "not_available_time_info": { "fulfil_enable": false, "can_no_use_week_day": [ 5710883361548604000 ], "can_no_use_date": [ { "start_time": 747731674896103300, "end_time": 1258151008619668000 } ] }, "verify_records": [ { "verify_type": 1, "times_card_serial_num": 4620250076619061000, "certificate_id": "wD87IgCqV0", "poi_id": 8870086619667952000, "verify_time": 853288911388281000, "extra": { "open_order_id": "lRloqJx8r8" }, "benefit_amount": { "benefit_amount": 9146636878053157000, "brand_discount_amount": 5802334237758557000, "platform_discount_amount": 3356928999631822300, "total_amount": 2998916931883578400, "principal_amount": 8212231462304613000, "pay_amount": 9221595760896148000, "payment_discount_amount": 3089379858766215700, "merchant_discount_amount": 5524895266730545000, "provider_discount_amount": 6168019226166654000 }, "can_cancel": false, "verify_id": "5THoSCm8nC", "verifier_unique_id": "SXKpq0uixE" } ], "sku": { "sold_start_time": 1229215957582659800, "product_id": "zUL41WAU02", "voucher_type": 1, "account_id": "tu1D2wfTSn", "sku_out_id": "pVpEclsLrx", "market_price": 8091018696788772000, "sku_id": "QFgeCKZWTi", "groupon_type": 1, "product_out_id": "AbsrFx7hOd", "title": "BV225v1yJr", "product_attr": { "FvfWbm9MQT": "jHcHH3AF8K" }, "third_sku_id": "TuaMFSoQqd", "suplier_product_out_id": "yAvxqkQWrG" }, "code": "k1ijZ867UY", "dynamic_code_info": { "code_expire_time": "yBoaCQER0x" }, "encrypted_code": "EXDmAp94Hp", "time_card": { "times_used": 6313079827580345000, "serial_amount_list": [ { "serial_numb": 5664429157032914000, "amount": { "payment_discount_amount": 1258079811058110000, "coupon_pay_amount": 733032410574447100, "origin_list_market_amount": 5525546160962285000, "list_market_amount": 7750737315898841000, "original_currency": "Ws4LIsNaYQ", "merchant_ticket_amount": 3819199563741886500, "platform_discount_amount": 8651261910828365000, "pay_amount": 8367802528817878000, "brand_ticket_amount": 3119939923525807600, "merchant_discount_detail_list": [ { "discount_id": "FDyTWFOpD7", "discount_name": "WJICkQBM18", "discount_amount": 3169916577620655000 } ], "original_amount": 7811209760243829000 } } ], "time_card_type": 1, "times_count": 6829375680566171000 }, "amount": { "original_amount": 759233626300240600, "list_market_amount": 208563198894053220, "brand_ticket_amount": 1863525418789091600, "original_currency": "LErQokZn37", "origin_list_market_amount": 715542100579537400, "pay_amount": 2133009137906932000, "payment_discount_amount": 3961079568238796300, "coupon_pay_amount": 7178137834733575000, "platform_discount_amount": 3701119070138939400, "merchant_ticket_amount": 527477162657904600, "merchant_discount_detail_list": [ { "discount_id": "dR5onQcsYt", "discount_name": "OviLgPTs9c", "discount_amount": 2257672599214603000 } ] }, "book_info": { "verify_amount": 6639454790631962000, "book_poi_id": "SydOBcnlqT", "book_product_number": 8965823798747971000 }, "advance_purchase_struct": { "purchase_type": 1, "time_detail": [ { "time_type": 1, "time": 8900116255677229000 } ] }, "additional_map": { "1": "9IDf3biKkA" }, "benefit_card_info": { "total_amount": { "benefit_amount": 6131801464776723000, "platform_discount_amount": 8452502201267043000, "pay_amount": 8078374472096131000, "principal_amount": 6375068919983481000, "merchant_discount_amount": 3845862545107155500, "payment_discount_amount": 7434228979756828000, "provider_discount_amount": 1001594235886369000, "total_amount": 8499844935397168000, "brand_discount_amount": 7687286443119511000 }, "left_amount": { "provider_discount_amount": 6434235477197776000, "brand_discount_amount": 8436792713613257000, "total_amount": 3710303590435273000, "platform_discount_amount": 6438228121256775000, "principal_amount": 4903670877965574000, "benefit_amount": 4421351166685309000, "payment_discount_amount": 3939883746550792700, "pay_amount": 7254801775393186000, "merchant_discount_amount": 7565561511261086000 } }, "cancel_verify_records": [ { "verify_time": 8929212132403154000, "verify_type": 1, "verifier_unique_id": "og9GVyTmJ7", "extra": { "open_order_id": "utb5WLuZIH" }, "poi_id": 4612055465302095000, "benefit_amount": { "payment_discount_amount": 5938718048992241000, "pay_amount": 1867839490140370000, "brand_discount_amount": 6787866857564107000, "principal_amount": 6184165798726183000, "provider_discount_amount": 7634827985360136000, "benefit_amount": 6158951734172203000, "merchant_discount_amount": 6743982203705600000, "platform_discount_amount": 436625683057061570, "total_amount": 2174909739553662700 }, "can_cancel": false, "certificate_id": "3w6eUUTXAZ", "verify_id": "Vq6iTS3igm", "times_card_serial_num": 8953052348469643000 } ], "start_time": 2119559584292179500, "can_verify_status": 1, "reserve_info": { "order_reserve_user_info_list": [ { "phone": "htgpF6h4ra", "credential_numb": "4fZwmFl6G3", "credential_type": 1, "enc_name": "f8nnt1bOpe", "enc_phone": "85thAn8JNg", "enc_credential_numb": "MZfLVZ1PYb", "name": "lHu8vulVxb" } ] }, "expire_time": 5280612643311658000, "verify": { "verifier_unique_id": "Hk9bWHK5AE", "poi_id": 7773007748024822000, "times_card_serial_num": 7843618628116344000, "certificate_id": "0tsygZyYiw", "verify_id": "d5YXnTIhLI", "verify_time": 5530700725799761000, "extra": { "open_order_id": "rEKgmqAQAr" }, "can_cancel": false, "verify_type": 1, "benefit_amount": { "payment_discount_amount": 1733062911566181000, "brand_discount_amount": 6139649391914598000, "principal_amount": 265975283669478270, "provider_discount_amount": 7754744369905555000, "total_amount": 8077515829566384000, "benefit_amount": 1439033022905625900, "merchant_discount_amount": 6749756213482186000, "platform_discount_amount": 1865815938695107300, "pay_amount": 5607378826357697000 } }, "pay_bill_info": { "order_source": 1, "bill_total_amount": 6012357579667661000, "bill_amount": 5183557564772561000 } } ], "order_id": "eJwQtBmfCq", "certificates_v2": [ { "additional_map": { "1": "vePgP9bKKt" }, "not_available_time_info": { "fulfil_enable": false, "can_no_use_week_day": [ 8788200709314959000 ], "can_no_use_date": [ { "start_time": 3575510519832681000, "end_time": 8495242263121794000 } ] }, "period_card": { "period_type": 1 }, "pay_bill_info": { "order_source": 1, "bill_total_amount": 8088476760632494000, "bill_amount": 8298840143944326000 }, "verify_records": [ { "verifier_unique_id": "KNmMzS8yxs", "verify_type": 1, "verify_time": 3691895297199231500, "extra": { "open_order_id": "aGw6sbU2PP" }, "verify_id": "RON52Lriru", "certificate_id": "rv2csDcKpy", "can_cancel": false, "poi_id": 3922316696561657000, "times_card_serial_num": 6789489123246883000, "benefit_amount": { "platform_discount_amount": 7371739789814310000, "provider_discount_amount": 2123167190962241300, "payment_discount_amount": 2664411542169590000, "pay_amount": 538609244481959800, "benefit_amount": 6592171658885386000, "merchant_discount_amount": 6879740185414705000, "total_amount": 4283391940235821000, "principal_amount": 956235400963204600, "brand_discount_amount": 4442740684545934300 } } ], "code": "wR1UQc0Im6", "used_status_type": 1, "reserve_info": { "order_reserve_user_info_list": [ { "enc_name": "HkYzT30eLV", "enc_phone": "GLYNg1Uzvk", "enc_credential_numb": "5miStsaWTm", "name": "ZK7aIt1s8N", "phone": "u1G8ZUSwu0", "credential_numb": "7GykdpugZS", "credential_type": 1 } ] }, "sku": { "suplier_product_out_id": "zy2KEqgAUn", "sku_id": "ovmykvH3no", "voucher_type": 1, "title": "zyghQBlrje", "product_id": "GgKcPCqLUe", "third_sku_id": "UQu3Sw46wE", "groupon_type": 1, "product_attr": { "Sc5QpTv0nM": "U7c40HVcUV" }, "account_id": "Z7xoylA04u", "sku_out_id": "rdI9tveHge", "market_price": 7828561808036679000, "sold_start_time": 5629028709814056000, "product_out_id": "jkieJ42e1J" }, "book_info": { "verify_amount": 5742418685847525000, "book_poi_id": "Q0OyrlLiJF", "book_product_number": 6180308644430737000 }, "use_time_info": { "use_time_type": 1, "time_period_list": [ { "start_time": "pmXn5pttWa", "end_time": "VpC6rCWuFN", "end_time_is_next_day": false } ] }, "can_verify_status": 1, "cancel_verify_records": [ { "verify_id": "RB1g8iol22", "certificate_id": "LvcejqA0hM", "times_card_serial_num": 915049859744452400, "benefit_amount": { "platform_discount_amount": 5087105867669536000, "pay_amount": 807823067646202500, "provider_discount_amount": 4723916055877200000, "benefit_amount": 4094656239039365600, "brand_discount_amount": 4956034746174219000, "payment_discount_amount": 5344635594463645000, "principal_amount": 9168582707746310000, "merchant_discount_amount": 4544658252209229000, "total_amount": 6769013147234698000 }, "verifier_unique_id": "yVSQbUMaUH", "poi_id": 1482554317006044200, "verify_time": 9057239440349562000, "can_cancel": false, "verify_type": 1, "extra": { "open_order_id": "L9H8wadyzY" } } ], "advance_purchase_struct": { "time_detail": [ { "time": 1512424398187288300, "time_type": 1 } ], "purchase_type": 1 }, "expire_time": 2217234903814975200, "benefit_card_info": { "total_amount": { "brand_discount_amount": 6711530222324721000, "provider_discount_amount": 6884118825939098000, "platform_discount_amount": 3842957214351937500, "total_amount": 6380442506414394000, "payment_discount_amount": 113731541495654940, "merchant_discount_amount": 5488427656142132000, "pay_amount": 1294004851200730000, "principal_amount": 4418807621114910700, "benefit_amount": 8869032006872025000 }, "left_amount": { "payment_discount_amount": 6435127114935331000, "principal_amount": 7774251529167790000, "provider_discount_amount": 2576938296877613600, "total_amount": 6431258686205177000, "brand_discount_amount": 1015686361194465500, "benefit_amount": 4820289985807130000, "merchant_discount_amount": 6879485047352360000, "platform_discount_amount": 3384477165718714000, "pay_amount": 816427928064694500 } }, "not_available_poi_list": [ "SPZtJXMonR" ], "verify": { "benefit_amount": { "brand_discount_amount": 2017077828479432000, "payment_discount_amount": 7438404467428690000, "provider_discount_amount": 8654599460020386000, "platform_discount_amount": 8749772397043534000, "benefit_amount": 8371670375482194000, "total_amount": 4286948767264222700, "merchant_discount_amount": 9150016396439806000, "principal_amount": 5252918198774087000, "pay_amount": 2718292971054300700 }, "verify_type": 1, "verifier_unique_id": "xBEmB7ge0o", "extra": { "open_order_id": "QXSs5pWRdt" }, "verify_id": "pTmtP3xzty", "poi_id": 310230647054881540, "verify_time": 3950313746957666000, "certificate_id": "PVVjIt9ixx", "times_card_serial_num": 6201342216016339000, "can_cancel": false }, "start_time": 7041507963025973000, "off_peak_discount_info": { "idle_time_limit_type": 1, "has_off_peak_discount": false, "off_peak_time_range": [ { "start_time": 889932792476839600, "end_time": 2010941497478233600, "daily_time_range_list": [ { "end_time_is_next_day": false, "start_time": "SKH5uRcB0B", "end_time": "qWCkHyLRfs" } ], "week_day_list": [ 1 ] } ] }, "status": 1, "dynamic_code_info": { "code_expire_time": "nouCRCA8tJ" }, "amount": { "merchant_discount_detail_list": [ { "discount_amount": 677946152308661100, "discount_id": "XFxS6Y5XX8", "discount_name": "zfpKq2GVKR" } ], "list_market_amount": 2340996355971040000, "platform_discount_amount": 2046644657467785700, "original_currency": "D6UAbbJekl", "coupon_pay_amount": 1539601481712649200, "pay_amount": 2255039727806220800, "origin_list_market_amount": 6939163453323305000, "original_amount": 923138235271834100, "brand_ticket_amount": 602622982035875200, "payment_discount_amount": 291127645691147900, "merchant_ticket_amount": 1727728222948092000 }, "buyer_reserve_info": { "credential_type": 5868387680092039000, "name": "iVtCshhXQs", "enc_credential_numb": "a7F97t5W0Q", "enc_name": "xAILWESfnX", "credential_numb": "MVbgSY0TCT" }, "encrypted_code": "mENC9bHRyw", "time_card": { "times_used": 3064471281515696600, "serial_amount_list": [ { "serial_numb": 5834214460756096000, "amount": { "brand_ticket_amount": 3524007564555374000, "platform_discount_amount": 3199373409685201000, "original_currency": "UcQ8iIZOSd", "pay_amount": 8484309329133401000, "coupon_pay_amount": 2224132166615883300, "merchant_ticket_amount": 5515105374392362000, "list_market_amount": 1620191878263732000, "merchant_discount_detail_list": [ { "discount_name": "adP0C01rlM", "discount_amount": 6894979564820395000, "discount_id": "mLSQw0B6FV" } ], "original_amount": 1200045598101991400, "payment_discount_amount": 8165500257582484000, "origin_list_market_amount": 2414718586506700300 } } ], "time_card_type": 1, "times_count": 8934166593947504000 }, "certificate_id": 5656125740536358000, "deduction_info_list": [ { "is_one_time_buy": false, "order_source": 1, "source_brand_discount_amount": 7494909991112893000, "source_amount": 270723127217948740, "source_selling_price": 8171706176363746000, "voucher_type": 1, "source_payment_discount_amount": 7694004471976967000, "source_sku_name": "KjIGjxZCeM", "groupon_type": 1, "source_item_order_id": "0z9AJEKVl5", "source_user_pay_amount": 184108313952516030, "source_certificate_id": "Y0c3KgLWzQ", "source_certificate_code": "I05QzciMji", "source_order_id": "JWxusfAfRH", "source_provider_discount_amount": 5753586390109805000, "source_sku_id": 748189449311505700, "source_platform_discount_amount": 6053214404197989000, "source_merchant_discount_amount": 5823978157569037000 } ] } ], "verify_token": "mUJVzn78Ix", "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 | 3000001 | 请求过于频繁,请稍后再试 | 重试解决 |
| 200 | 3000001 | 以实际错误信息为准 | |
| 200 | 5000001 | 服务器打瞌睡了,请稍后再试。 | |
| 200 | 3000002 | 以实际错误信息为准 | |
| 200 | 5000009 | 实名信息查询失败,请重试查询 |
