查询券状态信息

更新时间 2024-07-24 02:58:49

我的收藏

批量查询一个订单中的券的相关状态信息，比如已核销、已退款等状态。

使用限制

单次查询不能超过 20 个。

接口说明

•

如果在券码核销的流程中因为某种异常无法确认当前券码的核销状态，则可以通过这个接口查询券的相关状态信息。

•

只能传入同一个订单下的券列表，不能跨订单查询。

基本信息

基本信息
HTTP URL	`https://open.douyin.com/api/apps/trade/v2/order/query_item_order_info`
HTTP Method	POST
Scope	industry_open.trade.order_common
权限要求	不需要用户授权

请求头

参考通用参数

请求参数

名称	类型	是否必填	描述	示例值
order_id	string	是	抖音开平内部交易订单号，通过预下单回调传给开发者服务，长度 < 64byte	ot123456
item_order_id_list	array(string)	否	交易系统订单号下的商品单号列表。最多支持 20 个商品单传入，超过将报错。如不传，将返回此订单下的所有子单。	["ot123", "ot456"]

请求示例

text复制
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/order/query_item_order_info' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
        "order_id": "ot123456",
        "item_order_id_list": [
                "ot123",
                "ot456"
        ]
}'

响应参数

名称	类型	是否必填	描述	示例值
data	object	是	返回数据
extra	object	是	额外信息，参见通用参数

data 信息

名称	类型	是否必填	描述	示例值
item_list	array(object)	是	列表，返回的item单数据
order_source	string	否	用来标识一类订单的来源，比如 fulfillment_tool = 核销工具类订单	fulfillment_tool

item_list 信息

名称	类型	是否必填	描述	示例
item_order_id	string	是	交易系统商品单号	ot123
item_order_status	number	是	商品单的状态： •0：无效值 •1：待支付 •2：待使用 •3：已核销 •4：订单关闭 •10：待预约 •11：核销中 •20：退款中 •21：已退款	0
valid_start_time	number	是	商品单的有效开始时间，毫秒级的 Unix 时间戳	1658398122000
valid_end_time	number	是	商品单的有效截止时间，毫秒级的 Unix 时间戳	1658398122000
delivery_time	number	是	商品单的核销时间，毫秒级的 Unix 时间戳	1658398122000
item_verify_info	object	否	核销工具类订单才有的抵扣券核销信息。核销工具类订单才需要关注。
times_card_info	object	否	次卡信息，仅次卡类型且支付成功后会返回

item_verify_info 信息

名称	类型	是否必填	描述	示例值
deduct_code	string	是	下单时传入的抵扣券ID，即原生券的certificate_id。	12345
poi_id	string	是	下单时传入的核销门店poi_id	70123
verify_result	object	否	抵扣券的核销信息
verify_cancel_result	object	否	抵扣券的撤销核销信息

verify_result 信息

名称	类型	是否必填	描述	示例值
result_code	number	否	验券结果，0代表成功，非0为失败	0
result_msg	string	否	验券结果说明	验券成功
verify_id	string	否	验券的唯一标识，撤销核销时需要用到	70125
verify_time	int64	否	核销时间，秒级时间戳	1658398122
code	string	否	核销用户券码code，核销成功后返回。需要联系运营加白

verify_cancel_result 信息

名称	类型	是否必填	描述	示例值
cancel_suc	bool	否	撤销核销是否成功	true
cancel_msg	string	否	撤销核销失败的说明
cancel_time	int64	否	成功撤销核销的时间	1658398123

times_card_info

名称	类型	是否必填	描述	示例
total_times	int64	否	总计次数	10
usable_times	int64	否	可使用次数/剩余次数	4
refund_times	int64	否	退款次数(退款中+退款成功)	0
actual_amount_once	int64	否	商品单次现价，单位[分]	100

响应示例

正常示例

json复制
{
  "data": {
    "item_list": [
      {
        "item_order_id": "item_order_id_example_1",
        "item_order_status": 1,
        "valid_start_time": 1642491214992,
        "valid_end_time": 1642491231992,
        "delivery_time": 1642493214992
      },
      {
        "item_order_id": "item_order_id_example_2",
        "item_order_status": 2,
        "valid_start_time": 1642491214992,
        "valid_end_time": 1623491214992,
        "delivery_time": 1642231214992
      }
    ]
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  }
}

异常示例

json复制
{
  "data": {
    "error_code": 13000,
    "description": "系统错误"
  },
  "extra": {
    "sub_error_code": 13000,
    "sub_description": "系统错误",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2191000,
    "description": ""
  }
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	10000	参数错误	参数不符合规范。请根据提示检查参数。
200	13000	系统错误，请重试	内部错误，重试可解决。
200	21047	商品单 id 不合法	检查 item_order_id 是否正确。