> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境与测试模式

> 沙盒与生产环境各自独立的部署、凭据和访问审批。

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。不要假设存在跨部署的会话、共享的应用配置，或自动创建沙盒。

两个环境不共享凭据或运行数据：沙盒中的连接、订阅或订单，并不是生产环境中的资源。

> [!NOTE]
>
> 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`。

> [!WARNING]
>
> 请为每个环境使用单独的 webhook 订阅，并将其指向对应的基础 URL。投递的事件不带环境字段，接收事件的端点本身就说明了它来自哪个环境。

## 先测试的工作流程

1. ### 在沙盒中构建

   将您的客户端指向 `https://api.staging.maple.inc/v1`，并使用您的 `mpk_test_…` 密钥。连接 Maple 授予您的沙盒门店，订阅 webhook，并跑通完整的订单流程。

2. ### 验证您的 webhook 处理程序

   `POST /v1/webhook_subscriptions/{id}/test` 会投递一个已签名的 `webhook.test` 事件，让您在任何真实订单出现之前，就能确认签名验证和您的 `2xx` 响应。

3. ### 获得批准并正式上线

   Maple 会单独批准生产访问，并准备应用和门店授权。请在生产控制台中创建权限范围合适的 `mpk_live_…` 密钥，然后使用 `https://api.maple.inc/v1`。注册生产 webhook，并完成您的集成所需的设置，包括 POS/订单集成的订单接收方连接。不要假设沙盒的授权、标志或订阅会沿用到生产环境。

## 上线检查清单

- 您的客户端基础 URL 和凭据指向同一个环境。
- 您的 webhook 处理程序会验证 HMAC 签名，并拒绝错误或过期的签名。请参阅[Webhooks](https://docs.maple.inc/zh/developer-api/concepts/webhooks.md)。
- 您会根据信封中的 `id` 对投递去重（投递保证至少一次）。
- 您会快速返回 `2xx`，并以异步方式处理较慢的工作。
- 决策调用在遇到暂时性错误时可安全重试（它们是[重放安全](https://docs.maple.inc/zh/developer-api/concepts/idempotency.md)的）。
- 您已妥善保存生产环境的签名密钥（`mwhsec_…`），它只显示一次。