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

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

<Info>
  API 约定和签名格式是共用的，但每个部署都需要各自获批的应用、凭据、授权、端点和功能配置。更改基础 URL 并不等于获得生产批准。
</Info>

## 为什么这很重要

请只使用 Maple 为您的集成准备的隔离测试门店和受支持的工作流。在申请生产批准之前，先在其中验证完整的业务流程、签名处理和诊断；成功收到一次合成 webhook 并不等于通过认证。

```mermaid theme={null}
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。投递的事件不带环境字段，接收事件的端点本身就说明了它来自哪个环境。
</Warning>

## 先测试的工作流程

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

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

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

## 上线检查清单

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.