管理配送区域

配送区域定义了门店的配送范围。每个区域是一个 GeoJSON 多边形，带有配送费和可选的下单限制（最低订单金额、最大距离、优先级）。所有配送区域端点都要求与该门店有有效连接 — 只有担任该门店订单接收方的应用才能管理其区域。

权限范围（Scopes）

• delivery_zones:read — 列出区域、获取单个区域以及检查覆盖范围。
• delivery_zones:write — 创建、更新和删除区域。

创建区域

区域名称在每个门店内必须唯一。polygon 是由 [longitude, latitude] 环组成的 GeoJSON Polygon — 第一个环必须闭合（首尾点相同）。

curl -X POST $MAPLE_BASE/locations/{locationId}/delivery_zones \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown",
    "polygon": {
      "type": "Polygon",
      "coordinates": [
        [
          [-74.02, 40.70],
          [-73.99, 40.70],
          [-73.99, 40.73],
          [-74.02, 40.73],
          [-74.02, 40.70]
        ]
      ]
    },
    "delivery_fee_cents": 450,
    "priority": 0
  }'

delivery_fee_cents 默认为 0，is_active 默认为 true，priority 默认为 0，zone_type 默认为 polygon。响应是创建出的 delivery_zone 对象；请使用其 id 调用区域端点。

覆盖范围检查始终以 polygon 为准。zone_type: 'circle' 和 radius_miles 仅是描述性元数据 — 对于圆形区域，请提交一个近似该圆的多边形。

列出区域

curl $MAPLE_BASE/locations/{locationId}/delivery_zones \
  -H "Authorization: Bearer $MAPLE_KEY"

返回 { "object": "list", "data": [...] }，其中仅包含启用的区域。

更新区域

PATCH 只更改您发送的字段：

curl -X PATCH $MAPLE_BASE/locations/{locationId}/delivery_zones/{zoneId} \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_fee_cents": 550 }'

删除区域

删除操作会停用该区域（它将从列表结果和覆盖范围检查中消失）：

curl -X DELETE $MAPLE_BASE/locations/{locationId}/delivery_zones/{zoneId} \
  -H "Authorization: Bearer $MAPLE_KEY"

检查某个坐标是否可配送

在报价配送之前，请对照门店的区域检查顾客的坐标：

curl -X POST $MAPLE_BASE/locations/{locationId}/delivery_zones/check \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "latitude": 40.7128, "longitude": -74.006 }'

响应是一个 delivery_zone_check：in_zone 表示该门店是否配送到该处；为 true 时，zone 携带匹配的区域，delivery_fee_cents 为其费用。为 false 时，两者均为 null。

对于属于其他门店的区域，区域的 get/update/delete 会返回 404 — 合作伙伴只能操作路径中所指门店所拥有的区域。