办一下接单台 API

为合作伙伴提供程序化订单管理能力 — 下单、查询、取消,全链路 RESTful

Base URL https://api.banyixia.com/v1 Auth Bearer Token Content-Type application/json

📋 快速参考

Base URL

https://api.banyixia.com/v1
所有请求均使用 HTTPS。路径区分大小写。

认证方式

Bearer Token
控制台 → API 密钥 生成。Header: Authorization: Bearer bnyx_sk_xxx

速率限制

120 次 / 分钟
超出后返回 429 Too Many Requests。响应头 X-RateLimit-Remaining 含剩余配额。

API 版本

v1 (当前)
破坏性变更提前 90 天邮件通知。版本号通过 URL path 前缀标识。

HTTP 状态码

状态码含义说明
200OK请求成功(GET / 列表 / 取消)
201Created资源创建成功(POST 下单)
400Bad Request请求参数缺失或格式错误
401UnauthorizedAPI Key 无效或已过期
404Not Found订单 ID 不存在或不属于当前租户
409Conflict订单状态不允许该操作(如重复取消)
429Too Many Requests超过速率限制
500Internal Server Error服务端异常,请重试或联系技术支持

🔌 API 端点

POST /api/desk/orders 创建新订单

请求体 (Request Body)

参数类型必填说明示例
desk_idstring必填接单台 ID,在控制台「接单台管理」中获取desk_3fA8kL2m
itemsobject[]必填订单项列表,至少 1 项,最多 50 项见下方示例
  items[].namestring必填商品/服务名称,最长 120 字符"拿铁咖啡"
  items[].quantityinteger必填数量,1–9992
  items[].pricenumber必填单价(元),精确到分,0.01–99999.9928.00
customer_namestring必填客户姓名,最长 60 字符"张三"
customer_phonestring可选客户手机号,11 位"13800138000"
notestring可选备注,最长 500 字符"少糖、外带"
callback_urlstring可选订单状态变更时 POST 通知的 URL(需 HTTPS)"https://partner.example.com/webhook"

成功响应 (201 Created)

{
  "id": "ord_7XpQvN2kR",
  "desk_id": "desk_3fA8kL2m",
  "status": "pending",
  "items": [
    { "name": "拿铁咖啡", "quantity": 2, "price": 28.00 },
    { "name": "提拉米苏", "quantity": 1, "price": 36.00 }
  ],
  "total_amount": 92.00,
  "customer_name": "张三",
  "customer_phone": "13800138000",
  "note": "少糖、外带",
  "callback_url": "https://partner.example.com/webhook",
  "created_at": "2026-05-15T10:23:41+08:00",
  "updated_at": "2026-05-15T10:23:41+08:00"
}

错误示例

400 Bad Request — 缺少必填字段
{
  "error": {
    "code": "missing_field",
    "message": "缺少必填字段: desk_id",
    "detail": "请确保请求体中包含 desk_id 字段"
  }
}
401 Unauthorized — Token 无效
{
  "error": {
    "code": "unauthorized",
    "message": "API Key 无效或已过期",
    "detail": "请在控制台检查您的 API Key 状态"
  }
}

cURL 示例

curl -X POST https://api.banyixia.com/v1/api/desk/orders \
  -H "Authorization: Bearer bnyx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "desk_id": "desk_3fA8kL2m",
    "items": [
      { "name": "拿铁咖啡", "quantity": 2, "price": 28.00 },
      { "name": "提拉米苏", "quantity": 1, "price": 36.00 }
    ],
    "customer_name": "张三",
    "customer_phone": "13800138000",
    "note": "少糖、外带"
  }'
💡 注意事项
total_amount 由服务端按 items[].price × items[].quantity 累加计算,传入的 price 字段不会被子项覆盖。
callback_url 仅接收 HTTPS URL,回调超时 5 秒,失败重试 3 次(间隔 2s / 4s / 8s)。
• 订单创建后初始状态为 pending,可通过接单台手动接单或通过 API 取消。
GET /api/desk/orders/{id} 查询订单详情

路径参数 (Path Parameters)

参数类型必填说明示例
idstring必填订单 ID,创建订单时返回ord_7XpQvN2kR

成功响应 (200 OK)

{
  "id": "ord_7XpQvN2kR",
  "desk_id": "desk_3fA8kL2m",
  "status": "pending",
  "items": [
    { "name": "拿铁咖啡", "quantity": 2, "price": 28.00 },
    { "name": "提拉米苏", "quantity": 1, "price": 36.00 }
  ],
  "total_amount": 92.00,
  "customer_name": "张三",
  "customer_phone": "13800138000",
  "note": "少糖、外带",
  "created_at": "2026-05-15T10:23:41+08:00",
  "updated_at": "2026-05-15T10:23:41+08:00"
}

错误示例

404 Not Found
{
  "error": {
    "code": "not_found",
    "message": "订单 ord_NotFoundID 不存在",
    "detail": "请检查订单 ID 是否正确,或该订单不属于当前 API Key 对应的租户"
  }
}

cURL 示例

curl -X GET https://api.banyixia.com/v1/api/desk/orders/ord_7XpQvN2kR \
  -H "Authorization: Bearer bnyx_sk_YOUR_API_KEY"
💡 注意事项
• 只能查询当前 API Key 所属租户的订单。跨租户查询返回 404。
• 响应中的 status 可能为:pending(待接单)、accepted(已接单)、completed(已完成)、cancelled(已取消)。
updated_at 字段在每次状态变更时自动更新。
POST /api/desk/orders/{id}/cancel 取消订单

路径参数

参数类型必填说明示例
idstring必填要取消的订单 IDord_7XpQvN2kR

请求体

参数类型必填说明示例
reasonstring可选取消原因,最长 200 字符"客户主动取消"

成功响应 (200 OK)

{
  "id": "ord_7XpQvN2kR",
  "desk_id": "desk_3fA8kL2m",
  "status": "cancelled",
  "cancel_reason": "客户主动取消",
  "cancelled_at": "2026-05-15T11:05:22+08:00",
  "items": [
    { "name": "拿铁咖啡", "quantity": 2, "price": 28.00 },
    { "name": "提拉米苏", "quantity": 1, "price": 36.00 }
  ],
  "total_amount": 92.00,
  "customer_name": "张三",
  "customer_phone": "13800138000",
  "note": "少糖、外带",
  "created_at": "2026-05-15T10:23:41+08:00",
  "updated_at": "2026-05-15T11:05:22+08:00"
}

错误示例

409 Conflict — 重复取消
{
  "error": {
    "code": "invalid_state",
    "message": "订单 ord_7XpQvN2kR 当前状态为 cancelled,不允许执行取消操作",
    "detail": "仅 pending 和 accepted 状态的订单可以取消"
  }
}

cURL 示例

curl -X POST https://api.banyixia.com/v1/api/desk/orders/ord_7XpQvN2kR/cancel \
  -H "Authorization: Bearer bnyx_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "客户主动取消"
  }'
⚠️ 注意事项
• 取消是 不可逆 操作。已取消的订单无法恢复为其他状态。
• 仅 pendingaccepted 状态的订单可以取消。completed 订单不支持取消。
• 取消成功后,如果创建订单时传入了 callback_url,系统会向该 URL 发送 POST 通知(payload 含 status: "cancelled")。
GET /api/desk/orders 查询订单列表

查询参数 (Query Parameters)

参数类型必填说明示例
statusstring可选按订单状态筛选:pending / accepted / completed / cancelledpending
desk_idstring可选按接单台筛选desk_3fA8kL2m
pageinteger可选页码,从 1 开始,默认 11
per_pageinteger可选每页条数,默认 20,最大 10020
created_afterstring可选创建时间下限(ISO 8601),含该时刻2026-05-01T00:00:00+08:00
created_beforestring可选创建时间上限(ISO 8601),含该时刻2026-05-31T23:59:59+08:00

成功响应 (200 OK)

{
  "data": [
    {
      "id": "ord_7XpQvN2kR",
      "desk_id": "desk_3fA8kL2m",
      "status": "pending",
      "total_amount": 92.00,
      "customer_name": "张三",
      "created_at": "2026-05-15T10:23:41+08:00"
    },
    {
      "id": "ord_aB3cD5eFg",
      "desk_id": "desk_3fA8kL2m",
      "status": "completed",
      "total_amount": 56.00,
      "customer_name": "李四",
      "created_at": "2026-05-14T16:12:03+08:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_count": 47,
    "total_pages": 3
  }
}

错误示例

400 Bad Request — 非法的 status 值
{
  "error": {
    "code": "invalid_param",
    "message": "查询参数 status 值非法: 'deleted'",
    "detail": "status 仅支持: pending, accepted, completed, cancelled"
  }
}

cURL 示例

# 查询所有待接单的订单
curl -X GET "https://api.banyixia.com/v1/api/desk/orders?status=pending&page=1&per_page=20" \
  -H "Authorization: Bearer bnyx_sk_YOUR_API_KEY"

# 查询 2026 年 5 月的订单
curl -X GET "https://api.banyixia.com/v1/api/desk/orders?created_after=2026-05-01T00:00:00%2B08:00&created_before=2026-05-31T23:59:59%2B08:00" \
  -H "Authorization: Bearer bnyx_sk_YOUR_API_KEY"
💡 注意事项
• 列表接口返回的是订单摘要(不含 items 详情和 note),需要完整数据请调详情接口。
• 分页从第 1 页开始。total_pages 为总页数,超出范围返回空数组。
• 时间筛选参数使用 ISO 8601 格式,时区偏移必填(推荐 +08:00)。

💻 多语言代码示例

# ===== 1. 创建订单 =====
curl -s -X POST https://api.banyixia.com/v1/api/desk/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "desk_id": "desk_3fA8kL2m",
    "items": [{"name":"美式咖啡","quantity":1,"price":22.00}],
    "customer_name": "王五",
    "customer_phone": "13900139000"
  }' | jq .

# ===== 2. 查询订单详情 =====
ORDER_ID="ord_7XpQvN2kR"
curl -s -X GET "https://api.banyixia.com/v1/api/desk/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY" | jq .

# ===== 3. 取消订单 =====
curl -s -X POST "https://api.banyixia.com/v1/api/desk/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"测试取消"}' | jq .

# ===== 4. 列表查询(分页)=====
curl -s -X GET "https://api.banyixia.com/v1/api/desk/orders?status=pending&page=1&per_page=10" \
  -H "Authorization: Bearer $API_KEY" | jq .
import requests
import os

API_KEY = os.getenv("BANYIXIA_API_KEY")
BASE_URL = "https://api.banyixia.com/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_order(desk_id, items, customer_name, phone=None, note=None):
    """创建订单"""
    payload = {
        "desk_id": desk_id,
        "items": items,
        "customer_name": customer_name,
    }
    if phone:
        payload["customer_phone"] = phone
    if note:
        payload["note"] = note

    resp = requests.post(f"{BASE_URL}/api/desk/orders", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()


def get_order(order_id):
    """查询订单详情"""
    resp = requests.get(f"{BASE_URL}/api/desk/orders/{order_id}", headers=HEADERS)
    resp.raise_for_status()
    return resp.json()


def cancel_order(order_id, reason="客户取消"):
    """取消订单"""
    resp = requests.post(
        f"{BASE_URL}/api/desk/orders/{order_id}/cancel",
        json={"reason": reason},
        headers=HEADERS,
    )
    resp.raise_for_status()
    return resp.json()


def list_orders(status=None, page=1, per_page=20):
    """查询订单列表"""
    params = {"page": page, "per_page": per_page}
    if status:
        params["status"] = status
    resp = requests.get(f"{BASE_URL}/api/desk/orders", params=params, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()


# ---- 使用示例 ----
if __name__ == "__main__":
    order = create_order(
        desk_id="desk_3fA8kL2m",
        items=[{"name": "美式咖啡", "quantity": 1, "price": 22.00}],
        customer_name="王五",
        phone="13900139000",
    )
    print(f"订单已创建: {order['id']}")

    details = get_order(order["id"])
    print(f"状态: {details['status']}")

    result = list_orders(status="pending")
    print(f"待接单: {result['pagination']['total_count']} 条")
const API_KEY = process.env.BANYIXIA_API_KEY;
const BASE_URL = "https://api.banyixia.com/v1";
const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

/** 创建订单 */
async function createOrder({ deskId, items, customerName, phone, note }) {
  const body = { desk_id: deskId, items, customer_name: customerName };
  if (phone) body.customer_phone = phone;
  if (note) body.note = note;

  const resp = await fetch(`${BASE_URL}/api/desk/orders`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
  if (!resp.ok) throw new Error(`创建失败: ${resp.status}`);
  return resp.json();
}

/** 查询订单详情 */
async function getOrder(orderId) {
  const resp = await fetch(`${BASE_URL}/api/desk/orders/${orderId}`, { headers });
  if (!resp.ok) throw new Error(`查询失败: ${resp.status}`);
  return resp.json();
}

/** 取消订单 */
async function cancelOrder(orderId, reason = "客户取消") {
  const resp = await fetch(`${BASE_URL}/api/desk/orders/${orderId}/cancel`, {
    method: "POST",
    headers,
    body: JSON.stringify({ reason }),
  });
  if (!resp.ok) throw new Error(`取消失败: ${resp.status}`);
  return resp.json();
}

/** 查询订单列表 */
async function listOrders({ status, page = 1, perPage = 20 } = {}) {
  const params = new URLSearchParams({ page, per_page: perPage });
  if (status) params.set("status", status);

  const resp = await fetch(`${BASE_URL}/api/desk/orders?${params}`, { headers });
  if (!resp.ok) throw new Error(`列表查询失败: ${resp.status}`);
  return resp.json();
}

// ---- 使用示例 ----
(async () => {
  const order = await createOrder({
    deskId: "desk_3fA8kL2m",
    items: [{ name: "美式咖啡", quantity: 1, price: 22.00 }],
    customerName: "王五",
    phone: "13900139000",
  });
  console.log(`订单已创建: ${order.id}`);

  const details = await getOrder(order.id);
  console.log(`状态: ${details.status}`);

  const list = await listOrders({ status: "pending" });
  console.log(`待接单: ${list.pagination.total_count} 条`);
})();

🚀 常见集成场景

场景 1:POS 系统自动下单

用例:门店 POS 收银完成后,自动在接单台创建制作工单。

最佳实践:
• 在 POS 结算成功后调用 POST /api/desk/orders,传入 desk_id(厨房/吧台接单台)和订单明细。
• 设置 callback_url 为 POS 回调地址,当接单台完成订单时 POS 可自动更新状态。
• 用 Header X-Idempotency-Key 发送唯一幂等键,防止 POS 重试导致重复下单。
• 订单总额由 API 服务端计算,POS 侧仅传 price × quantity

场景 2:外卖平台对接

用例:美团/饿了么等外卖订单自动同步到店内接单台。

最佳实践:
• 定时轮询外卖平台订单 → 调用 POST /api/desk/orders 下到对应接单台。
• 外卖平台取消订单时 → 调用 POST /api/desk/orders/{id}/cancel
• 使用 GET /api/desk/orders?status=pending 做兜底对账,防止漏单。
• 建议将外卖平台的 order_id 写入 note 字段,方便溯源。

场景 3:数据分析看板

用例:内部 BI 系统拉取订单数据做日报/周报。

最佳实践:
• 使用 GET /api/desk/orders 配合 created_after / created_before 按小时/天拉取增量。
• 设置 per_page=100 减少请求次数,遍历 total_pages 完成全量拉取。
• 结合 status 参数分别统计 pending / completed / cancelled 数量。
• 注意 不超过 120 次/分钟 的速率限制,批量拉取时加 500ms 间隔或使用指数退避。

📝 更新日志

v1.2.0 2026-04-02 新增 created_after / created_before 查询参数,支持按时间范围筛选订单列表。
v1.1.0 2026-02-18 新增 callback_url 字段,订单状态变更时支持 Webhook 回调通知。
v1.0.1 2026-01-10 修复列表接口 per_page 超过 100 时未截断的问题;优化速率限制响应头。
v1.0.0 2025-12-01 首次发布。支持下单、查询详情、取消订单、订单列表四个核心端点。
本页面由 办一下|banyixia.com AI 生成