Skip to main content
使用开发者控制台管理 Maple 已批准应用的凭据和 webhook。请先在沙盒环境中完成一个受支持的业务流程，再申请生产环境访问权限。

​
开始之前

您需要：一份加入开发者组织的邀请、一个分配给该组织的已批准应用，以及对应环境的控制台：沙盒使用 https://app.staging.maple.inc，生产环境使用 https://app.maple.inc（参阅环境）。Maple 会为您准备沙盒，并授予您的集成所需的门店。创建密钥不会创建沙盒，也不会授予门店访问权限。 如果您没有邀请或已批准的应用，请联系 Maple。公开注册、应用审批、门店授权和生产环境激活都不支持自助完成。

​
从编码助手开始

如果由编码助手（Claude Code、Cursor、Codex 或类似工具）为您构建集成，请在 MAPLE_KEY 中放入沙盒密钥后，把下面的提示词复制给它。它会让助手阅读这些文档和 API 参考，将其限制在沙盒中，并告诉它如何报告 API 中妨碍工作的任何问题。

Set up a coding agent to build against the Maple Developer API in the sandbox.

在 Cursor 中打开
1

登录并选择您的应用

按邀请指引，使用受邀邮箱登录，然后打开 Developers。选择正确的组织和已批准的应用。您无需创建或选择餐厅。继续之前，请确认 Sandbox 或 Production 标识以及 API 基础 URL。每个控制台只管理各自的部署环境。切换环境时，请使用对应的邀请或控制台 URL；不要假设会话或数据是共享的。如果没有显示任何应用，请联系 Maple 批准该应用，或将其关联到所选组织。仅有员工访问权限并不会让应用出现在开发者控制台中。
2

创建并保存密钥

在 Overview & keys 中选择 Create key，为其命名，并只选择您的客户端所需且已获批准的权限范围（scope）。请妥善保存完整密钥：它只显示一次，关闭对话框后无法再次获取。在您自己的客户端环境中设置 MAPLE_KEY。示例都使用这个变量；请勿把密钥粘贴到文档、源代码管理、截图或请求历史字段中。设置沙盒控制台显示的公开基础 URL:
已暂停或已吊销的应用无法使用其密钥进行身份验证。您仍可以在控制台中查看并吊销密钥。
3

验证您的身份

运行 Getting started 中复制的 /me 命令，或使用：
Response
确认应用、环境和实际生效的权限范围。保留 x-request-id 响应头，以便在 Requests 中找到这次调用。密钥的权限永远不会超过应用当前获批的权限上限。
4

查看您的门店

Granted locations 显示为此应用配置的授权。要通过 API 读取门店，请使用带有 locations:read 的密钥：
列表为空并不意味着需要在门户中创建餐厅。请联系 Maple，由其提供测试门店和您的集成所需的授权。授权与订单接收方连接是两回事。对于订单/POS 集成，请按照接收并处理订单连接已授权的门店。对于预订，请阅读预订资料与预订指南；不要仅为了测试预订而创建订单接收方连接。
5

注册并测试 webhook

打开 Webhooks → Endpoints，选择 Add endpoint，输入您可控的公开 HTTPS URL，并选择受支持的事件类型。您的应用需要 webhooks:read 才能查看此区域，需要 webhooks:write 才能更改端点或发送测试。保存一次性签名密钥，并在您的接收端实现签名验证。创建端点不会自动发送测试。选择 Send test。“已送达”表示接收端返回了 2xx；这并不能证明您的处理程序已验证签名。失败或被跳过的测试不算成功。一次测试只有一次尝试，该操作不会安排自动重试。
6

查找请求和投递记录

在 Requests 中搜索您 API 调用的 x-request-id。您无需访问内部日志，即可查看其状态和安全的错误摘要。历史记录涵盖使用您应用的密钥或令牌发出的请求（包括已吊销的），保留 7 天；没有可识别凭据的请求不会被记录。历史记录服务不可用不等同于历史记录为空且成功。在 Webhooks → Deliveries 中，查看已签名测试的结果、尝试次数、HTTP 状态和时间戳。历史记录是按事件/端点汇总的，不是逐次尝试的时间线。URL 和启用状态反映的是端点当前的配置，而不是过去某次请求的目的地。对于可重放的业务事件，Review event 会预览事件级重试。确认后会重试符合条件的目的地；已成功的组合和已停用的目的地会被跳过。仅测试的记录提供 Send another test，而不是重放不存在的事件记录条目。关于限制和结果不确定的情况，请参阅Webhooks。Getting started 中的 Check recent activity 会按需读取最近的 /me 调用和已送达测试的元数据。它只是设置提示，不能证明您当前的密钥、当前的端点配置或完整的集成已通过验证。
7

完成您的业务流程并验证吊销

按照您已获批准的集成对应的指南，在隔离的测试门店上执行一次真实操作，例如：查询可用时段 → 保留 → 创建 → 修改/取消预订。接收由此产生的业务事件，并找到其诊断信息。仅有 /me 和合成测试不能验证业务集成。当临时验收密钥不再需要时，在控制台中选择 Revoke 并确认。使用该密钥再次发送 /me 请求，并确认身份验证失败。请勿吊销仍被其他客户端使用的密钥。

​
遇到问题时

​
继续您的集成

接受预订

读取预订资料、搜索可用时段、保留时段，并创建或修改预订。

接收并处理订单

连接已授权的门店，处理订单通知和订单决定。

发布菜单

为已获批准的订单/POS 集成发布商品目录。

生产环境访问

了解正式上线所需的独立审批、凭据、授权和端点设置。