Skip to main content
Maple 运行两个完全隔离的环境，各自有独立的基础 URL 和凭据： 请在 Maple 为您已获批准的应用准备的沙盒中开发和测试。受邀成员通过开发者控制台创建自己的沙盒密钥。应用审批、门店授权和功能配置仍由 Maple 管理。 每个控制台只读取和修改其自身部署中的数据。请使用对应的控制台/邀请 URL，按需登录，并查看其环境标识和 API 基础 URL。不要假设存在跨部署的会话、共享的应用配置，或自动创建沙盒。 两个环境不共享凭据或运行数据：沙盒中的连接、订阅或订单，并不是生产环境中的资源。
API 约定和签名格式是共用的，但每个部署都需要各自获批的应用、凭据、授权、端点和功能配置。更改基础 URL 并不等于获得生产批准。

​
为什么这很重要

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

​
在代码中区分环境

沙盒和生产是位于不同主机上的独立部署，因此请求或 webhook 属于哪个环境，由其主机和凭据决定，您无需从载荷中推断。如果您想明确获取：
  • GET /v1/me 会返回凭据的 environment（test 或 live）。
  • 订单资源带有 livemode：在生产环境中为 true，在沙盒中为 false。
请为每个环境使用单独的 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。
  • 您会根据信封中的 id 对投递去重（投递保证至少一次）。
  • 您会快速返回 2xx，并以异步方式处理较慢的工作。
  • 决策调用在遇到暂时性错误时可安全重试（它们是重放安全的）。
  • 您已妥善保存生产环境的签名密钥（mwhsec_…），它只显示一次。