📋 快速参考
Base URL
https://api.banyixia.com/v1
所有请求均使用 HTTPS。路径区分大小写。
速率限制
120 次 / 分钟
超出后返回
429 Too Many Requests。响应头 X-RateLimit-Remaining 含剩余配额。API 版本
v1 (当前)
破坏性变更提前 90 天邮件通知。版本号通过 URL path 前缀标识。
HTTP 状态码
| 状态码 | 含义 | 说明 |
|---|---|---|
| 200 | OK | 请求成功(GET / 列表 / 取消) |
| 201 | Created | 资源创建成功(POST 下单) |
| 400 | Bad Request | 请求参数缺失或格式错误 |
| 401 | Unauthorized | API Key 无效或已过期 |
| 404 | Not Found | 订单 ID 不存在或不属于当前租户 |
| 409 | Conflict | 订单状态不允许该操作(如重复取消) |
| 429 | Too Many Requests | 超过速率限制 |
| 500 | Internal Server Error | 服务端异常,请重试或联系技术支持 |
🔌 API 端点
POST
/api/desk/orders
创建新订单
请求体 (Request Body)
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| desk_id | string | 必填 | 接单台 ID,在控制台「接单台管理」中获取 | desk_3fA8kL2m |
| items | object[] | 必填 | 订单项列表,至少 1 项,最多 50 项 | 见下方示例 |
| items[].name | string | 必填 | 商品/服务名称,最长 120 字符 | "拿铁咖啡" |
| items[].quantity | integer | 必填 | 数量,1–999 | 2 |
| items[].price | number | 必填 | 单价(元),精确到分,0.01–99999.99 | 28.00 |
| customer_name | string | 必填 | 客户姓名,最长 60 字符 | "张三" |
| customer_phone | string | 可选 | 客户手机号,11 位 | "13800138000" |
| note | string | 可选 | 备注,最长 500 字符 | "少糖、外带" |
| callback_url | string | 可选 | 订单状态变更时 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)
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| id | string | 必填 | 订单 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。
• 响应中的
•
• 只能查询当前 API Key 所属租户的订单。跨租户查询返回 404。
• 响应中的
status 可能为:pending(待接单)、accepted(已接单)、completed(已完成)、cancelled(已取消)。•
updated_at 字段在每次状态变更时自动更新。
POST
/api/desk/orders/{id}/cancel
取消订单
路径参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| id | string | 必填 | 要取消的订单 ID | ord_7XpQvN2kR |
请求体
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| reason | string | 可选 | 取消原因,最长 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": "客户主动取消"
}'
⚠️ 注意事项
• 取消是 不可逆 操作。已取消的订单无法恢复为其他状态。
• 仅
• 取消成功后,如果创建订单时传入了
• 取消是 不可逆 操作。已取消的订单无法恢复为其他状态。
• 仅
pending 和 accepted 状态的订单可以取消。completed 订单不支持取消。• 取消成功后,如果创建订单时传入了
callback_url,系统会向该 URL 发送 POST 通知(payload 含 status: "cancelled")。
GET
/api/desk/orders
查询订单列表
查询参数 (Query Parameters)
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| status | string | 可选 | 按订单状态筛选:pending / accepted / completed / cancelled | pending |
| desk_id | string | 可选 | 按接单台筛选 | desk_3fA8kL2m |
| page | integer | 可选 | 页码,从 1 开始,默认 1 | 1 |
| per_page | integer | 可选 | 每页条数,默认 20,最大 100 | 20 |
| created_after | string | 可选 | 创建时间下限(ISO 8601),含该时刻 | 2026-05-01T00:00:00+08:00 |
| created_before | string | 可选 | 创建时间上限(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"
💡 注意事项
• 列表接口返回的是订单摘要(不含
• 分页从第 1 页开始。
• 时间筛选参数使用 ISO 8601 格式,时区偏移必填(推荐
• 列表接口返回的是订单摘要(不含
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 结算成功后调用
• 设置
• 用 Header
• 订单总额由 API 服务端计算,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 系统拉取订单数据做日报/周报。
最佳实践:
• 使用
• 设置
• 结合
• 注意 不超过 120 次/分钟 的速率限制,批量拉取时加 500ms 间隔或使用指数退避。
最佳实践:
• 使用
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
首次发布。支持下单、查询详情、取消订单、订单列表四个核心端点。