订单查询
通过接口查询指定范围的订单列表及订单详情:
1、查询指定状态的订单列表,用于对账或差异单最新状态确认;
2、查询指定用户的订单列表,用于积分计算、订单展示;
3、查询指定订单详情,用于接口补偿处理。
开票说明
尊敬的商家,依据税务规则与《抖音生活服务平台商户合作协议》的约定,如用户向商家申请开具发票,商家应按照用户实际支付金额向用户开具相应金额的发票。用户的实际支付金额可参考订单查询pay amount字段展示的具体金额(用户实际支付金额,不含平台等其他方补贴的金额)。
针对平台补贴需向平台开具增值税发票,请勿开具给用户。若商家向用户超额开具发票,由此导致的损失及税务风险需由商家自行承担
接口说明
- 服务商通过接口查询订单详情,支持三种查询方式:
- 根据订单 ID 或第三方订单号,查询对应订单详情,入参:订单 ID/第三方订单号、商户 id;该接口为订单维度查询,不支持券维度查询。
- 根据订单状态和商户 id,查询指定时间内该商户下的订单列表,入参:商户 id、订单状态、创单起止时间/修改起止时间;
- 根据用户 id 和商户 id,查询某用户在该商户下的所有订单,入参:商户 id、用户 id、创单起止时间/修改起止时间;
- 支付后未发码/发码失败订单查询方式:限定订单状态为“已支付”,如用户下单后超过 10 分钟未发码会发起退款;
- 退款申请待审核订单查询方式:限定券状态为“退款中”,如退款状态未响应超过 72 小时会自动退款。
- 承载总qps:200 (单服务商应用默认:20)
使用限制
SLA:支持的最大QPS:20;PCT99承诺值:2ms;
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/goodlife/v1/trade/order/query/ |
| HTTP Method | GET |
| Scope | life.capacity.order.query |
| 权限要求 |
|
请求参数
请求头
access-token必填String
示例:clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
固定值"application/json"
Rpc-Transit-Life-AccountString
来客商户根账户ID
Query
account_id必填String
来客商户根账户ID
page_num必填Int32
页数从1开始,如果使用page分页,页数*大小不能超过10000
page_size必填Int32
页大小,取值范围1~100
create_order_end_timeInt64
创单结束时间(秒时间戳,创单起止时间必须同时传入)
create_order_start_timeInt64
创单起始时间 (秒时间戳,创单起止时间必须同时传入)
cursorArray<String>
根据游标滚动请求,直到返回结果数量小于请求的size或未返回search_after结束;
首页传"0",之后传返回参数中的CursorValue string数组拼接的string,如CursorValue返回参数["0","1"],则传"0,1";
如果传入此参数,会优先使用cursor翻页,而不是page翻页,但page_size和page_num是必填项,不传会报错
ext_order_idString
开发者系统中的订单号
get_secret_numberBool
是否需要查询配送信息
open_idString
抖音内部用户的一种唯一标识
如果对接了会员通,可以通过接收会员入会SPI接口获取并保存
order_idString
抖音生活服务订单ID
见抖音-团购频道-订单详情
order_statusInt32
订单状态
update_order_end_timeInt64
修改结束时间(秒时间戳,修改起止时间必须同时传入)
update_order_start_timeInt64
修改起始时间 (秒时间戳,修改起止时间必须同时传入)
请求示例
curl --location --request GET 'https://open.douyin.com/goodlife/v1/trade/order/query/?update_order_end_time=1819156761207324039&page_num=5301112976713432450&create_order_start_time=6069121345827128020&order_status=2479197255620187492&get_secret_number=false&update_order_start_time=1352520420819435054&account_id=WgiVCokAU8&order_id=R0vomu4iGn&create_order_end_time=6186194007074038284&open_id=JKLwMXkgXF&cursor=[wcZuYZiRLi]&page_size=6340295797970494689&ext_order_id=qm9RWOZCNM' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
extra必填Struct
扩展信息
展开子属性
dataStruct
数据列表
展开子属性
响应示例
正常响应示例异常响应示例
{ "data": { "orders": [ { "contacts": [ { "name": "07PMX4wFBd", "phone": "4ZWpLwQXHX", "phone_encrypt": "eGCbaWYmik" } ], "payment_discount": 1199723458810637000, "poi": { "poi_id": "GuMAVROTPy", "poi_name": "OCyC8qkMIo", "url": "8TeHXKiuQl" }, "order_type": 6735163536744511000, "pay_bill_info": { "total_pay_amount": 2076485479018538500, "is_timely_pay_bill": false }, "receiver_info": { "receiver_name": "oMXSRmAiNQ", "lat": 0.14764108547701002, "town": "ImbVGzT989", "location_name": "sy1CZhZLwy", "city": "NJXTTEDqwP", "receiver_real_phone": "JNQ8u0SR13", "secret_number": "DTP5unuLWR", "location_address": "FqdSPplD6r", "receiver_phone": "Qr0DmPRCJE", "district": "lp1Lqi6dGf", "province": "aGkdEfABVQ", "lng": 0.5910046029053746, "door_plate_num": "XkFXMemwEi" }, "is_deliver_later": false, "craftsman_uid": "zzP83irQdL", "third_sku_id": "PKrBw8vDz3", "anchor_id": 4293278443010204000, "count": 5458252410969882000, "discount_amount": 1474484847244932000, "create_order_time": 751956387533111400, "open_id": "1aCtWl4kJC", "certificate": [ { "refund_time": 4092492425725339000, "combination_id": "a9mLVNxz7C", "fulfil_mode": 1, "order_item_id": "UXq5zAnGGV", "refund_amount": 6619566701653722000, "certificate_id": "d7pZAA6jr8", "item_status": 600498863251016000, "item_update_time": 4586337453933928000 } ], "sku_id": "guu3v0V7B3", "source_order_id": "7FL4iu9Lcw", "order_id": "JvdfhJSeaP", "receipt_amount": 3221229004557255700, "order_sale_info": { "sale_channel": "DpFBdIRIuc", "transfer_nickName": "hGSRPGkMIm", "transfer_uid": "WZxpkVqqVL", "transfer_douyin_uid": "Ynr5AJtYj8", "sale_role": "6H2BMDkDzP" }, "original_amount": 5134359451815500000, "products": [ { "third_sku_id": "psIBqoYuia", "ext_product_id": "nAftojcDMs", "snapshot_product": { "product_attr": { "voucher_par_type": 1, "dynamic_par_rule": { "dynamic_par_min_amount": 9064915150547097000, "dynamic_par_max_amount": 3632393865990709000, "dynamic_par_rule_item_list": [ { "time_period": { "use_start_time": "qXI82jRbrU", "use_end_time": "EpKxGc2DOw", "end_time_is_next_day": false }, "deductible_amount": 1618568249961316400, "day_of_week": [ 1 ] } ], "dynamic_par_rule_desc": "mQmE3srGoY" }, "show_channel": 1, "advance_purchase_struct": { "time_detail": [ { "time_type": 1, "time": 5738838781499862000 } ], "purchase_type": 1 }, "combo_package_verify_limit_struct": { "type": 1, "product_id_index": { "950527450494307003": 50377187595463370 } } }, "tag_info_list": [ { "TagKey": "zl8IA54qy1", "TagName": "J15ts0xS24", "TagValue": "wNFGssRT5n" } ] }, "product_name": "UtdJeT9pHu", "origin_amount": 948452420732143400, "product_origin_amount": 8521902012130872000, "num": 4372480734733027000, "product_id": "gDlsJRbWJG", "sku_id": "rC7RhfJskT", "commodities": [ { "option_count": 5209608739063674000, "items": [ { "unit": "hj7IB9ji9M", "sku_attr_list": [ { "attr_name": "oDI8anjBRx", "num": 6767203479315666000 } ], "price": 1204273975591437800, "name": "oF683vUPui", "count": 9084914833706442000, "attr_list": [ "P2lECCV25M" ], "desc": "4X891Ik04V", "item_tag": "UlIHqzK2zU" } ], "group_name": "1XtE6fhtba", "total_count": 799756637247009800 } ] } ], "room_id": "RlhxFLhXta", "reservation_gift": { "reserved_gift_content": "Swe0uKjUko", "has_reserved_gift": false, "reserved_gift_quantity": "Zm9es5uAyF" }, "discounts": [ { "platform_discount_amount": 3307746246880021500, "provider_discount_amount": 4442419432957876700, "idle_time_info": { "idle_time_limit_type": 1, "WriteOffTimeLimit": { "WeekDayList": [ 1 ], "WriteOffStartTime": 6015697643511591000, "WriteOffEndTime": 6406434322072637000, "DailyTimeRangeList": [ { "StartTime": "xQwg7r0A39", "EndTime": "aL5LgKCBv3" } ], "RelativeTime": { "RelativeTimeType": 1, "RelativeTime": 249616619842048350 } } }, "brand_discount_amount": 6101356284901456000, "discount_type": 1887275469187353600, "discount_amount": 3313012654557048000, "merchant_discount_amount": 8040359334981665000 } ], "buyer_info": { "buyer_real_phone": "r88mA9zcaU", "buyer_phone": "qwwyWPNa73", "buyer_secret_number": "awGrD652yU" }, "user_id": 5502981723284382000, "intention_poi_id": "ajJZFP84fz", "pay_time": 6847833724036811000, "sku_name": "kHZ0JZJbzt", "pay_amount": 7704181209462324000, "merchant_info": { "account_id": "nDWuo9Otp8", "account_name": "nsAjGmaxN9" }, "amount_info": { "estimated_order_income": 6591996703469929000, "platform_deliver_freight_fee": 7271707011547700000, "pay_amount": 882757826239350300, "provider_discount_amount": 3308198907850835000, "sale_price": 3835222134691769300, "pay_discount_amount": 4426822874445865500, "product_origin_amount": 366315948196344700, "deduct_amount": 682123067697727900, "platform_discount_amount": 9120275017049026000, "activities_fee_amount": 5589761727083048000, "merchant_discount_amount": 8889778116730242000, "brand_discount_amount": 2884080589691571700, "commission_amount": 3928304907668328000, "freight_pay_amount": 7459967216345624000, "merchant_deliver_freight_fee": 6278191048380531000, "deduct_info_list": [ { "source_sku_name": "8aruoOxtRI", "source_merchant_discount_amount": 2623332226331602000, "source_provider_discount_amount": 7419711600441137000, "source_brand_discount_amount": 1875868879136821200, "source_selling_price": 4867104156335749000, "source_pay_amount": 1225397556810192100, "source_order_id": "tdTcL978J6", "source_sku_id": 6396909197849804000, "source_payment_discount_amount": 569331451894620100, "source_certificate_id": "tVzJ2APowI", "source_product_name": "gFiDz90CiO", "source_platform_discount_amount": 9125705619316988000, "groupon_type": 1, "source_origin_amount": 6602682038683749000, "voucher_type": 1, "source_product_id": 2471719536867962400 } ], "origin_amount": 8236771508709511000 }, "update_order_time": 5243186141189703000, "poi_id": "me53hXG34l", "delivery_info": { "sys_expect_time": "FrGL6VqaF7", "remark": "osq8SJu9QP", "table_ware": "82ONtYLitU", "deliver_model": 6599249908903982000, "shop_number": "RmPeFi0m4e", "is_book": false, "user_expect_time": "b14YoNCEQR" }, "sub_order_amount_infos": [ { "discount_amount": 8948959892979164000, "pay_amount": 1944939441990337500, "receipt_amount": 3225502972103638000, "discounts": [ { "discount_type": 8313157462679294000, "discount_amount": 8666411380367287000, "merchant_discount_amount": 5458758968633533000, "platform_discount_amount": 4239919407566020000, "provider_discount_amount": 3121053480425302500, "idle_time_info": { "idle_time_limit_type": 1, "WriteOffTimeLimit": { "DailyTimeRangeList": [ { "StartTime": "K4fzVkurvL", "EndTime": "MQiV3n4kJZ" } ], "RelativeTime": { "RelativeTime": 3809416097783390000, "RelativeTimeType": 1 }, "WeekDayList": [ 1 ], "WriteOffStartTime": 7023172793834125000, "WriteOffEndTime": 5046013475134687000 } }, "brand_discount_amount": 6722316607843551000 } ], "sub_order_type": 2093592683062715600, "combination_id": "KPPcZ52idj", "sub_order_id": "kvo1fhK0Md", "origin_amount": 1098732746600910500 } ], "order_status": 4861481074828955000 } ], "page": { "page_num": 7364029998029336000, "page_size": 2145075078922130000, "total": 2678498293866260500 }, "search_after": { "CursorValue": [ "kXNWMdEEKc" ], "AllCursorValue": [ [ "HfPw03z3ce" ] ], "Size": 8477739389886884000 }, "error_code": 0, "description": "" }, "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "20260514173734C5E5CA63A2F70B01D0A7", "now": 1778751457 } }
错误码
| 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 | 2100001 | 未知错误 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
| 200 | 2100004 | 系统繁忙,此时请开发者稍候再试 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
| 200 | 2100005 | 参数不合法 | 更换参数 |
| 200 | 5000001 | 服务器打瞌睡了,请稍后再试。 | |
| 200 | 3000001 | 以实际错误信息为准 |
附录
(1)订单维度订单状态
order | 状态 | 状态定义 |
0 | 初始化 | 创单初始值 |
100 | 待支付 | 创单成功,未完成支付,15min待支付等待期 |
101 | 支付取消 | 用户取消支付或超时未支付 |
200 | 已支付 | 用户完成支付 |
201 | 待使用 | 发码成功,商品还未使用或完成预约 |
1 | 已完成 | 订单完成履约或者全部退款 |
(2)预售-券维度的订单状态
value | B端 | 状态语义 | 驱动角色 |
0 | 初始化 | 创单初始值 | - |
100 | 待使用 | 该商品未发生预约、预订失败回滚 | 系统 |
200 | 预订中 | 用户正在确认该商品的预订单 | 商户 |
201 | 已预订 | 用户已确认预约信息,契约达成 | 用户 |
300 | 退款中 | 发起退款流程 | 用户/商户/系统/客服 |
301 | 已退款 | 退款成功 | 系统 |
400 | 履约中 | 已到履约时间,订单开始履约 | 系统 |
401 | 已履约 | 该商品完成履约 | 系统 |
(3)团购-券维度的订单状态
value | B端 | 状态语义 | 驱动角色 |
0 | 初始化 | 创单初始值 | - |
100 | 待使用 | 该商品未发生预约、预订失败回滚 | 系统 |
300 | 退款中 | 发起退款流程 | 用户/商户/系统/客服 |
301 | 已退款 | 退款成功 | 系统 |
400 | 履约中 | 已到履约时间,订单开始履约 | 系统 |
401 | 已履约 | 该商品完成履约 | 系统 |
