> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理配送区域

> 创建、更新和列出已连接门店的配送区域，并检查某个坐标是否可配送。

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

## 权限范围（Scopes）

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

## 创建区域

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

```bash theme={null}
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` 仅是描述性元数据 — 对于圆形区域，请提交一个近似该圆的多边形。

## 列出区域

```bash theme={null}
curl $MAPLE_BASE/locations/{locationId}/delivery_zones \
  -H "Authorization: Bearer $MAPLE_KEY"
```

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

## 更新区域

`PATCH` 只更改您发送的字段：

```bash theme={null}
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 }'
```

## 删除区域

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

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

## 检查某个坐标是否可配送

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

```bash theme={null}
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` — 合作伙伴只能操作路径中所指门店所拥有的区域。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.