快速开始

快速入门

登录开发者控制台，创建您自己的密钥，并验证 API 请求和已签名的 webhook。

使用开发者控制台管理 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.
You are building an integration with the Maple Developer API in this repository.
Read these first:

The docs index: https://docs.maple.inc/llms.txt

The quickstart: https://docs.maple.inc/developer-api/quickstart

The OpenAPI spec, which is the source of truth for every endpoint and field: https://docs.maple.inc/openapi/developer-api.json

Rules:

Use the sandbox only. The base URL is https://api.staging.maple.inc/v1, and the key is in the MAPLE_KEY environment variable (it starts with mpk_test_). Never print, log, or commit the key, and ask me before doing anything against production.

Send the key as Authorization: Bearer $MAPLE_KEY. Start by calling GET /me to confirm the app, the environment, and the scopes the key has, and plan around those scopes.

Keep the x-request-id header from every response. It identifies the request in the developer console and in feedback.

Branch on an error’s _tag and code, never its message. Follow Retry-After on a 429.

Verify the HMAC signature on every webhook before acting on it.

When the API gets in your way (a bug, a capability you need that is missing, docs that disagree with what the API does, or an error that does not tell you what to change), report it with POST /v1/feedback, citing the x-request-id values involved, then carry on with the best workaround you have. See https://docs.maple.inc/developer-api/concepts/feedback for the fields.
Start by reading the docs above, calling GET /me, and telling me what the key can do and which guide fits what we are building.

登录并选择您的应用
按邀请指引，使用受邀邮箱登录，然后打开 Developers。选择正确的组织和已批准的应用。您无需创建或选择餐厅。
继续之前，请确认 Sandbox 或 Production 标识以及 API 基础 URL。每个控制台只管理各自的部署环境。切换环境时，请使用对应的邀请或控制台 URL；不要假设会话或数据是共享的。
如果没有显示任何应用，请联系 Maple 批准该应用，或将其关联到所选组织。仅有员工访问权限并不会让应用出现在开发者控制台中。
创建并保存密钥
在 Overview & keys 中选择 Create key，为其命名，并只选择您的客户端所需且已获批准的权限范围（scope）。请妥善保存完整密钥：它只显示一次，关闭对话框后无法再次获取。
在您自己的客户端环境中设置 MAPLE_KEY。示例都使用这个变量；请勿把密钥粘贴到文档、源代码管理、截图或请求历史字段中。
设置沙盒控制台显示的公开基础 URL:
Terminal window
```
export MAPLE_BASE="https://api.staging.maple.inc/v1"
```
已暂停或已吊销的应用无法使用其密钥进行身份验证。您仍可以在控制台中查看并吊销密钥。
验证您的身份
运行 Getting started 中复制的 /me 命令，或使用：
Terminal window
```
curl --include "$MAPLE_BASE/me" \
  -H "Authorization: Bearer $MAPLE_KEY"
```
```
{
  "object": "developer_app",
  "id": "dap_...",
  "name": "Your Integration",
  "environment": "test",
  "scopes": ["locations:read", "webhooks:read", "webhooks:write"]
}
```
确认应用、环境和实际生效的权限范围。保留 x-request-id 响应头，以便在 Requests 中找到这次调用。密钥的权限永远不会超过应用当前获批的权限上限。
查看您的门店
Granted locations 显示为此应用配置的授权。要通过 API 读取门店，请使用带有 locations:read 的密钥：
Terminal window
```
curl --include "$MAPLE_BASE/locations" \
  -H "Authorization: Bearer $MAPLE_KEY"
```
列表为空并不意味着需要在门户中创建餐厅。请联系 Maple，由其提供测试门店和您的集成所需的授权。
授权与订单接收方连接是两回事。对于订单/POS 集成，请按照接收并处理订单连接已授权的门店。对于预订，请阅读预订资料与预订指南；不要仅为了测试预订而创建订单接收方连接。
注册并测试 webhook
打开 Webhooks → Endpoints，选择 Add endpoint，输入您可控的公开 HTTPS URL，并选择受支持的事件类型。您的应用需要 webhooks:read 才能查看此区域，需要 webhooks:write 才能更改端点或发送测试。
保存一次性签名密钥，并在您的接收端实现签名验证。创建端点不会自动发送测试。
选择 Send test。“已送达”表示接收端返回了 2xx；这并不能证明您的处理程序已验证签名。失败或被跳过的测试不算成功。一次测试只有一次尝试，该操作不会安排自动重试。
查找请求和投递记录
在 Requests 中搜索您 API 调用的 x-request-id。您无需访问内部日志，即可查看其状态和安全的错误摘要。历史记录涵盖使用您应用的密钥或令牌发出的请求（包括已吊销的），保留 7 天；没有可识别凭据的请求不会被记录。历史记录服务不可用不等同于历史记录为空且成功。
在 Webhooks → Deliveries 中，查看已签名测试的结果、尝试次数、HTTP 状态和时间戳。历史记录是按事件/端点汇总的，不是逐次尝试的时间线。URL 和启用状态反映的是端点当前的配置，而不是过去某次请求的目的地。
对于可重放的业务事件，Review event 会预览事件级重试。确认后会重试符合条件的目的地；已成功的组合和已停用的目的地会被跳过。仅测试的记录提供 Send another test，而不是重放不存在的事件记录条目。关于限制和结果不确定的情况，请参阅Webhooks。
Getting started 中的 Check recent activity 会按需读取最近的 /me 调用和已送达测试的元数据。它只是设置提示，不能证明您当前的密钥、当前的端点配置或完整的集成已通过验证。
完成您的业务流程并验证吊销
按照您已获批准的集成对应的指南，在隔离的测试门店上执行一次真实操作，例如：查询可用时段 → 保留 → 创建 → 修改/取消预订。接收由此产生的业务事件，并找到其诊断信息。仅有 /me 和合成测试不能验证业务集成。
当临时验收密钥不再需要时，在控制台中选择 Revoke 并确认。使用该密钥再次发送 /me 请求，并确认身份验证失败。请勿吊销仍被其他客户端使用的密钥。

遇到问题时

您看到的情况	需要检查的内容
没有已批准的应用	受邀邮箱、所选组织，以及 Maple 对应用的归属/审批情况
没有授权或门店列表为空	按环境划分的门店授权，以及密钥上的 `locations:read`
没有最近的请求	您的响应/请求 ID、筛选条件、7 天保留期，以及您是否使用了此应用和此环境的密钥进行调用
历史记录不可用	稍后重试读取历史记录；密钥和 webhook 管理是独立的
端点已停用	重新启用之前，先查看其配置和失败历史
应用已暂停	联系 Maple；创建另一个密钥无法绕过应用状态
环境错误	确保控制台、API 基础 URL 和凭据一致；沙盒不会激活生产环境