开发应用

应用通过受限、可吊销的 OAuth 访问来扩展餐厅的账户。您的代码运行在您自己的服务器上；平台则持有注册表、安装台账和计费通道。本指南将带您从零打造一个已安装、按量计费的应用。

1. 注册您的应用

在以下位置创建一个应用：合作伙伴仪表盘: 名称、分类、您所需的范围、一个可选的 webhook URL，以及您的计费模式。提交后会生成一个 OAuth 客户端（client id + secret），并将应用置于审核中。一旦管理员批准，它就会出现在应用商店中并可被安装。

2. 完成安装

餐厅店主会从您应用的应用商店详情页安装它，授予您所请求的范围。安装会创建一个 AppInstallation 并（对付费应用而言）通过其钱包收取首个周期的费用。

3. 调用 API

为安装该应用的账户换取一个 OAuth 令牌，然后调用 REST API 用它上报用量、接收 webhooks，或在其仪表盘中嵌入一个页面——下文将逐一介绍。

OAuth 与令牌

应用使用 OAuth 2.0（Laravel Passport）进行认证。您的客户端凭据来自合作伙伴仪表盘。使用标准的授权码流程；所授予的令牌会携带店主在安装时批准的范围。

# Exchange an authorization code for an access token
curl -X POST https://www.menubarcode.comoauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=YOUR_REDIRECT \
  -d code=AUTH_CODE

# Call the API with the returned bearer token
curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

令牌是受限的：一个需要以下范围的调用 orders:read 会失败，除非店主已授予该范围。请只请求最小集合——审核人员会检查这一点。

会话令牌

对于短期的服务端到嵌入页面的调用，请从一个有效的安装记录中生成一个会话令牌。令牌将在以下时间后过期： 60 秒。

GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }

嵌入式应用

如果您的应用声明了一个 embed_url, 平台会在店主仪表盘内的一个 iframe 中托管它，位置在 /apps/{appId}/embed. 将它与一个会话令牌（见上文）配合使用，即可在不进行完整 OAuth 往返的情况下对嵌入页面进行认证。

Webhooks

在您应用的以下位置订阅事件： webhook_url. 投递会被排队、重试，并使用以下方案签名： Standard Webhooks 方案，使用您应用的签名密钥。您的端点必须是公开的 HTTPS URL（不得为私有/回环/元数据主机），并返回 2xx 并尽快返回。

# A delivery your endpoint receives
POST https://your-app.com/webhooks
webhook-id: msg_...
webhook-timestamp: 1710000000
webhook-signature: v1,BASE64_HMAC
Content-Type: application/json

{ "type": "order.paid", "data": { "order_id": 123, ... } }

在信任某个载荷之前，请依据您的密钥验证签名。参见事件列表.

用量计费

按量计费的应用通过上报单位来计量消耗。每次上报都会按您的单价从店主的钱包扣费。请传入一个唯一的 ref 以使上报具备幂等性（使用相同 ref 的重复上报会被忽略）。

curl -X POST https://www.menubarcode.com/api/app/usage \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -d quantity=1 \
  -d ref=unique-key-per-event

字段	类型	备注
`quantity`	数字 > 0	必填——所消耗的单位数
`ref`	字符串 ≤ 120	可选的幂等键

该端点返回 403 如果该令牌不属于任何已注册的应用，或该应用未针对此账户安装。

操作指南

选择一种计费类型

免费 — 安装时不收费。
周期性 — 在每个计费周期（默认 30 天）从店主的钱包收取一笔固定费用。
按用量计费 — 一个按单位计价的价格，随您上报用量而计费。

负责任地请求范围

只请求您应用会用到的范围。在已上线的上架页上更改范围会使应用重新回到审核。参见范围参考.

在卸载时清理

当店主卸载时，平台会吊销该应用的令牌并触发一个 app/uninstalled 事件。收到它时，请停止后台工作并删除该账户的已存储数据。

范围参考

反映自平台的 OAuth 范围注册表。

权限范围	授予
`menu:read`	Read menus, categories and items
`menu:write`	Create and update menu items
`orders:read`	Read orders and their status
`orders:write`	Create and update orders
`analytics:read`	Read scan and sales analytics
`restaurant:read`	Read restaurant profile and settings

Webhook 事件

您目前可以订阅的事件：

事件
`order.created`
`order.status_changed`
`order.paid`
`refund.completed`
`reservation.created`
`reservation.cancelled`
`customer.created`
`shift.opened`
`shift.closed`
`menu.updated`
`entitlement.changed`
`subscription.paused`
`subscription.resumed`
`subscription.renewed`
`subscription.expired`
`subscription.plan_changed`
`subscription.past_due`
`subscription.expiring`
`subscription.trial_ending`
`app.uninstalled`

上架与审核要求

在管理员批准您的应用之前，它必须：

只请求它会用到的范围，且每个都在描述中说明理由。
如果它订阅了事件，则提供一个可用的 webhook 端点（公开 HTTPS）。
声明准确的定价——您详情页上的价格表就是由它生成的。
包含清晰的一句话简介、描述、分类，以及至少一张截图。
妥善处理卸载（吊销访问权限、停止计费、删除账户数据）。

元数据编辑（一句话简介、描述、截图、链接）会立即生效；价格或范围的更改则会重新排入审核。