跳到内容
API 文档
Esc
↑↓切换↵打开⌘J预览

查询订单

仅查询当前商家账户内的订单，不会透露其他商家的订单是否存在。当前版本不接受 query 参数，URL 带 query 时返回 400。

GET/orders/{order_code}
Path parameters
order_codeOrderCoderequired
min length 3 · max length 40 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{2,39}$
Responses
200返回订单。响应不包含永久有效的顾客免登录链接。
dataOrderrequired
Show properties
order_codeOrderCoderequired
由调用方指定的订单编号，同一商家内唯一，是创建订单的幂等键。 ⚠️ 它同时是顾客自助验证身份时的因子之一（凭「手机号 + 订单号」绑定微信、在公众号里找订单、找回密码）， 因此必须不可预测：请使用随机字符串（建议至少 8 位随机字母数字，可带固定前缀便于对账）， ⛔ 不要用自增序号、日期加流水号或 CRM 主键这类能推算出来的编号。 Darkroom 自己生成的订单号是 6 位随机大写字母数字（约 10 亿种组合），在限流下被猜中的概率接近零； 自定义连号会让这层保护失效。详见接入指南「幂等与错误处理」中的「订单号怎么取」。
min length 3 · max length 40 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{2,39}$
statusstringrequired
scheduled_datestring<date>required
scheduled_start_timestringrequired
matches ^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$
store_codestringrequired
servicesServiceSummary[]required
Show properties
Array of ServiceSummary
service_codestringrequired
min length 1 · max length 64
unit_price_amountMoneyAmountrequired
matches ^(0|[1-9][0-9]{0,7})\.[0-9]{2}$
quantityintegerrequired
min 1 · max 999
namestringrequired
total_price_amountMoneyAmountrequired
matches ^(0|[1-9][0-9]{0,7})\.[0-9]{2}$
coupon_codestring | nullrequired
prepaymentPrepaymentrequired
Show properties
amountMoneyAmountrequired
matches ^(0|[1-9][0-9]{0,7})\.[0-9]{2}$
methodstring | null
可用值由当前商家配置决定。
min length 1 · max length 64
remarkstring | null
min length 1 · max length 1000
customerCustomerSummaryrequired
Show properties
customer_idstringrequired
namestring | nullrequired
country_calling_codestringrequired
mobilestringrequired
emailstring<email> | nullrequired
genderstring | nullrequired
Allowed:femalemaleunspecifiednull
childChildInput | any
Show properties
Any of:
ChildInput
namestring | null
min length 1 · max length 100
genderstring | null
Allowed:femalemaleunspecifiednull
birthdaystring<date> | null
any
any
customer_remarkstring | nullrequired
team_remarkstring | nullrequired
created_atstring<date-time>required
request_idstringrequired
401`invalid_token`（token 格式非法、已过期或已被撤销）或 `missing_token` （缺少 `Authorization: Bearer`）。收到 401 后，可以获取新令牌并重试一次； 如果仍返回 401，请停止自动重试并检查凭据状态。
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsErrorDetail[]
Show properties
Array of ErrorDetail
fieldstringrequired
reasonstringrequired
request_idstringrequired
403`insufficient_scope`（token 的 scope 不含本端点所需权限）或 `credential_disabled`（凭据已被停用）。 `orders:write` 不包含 `orders:read`；查询订单必须显式授予 `orders:read`。
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsErrorDetail[]
Show properties
Array of ErrorDetail
fieldstringrequired
reasonstringrequired
request_idstringrequired
404当前商家账户中不存在对应订单。
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsErrorDetail[]
Show properties
Array of ErrorDetail
fieldstringrequired
reasonstringrequired
request_idstringrequired
429API 同时采用分钟配额和秒级突发限制，两者使用不同的等待时间： - `rate_limit_exceeded`：已达到分钟配额，默认值为 20 req/min/key。 `Retry-After` 表示距下一分钟窗口的秒数。 - `burst_limit_exceeded`：已达到 2 req/s/key 的短时请求限制。 `Retry-After` 通常为 1 秒。 秒级突发限制不会提高分钟配额。即使请求速率不超过 2 req/s， 每分钟请求总量仍不得超过对应凭据的分钟配额。 `/oauth/token` 另有独立配额（10 req/min/client_id）。
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsErrorDetail[]
Show properties
Array of ErrorDetail
fieldstringrequired
reasonstringrequired
request_idstringrequired
503`api_temporarily_unavailable` 表示 API 功能、凭据服务或订单依赖暂时不可用。 可以使用设有次数上限的指数退避策略重试，避免短时间内发送大量重复请求。
errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsErrorDetail[]
Show properties
Array of ErrorDetail
fieldstringrequired
reasonstringrequired
request_idstringrequired
Request
curl -X GET "https://api.darkroom.net/v2/orders/crm-20260727-K7Q2XM"
Response
{
  "data": {
    "order_code": "crm-20260727-K7Q2XM",
    "status": "string",
    "scheduled_date": "<date>",
    "scheduled_start_time": "string",
    "store_code": "string",
    "services": [
      {
        "service_code": "string",
        "unit_price_amount": "699.00",
        "quantity": 0,
        "name": "string"
      }
    ],
    "total_price_amount": "699.00",
    "coupon_code": "string",
    "prepayment": {
      "amount": "699.00",
      "method": "string",
      "remark": "string"
    },
    "customer": {
      "customer_id": "string",
      "name": "string",
      "country_calling_code": "string",
      "mobile": "string",
      "email": "<email>",
      "gender": "female",
      "child": {
        "name": "string",
        "gender": "female",
        "birthday": "<date>"
      }
    },
    "customer_remark": "string",
    "team_remark": "string",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "request_id": "string"
}