跳转到内容
Maple

    核心概念

    身份验证

    每个请求都携带 Bearer API 密钥。密钥决定所属环境，并携带您的应用所拥有的权限范围（scope）。

    向 Developer API 发送的每个请求，都要在 Authorization 请求头中携带 Bearer API 密钥：

    Terminal window
    # Sandbox
    curl https://api.staging.maple.inc/v1/me \
      -H "Authorization: Bearer mpk_test_..."

    一个密钥同时回答三个问题：您是哪个应用、属于哪个环境（沙盒或生产），以及拥有哪些权限范围。您可以用 GET /v1/me 验证任何密钥，它会返回的正是这些信息。

    每个环境都有各自的基础 URL：沙盒为 https://api.staging.maple.inc/v1，生产为 https://api.maple.inc/v1。请使用与主机相匹配的密钥。请参阅环境。

    API 密钥

    Maple 会批准您的应用及其权限范围上限。受邀的组织成员可在 Developers → your app → Overview & keys 中创建和吊销密钥。请登录与密钥所属环境对应的控制台（沙盒密钥使用 https://app.staging.maple.inc，生产密钥使用 https://app.maple.inc）；无需选择商户或餐厅。

    密钥 环境 基础 URL
    mpk_test_… 沙盒 https://api.staging.maple.inc/v1
    mpk_live_… 生产 https://api.maple.inc/v1

    每个请求都要把密钥作为 bearer 令牌发送，并使用其所属环境的基础 URL。请把密钥保存在服务器端；切勿将其嵌入客户端应用，也不要提交到源代码管理中。缩小应用的权限范围会立即对其现有密钥生效。

    要更换密钥，请创建新密钥、更新您的客户端、确认其可用，然后明确吊销旧密钥。吊销后，该密钥会立即无法通过身份验证。被暂停或吊销的应用无法使用其任何密钥进行身份验证，但仍可通过控制台进行检查和保护性吊销。

    密钥不会授予门店访问权限、创建沙盒，或批准生产环境使用。应用所有权、权限范围上限、门店授权和生产批准均由 Maple 单独管理。仅有员工权限，并不能访问开发者控制台中未关联的应用。

    请按照快速入门创建密钥，并通过 /v1/me 验证返回的应用和环境。

    权限范围（Scopes）

    访问受权限范围控制，因此您的应用只拥有其所需的权限：

    权限范围 授予的权限
    locations:read 列出并读取已授权的门店
    connections:read / connections:write 读取或管理门店连接
    orders:read / orders:write 读取订单或提交订单决策
    menus:read / menus:write 读取或发布门店的菜单
    delivery_zones:read / delivery_zones:write 读取或管理已连接门店的外送范围，并检查是否可送达
    webhooks:read / webhooks:write 读取或管理 webhook 订阅
    bookings:read 读取已授权门店的预订、资料、可订时段、配置和实时桌位情况
    bookings:write 为客人保留时段，并创建、更改或取消预订
    bookings:manage 代表场所操作：确认、拒绝、安排入座、完成、取消预订或标记预订为未到店，并为散客安排入座
    bookings:configure 发布原生预订配置

    缺少所需权限范围的请求会返回 403，代码为 insufficient_scope。在错误的环境中使用密钥会返回 403，代码为 wrong_environment。请参阅错误。

    OAuth