---
title: "发货流程"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/order-and-fulfillment/fulfillment-service-provider/shipping-workflow'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/order-and-fulfillment/fulfillment-service-provider/shipping-workflow.md'
---
# 发货流程
本文旨在介绍履约应用发货流程。在此之前，将说明履约发货的核心概念及履约单状态流转规则。

---

## 履约发货相关对象关系
履约发货相关的核心概念包括订单、履约单和发货单，如下所示：

* **订单**：客户下单后生成的交易记录，包含所有购买信息，如商品、折扣、运费、客户等。
* **履约单**：根据一个订单中的商品是否需要运输、是否为礼品卡、运费方案以及商品发货地点的不同，在该订单的基础上生成的履约指令。一个订单可能包含多个履约单。
* **发货单**：实际发货时生成的操作记录，包含物流跟踪信息。一个履约单可以分多次发货，可能生成多个发货单。

下图介绍了 SHOPLINE 订单、履约单和履约应用之间的关系。对于一个订单，订单系统会根据该订单的具体情况生成一个或多个履约单。若履约单发货地点为履约应用地点，则由该地点所对应的履约服务商进行发货。

![111.png](https://cdn.myshopline.com/sl/slfs/sl-new/178365392594404/111.png)

---

## 履约单相关状态
### 履约单状态流转图
![222.png](https://cdn.myshopline.com/sl/slfs/sl-new/178365394719457/222.png)

| 状态 | 描述 |
| --- | --- |
| open | 履约单上的商品暂未发货。 |
| on_hold | 履约单暂停发货。 |
| in_progress | 履约单上的部分商品已发货。 |
| closed | 履约单上的商品全部发货。 |

### 履约单请求状态流转
履约应用需要感知履约单请求状态，因为需要通过调用相关接口去同意发货、拒绝发货、拒绝取消发货、同意取消发货。

![333.png](https://cdn.myshopline.com/sl/slfs/sl-new/178365397297915/333.png)

---

## 履约应用发货流程
### 前提条件
#### 订阅必须的 webhook 事件
履约应用需要申请订阅 [发货请求提交](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/submit-request-for-fulfillment.md)、[发货取消请求提交](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/cancellation-request-for-fulfillment-order.md)、[履约单更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/fulfillment-order-update.md) 的 webhook 事件，以接收商家在 SHOPLINE 商家后台提交的发货、取消发货以及履约单更新操作。

#### 创建一个履约服务
履约应用可以使用 [创建履约服务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/fulfillment-service/create-fulfillment-service.md) 的 REST API，创建专属于应用的履约服务。

> **注意**
>
> 一个应用仅能创建一个履约服务。

#### 创建一个履约应用地点
履约应用承担服务商角色后，需调用 [创建履约应用地点](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/fulfillment-service/create-fulfillment-location.md) 接口生成专用地点，方便商家管理商品库存和履约发货。

### 处理发货请求步骤
#### 第一步：接收发货请求提交事件
当商家在 SHOPLINE 商家后台点击 **提交发货** 后，履约应用将收到 [发货请求提交](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/submit-request-for-fulfillment.md) webhook 事件。

事件示例：

```json
{
  "fulfillment_order_merchant_request": {
    "message": "ship this order",
    "notify_customer": true
  },
  "original_fulfillment_order": {
    "id": "21062824515206062204123195_4006282451539732368282",
    "requestStatus": "unsubmitted",
    "status": "open"
  },
  "submitted_fulfillment_order": {
    "id": "21062824515206062204123195_4006282451539732368282",
    "request_status": "submitted",
    "status": "open"
  }
}
```

#### 第二步：获取履约单信息
根据接收到的 [发货请求提交](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/submit-request-for-fulfillment.md) webhook 事件，使用 [获取指定履约单](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/get-specify-fulfillment-order.md) REST API 获取履约信息。

接口示例：
+ GET：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillment_orders/:order_id/:fulfillment_order_id.json`
+ 响应体：

```json
{
  "fulfillment_order": {
    "assigned_location": {
      "address1": "Chestnut Street 92",
      "address2": "Chestnut Street 92",
      "city": "Louisville",
      "country_code": "US",
      "location_id": "5327026538935748524",
      "name": "Apple Api Shipwire",
      "phone": "+1 123-***-7890",
      "province": "Kentucky",
      "zip": "40202"
    },
    "assigned_location_id": "5327026538935748524",
    "destination": {
      "address1": "Chestnut Street 92",
      "address2": "Chestnut Street 92",
      "city": "Louisville",
      "company": "Apple inc",
      "country": "United States",
      "email": "*********@example.com",
      "first_name": "T*****",
      "last_name": "Norman",
      "phone": "+1 123-***-7890",
      "province": "Kentucky",
      "zip": "40202"
    },
    "id": "4005740193290131085320",
    "line_items": [
      {
        "fulfillable_quantity": 1,
        "fulfillment_order_id": "4005740193290131085320",
        "id": "1039283",
        "line_item_id": "518995019",
        "quantity": 1,
        "shop_id": "1644828244663",
        "variant_id": "18055128824718541486811487"
      }
    ],
    "order_id": "21057401932826316666967110",
    "request_status": "submitted",
    "shop_id": "1644828244663",
    "status": "open",
    "supported_actions": [
      "create_fulfillment"
    ]
  }
}
```

#### 第三步：接受或拒绝发货请求
履约应用根据履约单中的配送目的地 `destination`、商品行信息 `line_items`、数量 `quantity` 等条件确定接受或拒绝本次请求。

履约应用通过 [接受发货请求](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/fulfillment-app-accepts-request-to-ship.md) REST API 接受发货请求。

接口示例：
+ POST：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/request_accept.json`
+ 请求体：

```json
{
  "message": "shipping at 8pm"
}
```

履约应用通过调用 [拒绝发货请求](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/fulfillment-app-rejects-shipment-request.md) REST API 拒绝发货请求。拒绝成功后，商家可重新提交发货请求。

接口示例：
+ POST：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/request_reject.json`
+ 请求体：

```json
{
  "reason": "incorrect_address",
  "message": "cannot ship to this address"
}
```

#### 第四步：创建发货单
履约应用接受发货请求后，将调用 [为履约单创建发货单](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/create-an-fulfillment-for-the-fulfillment-order-single-or-batch.md) REST API 来处理履约单中商品的发货。

> **注意**
>
> 目前仅支持整个履约单发货，不支持仅发货履约单中的部分商品。

必要条件：

* 履约单状态 `status` 为 `open` 或者 `in_progress`。
* 商品行的可履约数量 `fulfillable_quantity` 大于 0。

> **注意**
>
> 使用 SHOPLINE Payments 作为支付方式的订单进行发货时，需在请求中通过 `tracking_info_list.tracking_number` 和 `tracking_info_list.tracking_company` 提供运单号以及运输公司信息，作为报关结账凭证。

请求示例：
+ POST：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/fulfillments.json`
+ 请求体：

```json
{
  "fulfillment": {
    "line_items_by_fulfillment_order": [
      {
        "fulfillment_order_id": "1046000807"
      }
    ],
    "message": "The package was shipped this morning.",
    "notify_customer": true,
    "tracking_info_list": [
      {
        "tracking_company": "my-company",
        "tracking_number": "UG15439033",
        "tracking_url": "http://www.my-url.com"
      }
    ]
  },
  "order_id": "21057116277667827637773776"
}
```

+ 响应体：

```json
{
  "fulfillment": {
    "created_at": "2022-10-21T08:56:20-04:00",
    "id": "4005740193290131085320",
    "line_items": [
      {
        "fulfillable_quantity": 1,
        "fulfillment_quantity": 1,
        "fulfillment_status": "open",
        "grams": 10.5,
        "id": "466157049",
        "name": "Trade name",
        "price": "100.00",
        "price_set": {
          "presentment_money": {
            "amount": "100.00",
            "currency_code": "USD"
          },
          "shop_money": {
            "amount": "100.00",
            "currency_code": "USD"
          }
        },
        "product_id": "343342675",
        "properties": [
          {
            "additional": " add-on information ",
            "name": " picture ",
            "type": "picture",
            "urls": [
              "https://www.myshopline.com"
            ],
            "value": "value"
          }
        ],
        "quantity": 1,
        "requires_shipping": true,
        "sku": "183423409238904944",
        "tax_lines": [
          {
            "name": " item tax ",
            "price": "10.00",
            "price_set": {
              "presentment_money": {
                "amount": "10.00",
                "currency_code": "USD"
              },
              "shop_money": {
                "amount": "10.00",
                "currency_code": "USD"
              }
            },
            "rate": "1.00",
            "title": " Product tax "
          }
        ],
        "taxable": true,
        "title": "Draft",
        "total_discount": "0.00",
        "total_discount_set": {
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "USD"
          },
          "shop_money": {
            "amount": "0.00",
            "currency_code": "USD"
          }
        },
        "variant_id": "183423409238904944",
        "variant_title": "Black / Bracelet / Bracelet",
        "vendor": "",
        "version": "1"
      }
    ],
    "location_id": "54039222210",
    "name": "#21057116277667827637773776.1",
    "order_id": "21057116277667827637773776",
    "shipment_status": "success",
    "status": "success",
    "tracking_company": "Other",
    "tracking_number": "UG198768340YP",
    "tracking_numbers": [
      "UG198768340YP"
    ],
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z2345",
    "tracking_urls": [
      "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z2345"
    ],
    "updated_at": "2022-10-21T08:56:20-04:00"
  }
}
```

#### 第五步（可选）：更新发货单物流追踪信息
履约应用可调用 [创建履约发货物流事件](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/create-fulfillment-shipping-logistics-event.md) 为发货单增加最新的物流追踪信息，SHOPLINE 将会发送物流更新邮件给客户。

接口示例：
+ POST：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/events/create.json`
+ 请求体：

```json
{
  "address": "126 York Street",
  "city": "Ottawa",
  "country": "Canada",
  "estimated_delivery_at": "2021-08-16T08:27:57+00:00",
  "happened_at": "2021-08-16T08:27:57+00:00",
  "latitude": "23.32947",
  "longitude": "113.301255",
  "message": "nothing",
  "province": "Ontario",
  "status": "label_printed",
  "zip": "A1B 2C3"
}
```

+ 响应体：

```json
{
  "fulfillment_event": {
    "address": "126 York Street",
    "city": "Ottawa",
    "country": "Canada",
    "create_at": "2021-08-16T08:27:57+00:00",
    "estimated_delivery_at": "2021-08-16T08:27:57+00:00",
    "fulfillment_id": "22060720884441337538627925",
    "happened_at": "2021-08-16T08:27:57+00:00",
    "id": "4206234611998187371524",
    "latitude": "23.32947",
    "longitude": "113.301255",
    "message": "nothing",
    "order_id": "21056024607602932623437925",
    "province": "Ontario",
    "shop_id": "2331445",
    "status": "label_printed",
    "update_at": "2021-08-16T08:27:57+00:00",
    "zip": "A1B 2C3"
  }
}
```

### 处理取消发货请求步骤
#### 第一步：接收取消发货请求提交事件
当商家在 SHOPLINE 商家后台点击 **取消发货** 后，履约应用将收到 [取消发货请求提交](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/cancellation-request-for-fulfillment-order.md) webhook 事件。

事件示例：

```json
{
  "fulfillment_order": {
    "fulfillment_order_merchant_request": {
      "message": "customer wanna cancel"
    },
    "id": "21062824515206062204123195_4006282455672296213439",
    "request_status": "cancellation_requested",
    "status": "in_progress"
  }
}
```

#### 第二步：获取履约单信息
接收到 [取消发货请求提交](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/cancellation-request-for-fulfillment-order.md) webhook 事件后，履约应用调用 [获取指定履约单](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/get-specify-fulfillment-order.md) REST API 获取履约信息。

#### 第三步：接受或拒绝取消发货请求
履约应用根据履约单中的配送目的地 `destination`、商品行信息 `line_items`、数量 `quantity` 等条件确定接受或拒绝取消发货请求，并调用 [接受取消发货请求](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/fulfillment-app-accepts-cancellation-request-for-shipment.md) REST API 接受请求。随后，订单系统将关闭该履约单，并生成新的履约单。

接口示例：
+ POST：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/cancellation_request_accept.json`
+ 请求体：

```json
{
  "message": "ok"
}
```

履约应用调用 [拒绝取消发货请求](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/order/shipping-and-fulfillment/fulfillment-app-rejects-shipment-cancellation-request.md) REST API 来拒绝取消发货请求。被拒绝后，商家仍可再次提交取消发货请求。

接口示例：
+ POST：`https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/cancellation_request_reject.json`
+ 请求体：

```json
{
  "message": "The order was already shipped"
}
```

> **注意**
>
> 当发货请求未进行接受或拒绝前商家就取消发货请求，履约应用将收到对应的 [履约单更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/order/fulfillment-order-update.md) 事件，此时履约单已关闭，服务商无需进行履约。

事件示例：

```json
{
  "fulfillment_order": {
    "assigned_location": {
      "address1": "Yulong road",
      "address2": "",
      "city": "",
      "country_code": "US",
      "location_id": "5759241455475889066",
      "name": "Tom",
      "phone": "136****5580",
      "province": "New York",
      "zip": "9900"
    },
    "assigned_location_id": "5759241455475889066",
    "delivery_method": {
      "method_type": "none"
    },
    "destination": {
      "email": "xxxxxxxx@example.com"
    },
    "fulfillment_holds": [],
    "id": "4006280934539751235751",
    "line_items": [
      {
        "fulfillable_quantity": "0",
        "fulfillment_order_id": "4006280934539751235751",
        "id": "7691",
        "line_item_id": "7127",
        "quantity": 1,
        "shop_id": "1000067",
        "variant_id": "18062809312326262549272210"
      }
    ],
    "merchant_requests": [],
    "order_id": "21062809345336442050725071",
    "request_status": "unsubmitted",
    "shop_id": "1000067",
    "status": "closed",
    "supported_actions": []
  }
}
```