开发者文档

开始使用

从您的仪表盘中创建一个 API 令牌，位置在 API 令牌和 Webhook. 选择 read 和/或 write 能力，并复制该令牌——它只会显示一次。

快速检查您的令牌是否有效：

curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer YOUR_TOKEN"

身份验证

在每个请求中以 Bearer 头的形式发送您的令牌：

Authorization: Bearer YOUR_TOKEN

如需快速测试，您也可以改为传入 ?api_token=YOUR_TOKEN 作为查询参数，但强烈建议使用请求头，以免令牌泄漏到日志中。

受限令牌

超越粗粒度 read/write, 令牌可以被限定到特定资源，通过 resource:action 能力。资源： restaurants, menu, orders, customers, analytics, drivers, webhooks; 操作 read, write. 在仪表盘中创建令牌时进行选择。

覆盖规则： * 授予一切；一个 :write 范围也会授予其对应的 :read; 粗粒度 read/write 表现如同 *:read / *:write. 缺少所需范围的请求会返回 403. 旧版 read/write 令牌不受影响。

令牌在静态存储时会被哈希处理（SHA-256），并可携带可选的过期时间。您可从仪表盘立即吊销任意令牌。

速率限制

该 API 允许 每分钟 120 个请求 每个令牌。超出后会返回 429 Too Many Requests 并带有一个 Retry-After 头。标准的速率限制头会包含在每个响应中：

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

错误

任何针对 /api/v1 路由的错误都会返回常规的 HTTP 状态码和单一的 JSON 封装——一个供人阅读的 message, 一个稳定的、供机器读取的 code, 以及（在校验时）一个按字段的 errors 地图

{ "message": "Invalid or expired token.", "code": "unauthenticated" }

{ "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": { "title": ["The title field is required."] } }

分页

列表端点返回 Laravel 风格的分页封装。使用 ?page= 查询参数来翻页。

{
  "data": [ ... ],
  "current_page": 1,
  "last_page": 3,
  "per_page": 20,
  "total": 47
}

读取餐厅与菜单

列出该令牌拥有的餐厅，分页（每页 20 条）。

{
  "data": [
    { "id": 12, "title": "Nova Bistro", "slug": "nova-bistro",
      "url": "https://.../nova-bistro", "template": "linen",
      "created_at": "2026-06-01T10:22:00+00:00" }
  ],
  "current_page": 1, "last_page": 1, "total": 1
}

单个餐厅及其菜单分类和商品数量。

按分类分组的完整有效菜单。

[
  { "id": 3, "name": "Starters",
    "items": [
      { "id": 88, "name": "Bruschetta", "price": 6.50,
        "is_sold_out": false, "is_popular": true, "is_vegan": true,
        "is_halal": true, "calories": 210 }
    ]
  }
]

管理菜单 撰写

针对分类和商品的完整增删改查——商家端应用运行菜单所需的一切。所有写入端点都需要一个 write 令牌，并限定于您拥有的某家餐厅。图片上传不在 JSON 的处理范围内；请在下列字段中传入一个已托管的 URL： image.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/menu/items \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "category_id": 3, "name": "Margherita", "price": 11.00,
    "description": "San Marzano, mozzarella, basil",
    "is_vegan": true, "is_halal": true, "calories": 850
  }'

快速“86”（停售）开关。发送 {"is_sold_out": true}, 或省略请求体以切换状态。

订单

订单按最新在前排列，分页（每页 30 条）。使用以下方式筛选： ?status=.

包含明细项、附加项、司机和配送时间线的完整订单详情。

创建订单——这就是一个 客户端应用 提交购物车的方式（令牌由商家后端持有）。每个商品都会对照餐厅的实时菜单进行校验；售罄或非本餐厅的商品会导致整个订单被拒绝（422）。触发 order.created 并返回完整订单，包括其 track_token.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/orders \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "delivery",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "address": "9 Cedar Road",
    "tip_amount": 3.00,
    "note": "Ring the bell",
    "source": "customer_app",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12], "note": "no onion" },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

订单 type 是以下之一： on-table, takeaway, delivery. 用于 on-table 传入 table_number; 用于 delivery 传入 address.

幂等性。 发送一个 Idempotency-Key 头（或请求体中的 client_uuid) 在任意创建订单的调用上。使用相同键重试会返回原始订单，绝不会创建重复项——对于丢失的响应和离线重放都是安全的。键按每家餐厅限定范围。

更新厨房状态 (new|preparing|ready|delivered|completed|cancelled). 触发 order.status_changed.

店面 API（按餐厅令牌）

一个独立的、面向公众的 API，通过以下方式认证： 按餐厅的店面令牌 作为以下方式发送 X-Storefront-Token （而非所有者的 Bearer 令牌）。从您的仪表盘签发这些令牌；每个令牌只能访问其自身的餐厅。读取范围为 menu:read; 下单需要 order:write 权限范围

该令牌所属餐厅的完整菜单（规格、附加项、分组、图库）。

该令牌所属餐厅的基本餐厅信息。

代表食客提交购物车。服务端定价并 未支付 （食客到店/收货时付款）； takeaway 或 on-table 仅限于此。每个商品都会对照实时菜单进行校验——售罄或非本餐厅的商品会导致整个订单被拒绝（422）。上限：每单 40 件，每行 30 个数量。可选 coupon_code 在服务端应用店主折扣。触发 order.created 并返回 track_token + continue_url.

curl -X POST https://www.menubarcode.com/api/v1/storefront/orders \
  -H "X-Storefront-Token: YOUR_STOREFRONT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "takeaway",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "coupon_code": "WELCOME10",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12] },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

分析与客户

某一日期范围内的销售汇总 (?from=YYYY-MM-DD&to=YYYY-MM-DD, 默认为最近 30 天）：按状态/类型统计的订单数、总收入与已付收入、平均订单金额，以及热销商品。

{
  "range": { "from": "2026-06-02", "to": "2026-07-02" },
  "orders": { "total": 214, "paid": 198, "by_status": {...}, "by_type": {...} },
  "revenue": { "gross": 8420.50, "paid": 7990.00, "avg_order_value": 39.35 },
  "top_items": [ { "item_id": 88, "name": "Margherita", "quantity": 143 } ]
}

餐厅的客户列表（CRM），分页。使用以下方式筛选： ?search=.

管理司机 撰写

司机归属于您，并（可选地）归属于某一家餐厅。创建或轮换司机会返回一个原始的 司机令牌，仅一次 — 将其交给司机端应用；他们用它进行认证（见下文）。

curl -X POST https://www.menubarcode.com/api/v1/drivers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Alex","phone":"+15550001111","restaurant_id":12}'

# → { "id": 7, "name": "Alex", ..., "token": "RAW_DRIVER_TOKEN_SHOWN_ONCE" }

使旧令牌失效并返回一个新令牌。

分配并追踪一次配送

配送订单，可按以下方式筛选： ?delivery_status= 和 ?driver_id=.

指派骑手 {"driver_id": 7}. 设置 delivery_status=assigned 并触发 order.driver_assigned.

覆盖配送阶段： pending | assigned | picked_up | out_for_delivery | delivered | failed.

司机端应用 API

司机端应用通过以下方式认证： 司机令牌 （而非上文签发的所有者令牌）。基础路径 https://www.menubarcode.com/api/v1/driver. 每个响应都限定于那一位司机。

Authorization: Bearer RAW_DRIVER_TOKEN

已认证司机的个人资料。

分配给该司机的订单。添加 ?active=1 以隐藏已送达/失败的订单。

推进配送： {"delivery_status":"out_for_delivery"} 然后 "delivered" 或 "picked_up" / "failed", 可选 note). 触发与所有者端点相同的 Webhooks。

推送实时位置： {"lat":25.2048,"lng":55.2708}. 在配送途中展示在客户的追踪视图中。

客户账户

A 独立客户端应用 使用按客户令牌（Sanctum 风格：多设备，可单独吊销）来认证其自身用户。不涉及任何所有者令牌。客户按每家餐厅限定范围，因此认证位于 /restaurants/{id}/customer/…. 先使用公开端点浏览菜单：

按分类分组的有效菜单（不含售罄商品）。无需认证。

注册 / 登录

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/login \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","password":"secret123","device":"iPhone 15"}'

# → { "token": "RAW_CUSTOMER_TOKEN", "customer": { "id": 42, "name": "Sam", ... } }

无密码（SMS OTP）

为某个手机号请求验证码，然后进行验证。验证会查找或创建该客户并返回一个令牌。认证端点受速率限制（登录/注册 10 次/分钟，OTP 请求 6 次/分钟）。

客户端应用 API

使用客户令牌进行认证。基础路径 https://www.menubarcode.com/api/v1/customer. 一切都限定于已认证的客户——订单请求体绝不可能伪造另一位客户的 id。

Authorization: Bearer RAW_CUSTOMER_TOKEN

个人资料读取/更新（姓名、邮箱、电话、生日、同意项）。

以该客户身份下单（商品结构与商家端创建端点相同；身份取自令牌）。返回订单，包含其 track_token.

该客户自己的订单历史，分页。

已保存的配送地址（第一个成为默认；支持 lat/lng).

吊销用于该请求的令牌（仅限该设备）。

订单追踪 公开

无需认证——访问由订单不可猜测的以下值把关： track_token （在订单创建时返回）。这为一个 客户端应用 实时追踪界面提供支持。

{
  "id": 5501, "status": "preparing", "delivery_status": "out_for_delivery",
  "is_paid": true, "total": 42.00,
  "timeline": { "preparing_at": "...", "out_for_delivery_at": "..." },
  "items": [ { "name": "Margherita", "quantity": 2 } ],
  "driver": { "name": "Alex", "lat": 25.2, "lng": 55.27, "location_updated_at": "..." }
}

司机信息块（含实时坐标）仅在订单被取货/配送途中时才会出现。

员工登录

A 员工应用 （POS / KDS / 服务员）使用按员工令牌来认证每位员工。两种方式与仪表盘一致：邮箱 + 密码，或快速的数字 PIN 用于共享的厨房平板。员工按每家餐厅限定范围。

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/staff/pin \
  -H "Content-Type: application/json" -d '{"pin":"4321","device":"Kitchen iPad"}'

# → { "token": "RAW_STAFF_TOKEN",
#     "staff": { "id": 3, "role": "kitchen", "permissions": ["kds"] } }

响应会列出该员工的有效 权限 — 以下的一个子集： orders, menu_edit, coupons, analytics, kds, customers 由其角色（经理 / 收银 / 厨房 / 服务员）以及任何按员工的覆盖设置推导得出。端点受权限把关 (403 否则）。

员工端应用 API

使用员工令牌进行认证。基础路径 https://www.menubarcode.com/api/v1/staff. 所有操作都限定于该员工所属的餐厅。

Authorization: Bearer RAW_STAFF_TOKEN

包含角色和权限列表的个人资料。

列出订单并更新厨房状态。需要 orders 权限。

按订单分组的实时厨房单据，筛选至该员工的工位（或 ?station_id=). 只显示仍处于以下状态的商品： queued|preparing|ready.

推进 (queued → preparing → ready → served) 或后退一个 KDS 状态。父订单的状态会自动重新同步。

在店内直接编辑菜单（经理）。载荷与商家端菜单端点相同，限定于该员工所属的餐厅。

该员工所属餐厅的销售汇总（结构与商家端分析端点相同； ?from=&to=).

吊销此设备的令牌。

Webhooks — 设置

从仪表盘中注册端点，位置在 API 令牌和 Webhook. 选择每个端点接收哪些事件。保存后您会获得一个按端点的 签名密钥; 使用 测试 按钮发送一个 ping. 暂停某个端点即可停止投递，且不会丢失其密钥。

您的端点应返回一个 2xx 状态并尽快返回（10 秒内）。任何其他状态——或超时——都会被视为失败并进行重试。

端点也可以被管理 以编程方式 （用于 Zapier/Make REST-Hooks），使用一个 webhooks:write 令牌：

GET    /api/v1/webhook-endpoints            # list your endpoints
POST   /api/v1/webhook-endpoints            # {"url":"https://…","events":["order.created"]} → 201 {id, secret, …}
DELETE /api/v1/webhook-endpoints/{id}       # unsubscribe → 204

该 secret 会被返回 仅 在创建时——请妥善保存以验证签名。 url 必须是公开的 HTTPS 端点（有 SSRF 防护）； events 必须来自下方列表（或 *).

Webhook 事件

在您的端点宕机期间某次投递失败了？请使用 重新投递 在仪表盘的“最近投递”日志中的任意行上，以一个全新的以下值将其重新排队： webhook-id.

Webhook 载荷

每次投递都是一个 POST 带有以下 JSON 封装和这些请求头：

POST /your-endpoint HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4e5f6g7h8i9j0k1l2
webhook-timestamp: 1751472240
webhook-signature: v1,K5f...base64...==
X-Webhook-Event: order.created          (legacy)
X-Webhook-Signature: 9a3f...hex...      (legacy, HMAC of body only)

{
  "id": "msg_a1b2c3d4e5f6g7h8i9j0k1l2",
  "event": "order.created",
  "created_at": "2026-07-02T18:04:00+00:00",
  "data": { "order_id": 5501, "total": "42.00" }
}

该 id 每次投递都是唯一的。由于重试会复用相同的 id, 请用它让您的处理程序具备幂等性。

验证签名

该 webhook-signature 头是一个 HMAC-SHA256、经 base64 编码的值，计算依据为 {id}.{timestamp}.{body} 使用您端点的签名密钥。将 id 和时间戳绑定到签名中，正是使被截获的请求能抵御重放攻击的关键。请拒绝任何满足以下条件的请求：其 webhook-timestamp 已超过约 5 分钟。

PHP

$secret  = 'whsec_from_dashboard';
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$sent    = explode(',', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])[1] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

// verified — process $body
http_response_code(200);

Node.js

const crypto = require('crypto');

function verify(req, secret) {
  const id  = req.headers['webhook-id'];
  const ts  = req.headers['webhook-timestamp'];
  const sig = (req.headers['webhook-signature'] || '').split(',')[1];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${ts}.${req.rawBody}`)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig || ''));
}

重试与投递日志

投递是异步的，并在失败时以指数退避加抖动进行重试：大致为 1m → 5m → 15m → 1h （总计最多 5 次尝试）。每次尝试——无论成功或失败——都会连同其 HTTP 状态、尝试次数和响应片段记录在您仪表盘的投递日志中。

MCP 服务器

五个 Model Context Protocol 服务器将 AI 智能体（ChatGPT、Claude、Cursor）连接到平台——请选择与您受众匹配的那一个。它们都通过 HTTP 使用 JSON-RPC 2.0 通信并协商协议版本 2024-11-05 / 2025-03-26 / 2025-06-18.

快速开始：跳转至 Admin, Catalog, Customer, 或 Dev. 店面服务器与后台的连接模式相同，只是使用一个 X-Storefront-Token 头，而非 Bearer 令牌。

MCP 服务器（后台）

一个兼容 MCP 的 AI 客户端（Claude、ChatGPT、Cursor）可以使用相同的 API 令牌，通过自然语言来操作您的餐厅。将它指向：

使用以下方式认证： Authorization: Bearer YOUR_TOKEN. 每个工具都会声明它所需的细粒度能力 (resource:action); 一个旧版的 read 令牌涵盖每一个 :read 工具，而 write 涵盖一切。所有调用都限定于您的餐厅范围内并受速率限制。您不具备相应能力的工具会被从以下列表中隐藏： tools/list.

连接（Claude Code）

claude mcp add --transport http platform-admin https://www.menubarcode.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

列出工具

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

调用一个工具 (例如：添加一个菜单商品)

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"add_menu_item",
                 "arguments":{"restaurant_id":12,"name":"Latte","price":4.5}}}'

工具

Catalog MCP（发现餐厅）

一个公开的、只读的 MCP 服务器，让 AI 智能体能在整个平台范围内发现餐厅和菜品，然后深链进入某个特定店铺去下单。无需认证，受速率限制。

连接（Claude Code）

claude mcp add --transport http platform-catalog https://www.menubarcode.com/mcp/catalog

只有活跃且公开上架的店铺才会出现；店主可在其店铺设置中选择退出。绝不会返回任何店主联系方式。要下单，请使用该店铺的 店面 MCP 并配合一个按店铺的智能体令牌。

客户账户 MCP

让食客的 AI 助手读取、追踪并再次下单 他们自己的 订单。通过来自现有 OTP 登录的按客户令牌进行认证；客户身份仅来自令牌——绝不会将手机号或客户 id 作为参数接受。

获取令牌（OTP 流程）

# 1) request a one-time code (sent to the customer's phone)
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/request \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567"}'

# 2) verify the code → returns a customer bearer token
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/verify \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567","code":"123456"}'

连接（Claude Code）

claude mcp add --transport http my-orders https://www.menubarcode.com/mcp/customer \
  --header "Authorization: Bearer CUSTOMER_TOKEN"

curl -X POST https://www.menubarcode.com/mcp/customer \
  -H "Authorization: Bearer CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"my_orders","arguments":{"limit":5}}}'

连接您的 AI 编辑器

正在用 Claude Code、Cursor 或 VS Code 构建主题或集成？请将它指向公开的 开发 MCP 服务器 ——您的 AI 工具将获得实时的平台文档、生成的 Liquid 白名单以及服务端主题校验。无需令牌。

Claude Code

claude mcp add --transport http platform-dev https://www.menubarcode.com/mcp/dev

Cursor — .cursor/mcp.json

{ "mcpServers": { "platform-dev": { "url": "https://www.menubarcode.com/mcp/dev" } } }

VS Code — .vscode/mcp.json

{ "servers": { "platform-dev": { "type": "http", "url": "https://www.menubarcode.com/mcp/dev" } } }

工具 learn_platform (从这里开始), search_docs / fetch_full_doc, get_liquid_reference, get_section_schema, validate_theme, list_webhook_events. 推荐的智能体工作流：学习 → 构建 → 验证 → 交付。

更新日志

返回 Menubarcode