发货流程

本文旨在介绍履约应用发货流程。在此之前，将说明履约发货的核心概念及履约单状态流转规则。

履约发货相关对象关系​

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

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

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

111.png

履约单相关状态​

履约单状态流转图​

222.png

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

履约单请求状态流转​

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

333.png

履约应用发货流程​

前提条件​

订阅必须的 webhook 事件​

履约应用需要申请订阅 发货请求提交、发货取消请求提交、履约单更新 的 webhook 事件，以接收商家在 SHOPLINE 商家后台提交的发货、取消发货以及履约单更新操作。

创建一个履约服务​

履约应用可以使用 创建履约服务 的 REST API，创建专属于应用的履约服务。

注意

一个应用仅能创建一个履约服务。

创建一个履约应用地点​

履约应用承担服务商角色后，需调用 创建履约应用地点 接口生成专用地点，方便商家管理商品库存和履约发货。

处理发货请求步骤​

第一步：接收发货请求提交事件​

当商家在 SHOPLINE 商家后台点击 提交发货 后，履约应用将收到 发货请求提交 webhook 事件。

事件示例：

{
  "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"
  }
}

第二步：获取履约单信息​

根据接收到的 发货请求提交 webhook 事件，使用 获取指定履约单 REST API 获取履约信息。

接口示例：

  • GET：https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillment_orders/:order_id/:fulfillment_order_id.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 等条件确定接受或拒绝本次请求。

履约应用通过 接受发货请求 REST API 接受发货请求。

接口示例：

  • POST：https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/request_accept.json
  • 请求体：
{
  "message": "shipping at 8pm"
}

履约应用通过调用 拒绝发货请求 REST API 拒绝发货请求。拒绝成功后，商家可重新提交发货请求。

接口示例：

  • POST：https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/request_reject.json
  • 请求体：
{
  "reason": "incorrect_address",
  "message": "cannot ship to this address"
}

第四步：创建发货单​

履约应用接受发货请求后，将调用 为履约单创建发货单 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
  • 请求体：
{
  "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"
}
  • 响应体：
{
  "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"
  }
}

第五步（可选）：更新发货单物流追踪信息​

履约应用可调用 创建履约发货物流事件 为发货单增加最新的物流追踪信息，SHOPLINE 将会发送物流更新邮件给客户。

接口示例：

  • POST：https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/events/create.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"
}
  • 响应体：
{
  "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 商家后台点击 取消发货 后，履约应用将收到 取消发货请求提交 webhook 事件。

事件示例：

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

第二步：获取履约单信息​

接收到 取消发货请求提交 webhook 事件后，履约应用调用 获取指定履约单 REST API 获取履约信息。

第三步：接受或拒绝取消发货请求​

履约应用根据履约单中的配送目的地 destination、商品行信息 line_items、数量 quantity 等条件确定接受或拒绝取消发货请求，并调用 接受取消发货请求 REST API 接受请求。随后，订单系统将关闭该履约单，并生成新的履约单。

接口示例：

  • POST：https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/cancellation_request_accept.json
  • 请求体：
{
  "message": "ok"
}

履约应用调用 拒绝取消发货请求 REST API 来拒绝取消发货请求。被拒绝后，商家仍可再次提交取消发货请求。

接口示例：

  • POST：https://{handle}.myshopline.com/admin/openapi/v20260301/fulfillments/:order_id/:fulfillment_id/cancellation_request_reject.json
  • 请求体：
{
  "message": "The order was already shipped"
}
注意

当发货请求未进行接受或拒绝前商家就取消发货请求，履约应用将收到对应的 履约单更新 事件，此时履约单已关闭，服务商无需进行履约。

事件示例：

{
  "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": []
  }
}
这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.