# 订单查询 order_query 查询订单详情接口，用于开发者根据订单号或商户订单号查询对应订单的支付状态及详细信息。适用于支付完成后的订单状态同步、对账、订单详情展示等业务场景。 ## 使用限制 - 调用频次限制：请遵守平台默认 QPS 限制，避免高频调用。 - 查询时需提供 order_id 或 out_order_no 中的至少一个，否则查询将失败。 ## 接口说明 - 业务场景：适用于开发者在用户完成支付后，主动查询订单的支付状态、支付方式、支付金额等详细信息。常见场景包括：支付结果页展示、定时对账任务、订单异常排查等。 - 前提条件：调用方需已完成应用创建，并通过 get_client_token 接口获取到有效的应用级 AccessToken。 - 注意事项： - order_id 为平台侧订单号，out_order_no 为商户侧订单号，两者均可用于查询，但建议优先使用 order_id。 - 请求 Body 中的 x_db_access_token 字段为冗余字段，鉴权以请求头 x-DB-AccessToken 为准。 ## 基本信息 | 名称 | 描述 | |-|-| | HTTP Path | /api/trade_basic/v1/developer/order_query | | HTTP Method | POST | | 权限要求 | - 需要申请权限 - 申请路径：智能服务开发者平台控制台 > 应用详情 > 能力 > 支付权限 - 需要应用级 AccessToken | ## 请求头 | 名称 | 类型 | 必填 | 描述 | |-|-|-|-| | content-type | string | 是 | 固定值 "application/json" | | x-DB-AccessToken | string | 是 | 调用 get_client_token 接口生成的应用级 token，示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn\*\*\*\*\*\* | ## 请求参数 ### Body | 名称 | 类型 | 是否必填 | 描述 | 示例值 | |-|-|-|-|-| | order_id | string | 否（与 out_order_no 二选一） | 平台侧订单号，由豆包支付系统生成的唯一订单标识 | 70214322040407612\*\*\* | | out_order_no | string | 否（与 order_id 二选一） | 商户侧订单号，由开发者自行生成的唯一订单标识，长度不超过64个字符 | MER2024010100\*\*\* | ## 请求示例 cURL ```shell curl -X POST '/api/trade_basic/v1/developer/order_query' \ -H 'content-type: application/json' \ -H 'x-DB-AccessToken: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******' \ -d '{ "order_id": "70214322040407612***", "out_order_no": "" }' ``` Go ```go package main import ( "bytes" "encoding/json" "fmt" "io/ioutil" "net/http" ) func main() { path := "/api/trade_basic/v1/developer/order_query" reqBody := map[string]string{ "order_id": "70214322040407612***", "out_order_no": "", } jsonData, _ := json.Marshal(reqBody) req, _ := http.NewRequest("POST", path, bytes.NewBuffer(jsonData)) req.Header.Set("content-type", "application/json") req.Header.Set("x-DB-AccessToken", "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******") client := &http.Client{} resp, err := client.Do(req) if err != nil { fmt.Println("Error:", err) return } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) fmt.Println(string(body)) } ``` Java ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class OrderQuery { public static void main(String[] args) throws Exception { String path = "/api/trade_basic/v1/developer/order_query"; String requestBody = "{\"order_id\":\"70214322040407612***\",\"out_order_no\":\"\"}"; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(path)) .header("content-type", "application/json") .header("x-DB-AccessToken", "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******") .POST(HttpRequest.BodyPublishers.ofString(requestBody)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` Node.js ```javascript const axios = require('axios'); async function orderQuery() { const path = '/api/trade_basic/v1/developer/order_query'; const headers = { 'content-type': 'application/json', 'x-DB-AccessToken': 'clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******' }; const data = { order_id: '70214322040407612***', out_order_no: '' }; try { const response = await axios.post(path, data, { headers }); console.log(response.data); } catch (error) { console.error('Error:', error.message); } } orderQuery(); ``` ## 响应参数 | 名称 | 类型 | 是否必填 | 描述 | 示例值 | |-|-|-|-|-| | code | integer | 是 | 响应状态码，0 表示成功，非 0 表示失败 | 0 | | msg | string | 是 | 响应状态描述信息 | success | | log_id | string | 是 | 请求日志 ID，用于问题排查时提供给技术支持 | 20240101120000ABCDEF\*\*\*\*\*\* | | data | object | 否 | 订单详情对象，仅在查询成功时返回 | 见下方 data 字段说明 | ### data 字段说明 | 名称 | 类型 | 是否必填 | 描述 | 示例值 | |-|-|-|-|-| | app_id | string | 是 | 智能服务的应用 ID | tt1234567890\*\*\*\*\*\* | | order_id | string | 是 | 平台侧订单号 | 70214322040407612\*\*\* | | out_order_no | string | 是 | 商户侧订单号 | MER2024010100\*\*\* | | merchant_uid | string | 是 | 收款商户uid | | | pay_order_no | string | 是 | 支付渠道的交易流水号 | PAY20240101000\*\*\* | | pay_status | string | 是 | 支付状态。枚举值： INIT（初始化）、PROCESSING（处理中）、SUCCESS（成功）、FAIL（失败，理论上不会有） | PAID | | pay_time | string | 否 | 支付完成时间，格式为秒级 Unix 时间戳字符串 | 1704067200 | | pay_type | string | 否 | 支付方式。枚举值：WECHAT - 微信支付；ALIPAY - 支付宝；BANK_CARD - 银行卡 | WECHAT | | total_amount | string | 是 | 订单总金额，单位为分 | 9900 | | trade_time | string | 是 | 下单时间，格式为秒级 Unix 时间戳字符串 | 1704067100 | ## 响应示例 ### 正常示例 ```json { "code": 0, "msg": "success", "log_id": "20240101120000ABCDEF******", "data": { "app_id": "tt1234567890******", "order_id": "70214322040407612***", "out_order_no": "MER2024010100***", "merchant_uid": "test_merchant_1", "pay_order_no": "PAY20240101000***", "pay_status": "PAID", "pay_time": "1704067200000", "pay_type": "WECHAT", "total_amount": "9900", "trade_time": "1704067100000" } } ``` ### 异常示例 ```json { "code": 500000001, "msg": "Parameter error", "log_id": "20240101120001GHIJKL******", "data": null } ``` ## 错误码 ### 通用错误码（模块编号 00） | 错误码 | 错误名称 | 描述（msg） | 排查建议 | |-|-|-|-| | 0 | Success | success | 请求成功，无需处理 | | 500000000 | OApiCommonInternalError | internal error | 系统内部错误，请稍后重试，若持续出现请携带 log_id 联系技术支持 | | 500000001 | OApiCommonDeveloperParamError | Parameter error | 请求参数错误，请检查 order_id 和 out_order_no 是否至少传入一个，以及参数格式是否正确 | | 500000002 | OApiCommonDeveloperRateLimitError | Rate limit error | 请求触发限流，请降低调用频率后重试 | | 500000003 | OApiCommonVerifySignFailError | Verify sign fail | 签名验证失败，请检查 x-DB-AccessToken 是否有效、是否过期，必要时重新调用 get_client_token 获取新 token | ### 交易模块错误码 | 错误码 | 错误名称 | 描述（msg） | 排查建议 | |-|-|-|-| | 500020002 | OApiTradeOutOrderIDExistError | out_order_no already exist | 商户订单号已存在，请勿重复创建，如需查询请使用该 out_order_no 直接查询 | | 500020003 | OApiTradeOutRefundIDExistError | out_refund_no already exist | 退款单号已存在（非 order_query 直接相关，但可能在关联流程中出现） | | 500020004 | OApiTradeSignAbnormalError | Sign abnormal | 交易签名异常，请检查请求签名逻辑是否正确 | | 500020005 | OApiTradeOrderNotFoundError | Order not found | 订单不存在，请确认 order_id 或 out_order_no 是否正确，订单是否已成功创建 | | 500020006 | OApiTradeRefundNotFoundError | Refund not found | 退款单不存在（非 order_query 直接相关，但可能在关联流程中出现） |