# 发货与履约

> 用 Open API 在应用里给已支付的 Shoplazza 订单发货：创建履约、完成或取消履约，并回写物流单号。

订单支付后就可以发货：创建履约、标记完成，或取消履约。

## 适用场景

对接仓储或物流商，并把运单信息回写到 Shoplazza。

## 前置需求

- 一个已跑通 OAuth 与 token 存储的公开应用——先完成 [开发独立应用](/docs/app/getting-started/create-public-app/develop-app)。下面的每个请求都带 `Access-Token: {token}` 头，使用你为每个店铺保存的 token。
- OAuth 时已授予订单相关的 access scope。
- 订单已支付——可由 `orders/paid` webhook 触发（见 [用 Webhook 监听订单事件](/docs/app/use-cases/orders-and-fulfillment/listen-for-order-events)）。

### 创建履约

对订单的所有行项一次性发货即整单发货。`ship_quantity: 0` 表示该行剩余数量全部发出。`tracking_number` 与 `tracking_company` 为可选字段。

`POST /openapi/2026-01/orders/{id}/fulfillments`

请求体：

```json5
{
  "fulfillment": {
    "line_items": [
      { "id": "cb43fba8-2e19-4add-aa70-5d0a81c6f746", "ship_quantity": 0 } // 0 表示该行剩余数量全部发出
    ],
    "tracking_number": "1Z999AA10123456784", // 可选
    "tracking_company": "UPS" // 可选
  }
}
```

响应（节选，履约在 `data.data.fulfillment` 下）：

```json
{
  "code": "Success",
  "data": {
    "fulfillment": {
      "id": "92db3f11-39ca-4253-8b26-6e2408e5ea21",
      "order_id": "2386979206088637521556",
      "status": "shipped",
      "created_at": "2026-07-02T03:05:00Z",
      "updated_at": "2026-07-02T03:05:00Z",
      "line_items": [
        {
          "id": "cb43fba8-2e19-4add-aa70-5d0a81c6f746",
          "product_title": "Hoodie",
          "variant_id": "fbb31d0c-0809-4394-87df-b5be865b30a7",
          "quantity": 1,
          "price": "83.22",
          "sku": "A002020",
          "fulfillment_status": "shipped",
          "ship_quantity": 1
        }
      ]
    }
  }
}
```

完整请求体（部分发货、运单字段）见 [创建履约](/api/fulfillment-create)。

### 完成或取消履约

两者都需要创建时返回的 `fulfillment_id`（或从 [履约列表](/api/fulfillments) 获取）。

`POST /openapi/2026-01/orders/{id}/fulfillments/{fulfillment_id}/complete`

响应（节选，履约结构不变，`status` 变为 `finished`）：

```json
{
  "code": "Success",
  "data": {
    "fulfillment": {
      "id": "92db3f11-39ca-4253-8b26-6e2408e5ea21",
      "order_id": "2386979206088637521556",
      "status": "finished",
      "updated_at": "2026-07-02T03:15:18Z"
    }
  }
}
```

完整字段见 [完成履约](/api/fulfillment-complete)。

`POST /openapi/2026-01/orders/{id}/fulfillments/{fulfillment_id}/cancel`

返回同一个履约，`status` 变为对应的取消态。见 [取消履约](/api/fulfillment-cancel)。

## 下一步

- [退款与售后](/docs/app/use-cases/orders-and-fulfillment/refunds-and-post-sales)
- [用 Webhook 监听订单事件](/docs/app/use-cases/orders-and-fulfillment/listen-for-order-events)