快速开始
Maple 如何运作
每个集成背后的对象与关系：应用、门店、连接，以及您与 Maple 之间的职责划分。
在编写代码之前，先在脑中建立完整的模型会很有帮助。对象只有寥寥几个，并且按单一方向相互衔接。
对象
Developer app
您的身份
您已获批准的集成，由 Maple 明确分配给某个开发者组织。受邀的组织成员通过开发者控制台创建密钥。凭证、授权和订阅都以环境为范围；沙盒和生产是相互独立的部署。应用审批和权限范围上限仍由 Maple 管理。
Location
一家餐厅
一家餐厅，也是 Developer API 操作的基本单位（ID 为 str_…）。商户会向您的应用授权某个门店；该授权让您可以读取它。门店有 status（active、inactive、paused），您应予以遵守。门店隶属于商户和组织，见组织、商户与门店。
Connection
您是订单接收方
连接到已授权的门店，会让您的应用成为该门店的订单接收方。只有建立连接之后，订单才会路由给您。每个环境下，一个门店只能连接到一个应用。
Order
顾客下的订单
顾客在已连接门店下的订单，包含商品明细、合计（由 Maple 计算）和支付对象。您通过决定调用来推动它走完生命周期。
Menu
顾客据以点餐的内容
门店的商品目录，包括分类、菜品、规格、加料选项，以及税费定义，以一份以您自己的外部 ID 为键的 JSON 文档发布。
Webhook subscription
您如何得知事件
一个 HTTPS 端点加上您需要的事件类型。Maple 会对事件签名并投递给它，并保留一份您可以从中重放的事件记录。
它们如何连接
flowchart LR App[Your developer app] -- granted --> Loc[Location] App -- connection --> Loc Loc -- emits --> Order[Order] App -- publishes --> Menu[Menu] Order -- order.notification --> Hook[Your webhook endpoint] Hook -- accept / deny / ready / complete --> Order
商户向您授权一个门店 → 您连接到它 → 该门店的订单被推送到您的 webhook → 您对每笔订单作出决定。与此同时，您发布这些订单所依据的菜单。
谁负责什么
这是最需要理解的一点，也是大多数餐厅集成最容易出错的地方。Maple 负责带有风险的部分：
| Maple 负责 | 您负责 |
|---|---|
| 顾客支付生命周期（由 Stripe 支持的支付链接） | 接收订单并作出决定 |
| 所有面向顾客的合计、税费和附加费计算 | 把订单状态反馈回来（accept、ready、complete） |
| 银行卡数据和 PCI 合规范围 | 发布准确的菜单 |
| 投递、重试和签名 webhook | 验证签名并对事件去重 |
您永远不需要计算价格、接触银行卡或构建支付流程。Maple 交给您的订单，totals 已是最终值，payment 对象您可以读取但无需管理。
订单流程全貌
- 顾客在已连接的门店下单。
- （可选） Maple 发送
order.validation_requested，并等待您确认订单可以履行。见验证订单。 - Maple 发送包含完整订单的
order.notification。 - 您接受或拒绝订单。
- 您回报进度，先 ready，再 complete；如果接单后不得不取消，则 cancel。
- 如果顾客或门店取消，您会收到
order.cancelled。
每个决定调用都可安全重放，因此重试不会有影响。完整流程见接收并处理订单。
环境
Maple 运行两个相互隔离的环境，各有自己的基础 URL：
- 沙盒：
https://api.staging.maple.inc/v1，使用您的mpk_test_…密钥。用于开发和测试。 - 生产：
https://api.maple.inc/v1，使用您的mpk_live_…密钥。处理真实流量。
您在沙盒中针对隔离的数据构建并验证所有内容，待集成获批后，再把同样的代码指向生产。两个环境永远看不到对方的数据。更多内容见环境与测试模式。