核心概念
环境与测试模式
沙盒与生产环境各自独立的部署、凭据和访问审批。
Maple 运行两个完全隔离的环境，各自有独立的基础 URL 和凭据：
| 环境 | 控制台（开发者控制台） | 基础 URL | 凭据 |
|---|---|---|---|
| 沙盒 | https://app.staging.maple.inc |
https://api.staging.maple.inc/v1 |
mpk_test_… |
| 生产 | https://app.maple.inc |
https://api.maple.inc/v1 |
mpk_live_… |
请在 Maple 为您已获批准的应用准备的沙盒中开发和测试。受邀成员通过开发者控制台创建自己的沙盒密钥。应用审批、门店授权和功能配置仍由 Maple 管理。
每个控制台只读取和修改其自身部署中的数据。请使用对应的控制台/邀请 URL，按需登录，并查看其环境标识和 API 基础 URL。不要假设存在跨部署的会话、共享的应用配置，或自动创建沙盒。
两个环境不共享凭据或运行数据：沙盒中的连接、订阅或订单，并不是生产环境中的资源。
为什么这很重要
请只使用 Maple 为您的集成准备的隔离测试门店和受支持的工作流。在申请生产批准之前，先在其中验证完整的业务流程、签名处理和诊断；成功收到一次合成 webhook 并不等于通过认证。
flowchart LR
subgraph Sandbox [Sandbox · api.staging.maple.inc]
SK[mpk_test_ key] --> SD[(sandbox data)]
end
subgraph Production [Production · api.maple.inc]
LK[mpk_live_ key] --> LD[(live data)]
end
在代码中区分环境
沙盒和生产是位于不同主机上的独立部署，因此请求或 webhook 属于哪个环境，由其主机和凭据决定，您无需从载荷中推断。如果您想明确获取：
GET /v1/me会返回凭据的environment（test或live）。- 订单资源带有
livemode：在生产环境中为true，在沙盒中为false。
先测试的工作流程
在沙盒中构建
将您的客户端指向
https://api.staging.maple.inc/v1，并使用您的mpk_test_…密钥。连接 Maple 授予您的沙盒门店，订阅 webhook，并跑通完整的订单流程。验证您的 webhook 处理程序
POST /v1/webhook_subscriptions/{id}/test会投递一个已签名的webhook.test事件，让您在任何真实订单出现之前，就能确认签名验证和您的2xx响应。获得批准并正式上线
Maple 会单独批准生产访问，并准备应用和门店授权。请在生产控制台中创建权限范围合适的
mpk_live_…密钥，然后使用https://api.maple.inc/v1。注册生产 webhook，并完成您的集成所需的设置，包括 POS/订单集成的订单接收方连接。不要假设沙盒的授权、标志或订阅会沿用到生产环境。