--- title: "履约单更新" description: "履约单更新事件" doc_type: openapi doc_category: openapi doc_version: v20270301 source_url: html: 'https://developer.shopline.com/zh-hans-cn/docs/webhook/order/fulfillment-order-update' md: 'https://developer.shopline.com/zh-hans-cn/docs/webhook/order/fulfillment-order-update.md' --- # 履约单更新 履约单更新事件 - **API Version:** v20270301 - **API Type:** Webhook - **API Protocol:** RESTful ## Request ### Request Headers * `X-Shopline-Topic` string (required) 事件的唯一标识。 * `X-Shopline-Hmac-Sha256` string (required) 该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。 * `X-Shopline-Shop-Domain` string (required) 店铺的域名。 * `X-Shopline-Shop-Id` string (required) 店铺 ID。 * `X-Shopline-Merchant-Id` string (required) 商家 ID。 * `X-Shopline-API-Version` string (required) API 版本号。 * `X-Shopline-Webhook-Id` string (required) 该 Webhook 事件的 ID。 ### Request Body * `fulfillment_order` object 履约详情 * `assigned_location` object 被分配的地点详情 * `address1` string 地址1 * `address2` string 地址2 * `city` string 城市 * `country` string 国家 * `country_code` string 国家码 * `location_id` string 地址id * `name` string 名称 * `phone` string 手机 * `province` string 省份 * `zip` string 邮编 * `assigned_location_id` string 被分配的地点id * `delivery_method` object 履约单配送方式信息 * `max_delivery_date_time` string 最晚发货时间 * `method_type` string 配送方式：local、none、pick_up、retail、shipping * `min_delivery_date_time` string 可发货时间 * `service_code` string 承运商运费方案编号。 * `shipping_rate_name` string 运费方案名称，当发货方式为 `SHIPPING` 或 `LOCAL_DELIVERY`，才有运费方案名称。 * `shipping_strategy_name` string 物流分组名称，当发货方式为 `SHIPPING` 或 `LOCAL_DELIVERY`，才有对应的值。 * `destination` object 收货人信息 * `address1` string 地址1 * `address2` string 地址2 * `city` string 城市 * `company` string 公司 * `country` string 国家 * `country_code` string 国家码 * `delivery_store_code` string 本地配送门店id，仅本地配送时提供 * `delivery_store_name` string 本地配送门店名称，仅本地配送时提供 * `email` string 邮箱 * `first_name` string 名称 * `last_name` string 姓氏 * `name` string 姓名 * `phone` string 手机 * `province` string 省份 * `province_code` string 州或是省编码，IOS 3166-2编码 * `zip` string 邮编 * `fulfillment_holds` array 暂停信息 * `reason` string 暂停原因 * `reason_note` string 暂停备注 * `id` string 履约单id * `line_items` array 商品行信息 * `country_code_of_origin` string 原产地/发货地的国家代码 * `fulfillable_quantity` string 可履约商品数量 * `fulfillment_order_id` string 履约单id * `harmonized_system_code` string 海关编码 * `id` string 履约单商品行id * `line_item_id` string 商品行id * `quantity` long 订单商品行商品数量 * `shop_id` string 店铺id * `variant_id` string 商品sku * `merchant_requests` array 请求发货信息列表 * `kind` string 请求类型： ① fulfillment_request ② cancellation_request * `message` string 履约发货应用的备注 * `request_options` object 请求参数 * `notify_customer` boolean 是否通知客户 * `send_at` string 请求时间 * `order_id` string 订单id * `request_status` string 履约单请求状态，包括：accepted，cancellation_accepted，cancellation_rejected，cancellation_requested，closed，rejected，submitted，unsubmitted * `shop_id` string 店铺id * `status` string 履约单状态，包括：open，in_progress，closed，cancelled，incomplete，on_hold，scheduled * `supported_actions` array 履约单支持的操作,包括：create_fulfillment -- 创建发货，move -- 移动到新地点，hold -- 暂停发货，release_hold -- （暂停之后）开始发货 ## Response ### Status Codes * `200` 收到 SHOPLINE 发送的 Webhook 通知后，你需要按照如下 SHOPLINE 要求的格式进行响应。 ``` HTTP/1.1 200 OK ``` 关于如何订阅 Webhooks 及更多 Webhook 响应规则说明，请参考 [Webhook 概述](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/webhooks/overview.md)。 ### Response Body #### 200 _No response body_ ## OpenAPI Definition ```json { "description": "履约单更新事件", "externalDocs": { "description": "| 事件分组 | 事件标识 |\n| :------: | :------: |\n|fulfillment_order |fulfillment_order/update |\n", "url": "", "errorTableDescription": "" }, "operationId": "Ivfn5GLz", "parameters": [ { "name": "X-Shopline-Topic", "in": "header", "description": "事件的唯一标识。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Topic", "description": "事件的唯一标识。", "type": "string", "example": "orders/edited" }, "example": "orders/edited" }, { "name": "X-Shopline-Hmac-Sha256", "in": "header", "description": "该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Hmac-Sha256", "description": "该请求的签名。收到请求后，你需要对该签名进行 [验签](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/generate-and-verify-signatures.md#post-请求操作步骤) 以验证数据的真实性和完整性。", "type": "string", "example": "XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=" }, "example": "XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=" }, { "name": "X-Shopline-Shop-Domain", "in": "header", "description": "店铺的域名。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Shop-Domain", "description": "店铺的域名。", "type": "string", "example": "example.myshopline.com" }, "example": "example.myshopline.com" }, { "name": "X-Shopline-Shop-Id", "in": "header", "description": "店铺 ID。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Shop-Id", "description": "店铺 ID。", "type": "string", "example": "1610418123456" }, "example": "1610418123456" }, { "name": "X-Shopline-Merchant-Id", "in": "header", "description": "商家 ID。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Merchant-Id", "description": "商家 ID。", "type": "string", "example": "2000001234" }, "example": "2000001234" }, { "name": "X-Shopline-API-Version", "in": "header", "description": "API 版本号。", "required": true, "style": "string", "schema": { "name": "X-Shopline-API-Version", "description": "API 版本号。", "type": "string", "example": "v20250601" }, "example": "v20250601" }, { "name": "X-Shopline-Webhook-Id", "in": "header", "description": "该 Webhook 事件的 ID。", "required": true, "style": "string", "schema": { "name": "X-Shopline-Webhook-Id", "description": "该 Webhook 事件的 ID。", "type": "string", "example": "b54557e48a5fbf7d70bcd043" }, "example": "b54557e48a5fbf7d70bcd043" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fulfillment_order": { "name": "fulfillment_order", "description": "履约详情", "type": "object", "properties": { "assigned_location": { "name": "assigned_location", "description": "被分配的地点详情", "type": "object", "properties": { "address1": { "name": "address1", "description": "地址1", "type": "string", "example": "\"Chestnut Street 92\"" }, "address2": { "name": "address2", "description": "地址2", "type": "string", "example": "\"Chestnut Street 92\"" }, "city": { "name": "city", "description": "城市", "type": "string", "example": "\"Louisville\"" }, "country": { "name": "country", "description": "国家", "type": "string", "example": "\"United States\"" }, "country_code": { "name": "country_code", "description": "国家码", "type": "string", "example": "\"US\"" }, "location_id": { "name": "location_id", "description": "地址id", "type": "string", "example": "\"5327026538935748524\"" }, "name": { "name": "name", "description": "名称", "type": "string", "example": "\"Apple Api Shipwire\"" }, "phone": { "name": "phone", "description": "手机", "type": "string", "example": "\"+1(502)-459-3417\"" }, "province": { "name": "province", "description": "省份", "type": "string", "example": "\"Kentucky\"" }, "zip": { "name": "zip", "description": "邮编", "type": "string", "example": "\"40202\"" } }, "example": { "address1": "\"Chestnut Street 92\"", "address2": "\"Chestnut Street 92\"", "city": "\"Louisville\"", "country": "\"United States\"", "country_code": "\"US\"", "location_id": "\"5327026538935748524\"", "name": "\"Apple Api Shipwire\"", "phone": "\"+1(502)-459-3417\"", "province": "\"Kentucky\"", "zip": "\"40202\"" } }, "assigned_location_id": { "name": "assigned_location_id", "description": "被分配的地点id", "type": "string", "example": "\"5327026538935748524\"" }, "delivery_method": { "name": "delivery_method", "description": "履约单配送方式信息", "type": "object", "properties": { "max_delivery_date_time": { "name": "max_delivery_date_time", "description": "最晚发货时间", "type": "string", "example": "\"2021-05-26T10:00:00-04:00\"" }, "method_type": { "name": "method_type", "description": "配送方式：local、none、pick_up、retail、shipping", "type": "string", "example": "\"none\"" }, "min_delivery_date_time": { "name": "min_delivery_date_time", "description": "可发货时间", "type": "string", "example": "\"2021-05-26T10:00:00-04:00\"" }, "service_code": { "name": "service_code", "description": "承运商运费方案编号。", "type": "string", "example": "" }, "shipping_rate_name": { "name": "shipping_rate_name", "description": "运费方案名称，当发货方式为 `SHIPPING` 或 `LOCAL_DELIVERY`，才有运费方案名称。", "type": "string", "example": "" }, "shipping_strategy_name": { "name": "shipping_strategy_name", "description": "物流分组名称，当发货方式为 `SHIPPING` 或 `LOCAL_DELIVERY`，才有对应的值。", "type": "string", "example": "" } }, "example": { "max_delivery_date_time": "\"2021-05-26T10:00:00-04:00\"", "method_type": "\"none\"", "min_delivery_date_time": "\"2021-05-26T10:00:00-04:00\"", "service_code": "", "shipping_rate_name": "", "shipping_strategy_name": "" } }, "destination": { "name": "destination", "description": "收货人信息", "type": "object", "properties": { "address1": { "name": "address1", "description": "地址1", "type": "string", "example": "\"Chestnut Street 92\"" }, "address2": { "name": "address2", "description": "地址2", "type": "string", "example": "\"Chestnut Street 92\"" }, "city": { "name": "city", "description": "城市", "type": "string", "example": "\"Louisville\"" }, "company": { "name": "company", "description": "公司", "type": "string", "example": "\"Apple inc\"" }, "country": { "name": "country", "description": "国家", "type": "string", "example": "\"US\"" }, "country_code": { "name": "country_code", "description": "国家码", "type": "string", "example": "\"US\"" }, "delivery_store_code": { "name": "delivery_store_code", "description": "本地配送门店id，仅本地配送时提供", "type": "string", "example": "\"A121\"" }, "delivery_store_name": { "name": "delivery_store_name", "description": "本地配送门店名称，仅本地配送时提供", "type": "string", "example": "\"Napo Shop\"" }, "email": { "name": "email", "description": "邮箱", "type": "string", "example": "\"bob.norman@mail.example.com\"" }, "first_name": { "name": "first_name", "description": "名称", "type": "string", "example": "\"Bob\"" }, "last_name": { "name": "last_name", "description": "姓氏", "type": "string", "example": "\"Norman\"" }, "name": { "name": "name", "description": "姓名", "type": "string", "example": "\"Bob Norman\"" }, "phone": { "name": "phone", "description": "手机", "type": "string", "example": "\"+1(502)-459-3417\"" }, "province": { "name": "province", "description": "省份", "type": "string", "example": "\"Kentucky\"" }, "province_code": { "name": "province_code", "description": "州或是省编码，IOS 3166-2编码", "type": "string", "example": "\"KY\"" }, "zip": { "name": "zip", "description": "邮编", "type": "string", "example": "\"40202\"" } }, "example": { "address1": "\"Chestnut Street 92\"", "address2": "\"Chestnut Street 92\"", "city": "\"Louisville\"", "company": "\"Apple inc\"", "country": "\"US\"", "country_code": "\"US\"", "delivery_store_code": "\"A121\"", "delivery_store_name": "\"Napo Shop\"", "email": "\"bob.norman@mail.example.com\"", "first_name": "\"Bob\"", "last_name": "\"Norman\"", "name": "\"Bob Norman\"", "phone": "\"+1(502)-459-3417\"", "province": "\"Kentucky\"", "province_code": "\"KY\"", "zip": "\"40202\"" } }, "fulfillment_holds": { "name": "fulfillment_holds", "description": "暂停信息", "type": "array", "items": { "name": "fulfillment_holds", "description": "暂停信息", "type": "object", "properties": { "reason": { "name": "reason", "description": "暂停原因", "type": "string", "example": "\"out of stock\"" }, "reason_note": { "name": "reason_note", "description": "暂停备注", "type": "string", "example": "\"customer require\"" } }, "example": { "reason": "\"out of stock\"", "reason_note": "\"customer require\"" } }, "example": [ "" ] }, "id": { "name": "id", "description": "履约单id", "type": "string", "example": "\"4005740193290131085320\"" }, "line_items": { "name": "line_items", "description": "商品行信息", "type": "array", "items": { "name": "line_items", "description": "商品行信息", "type": "object", "properties": { "country_code_of_origin": { "name": "country_code_of_origin", "description": "原产地/发货地的国家代码", "type": "string", "example": "\"US\"" }, "fulfillable_quantity": { "name": "fulfillable_quantity", "description": "可履约商品数量", "type": "string", "example": "1" }, "fulfillment_order_id": { "name": "fulfillment_order_id", "description": "履约单id", "type": "string", "example": "\"4005740193290131085320\"" }, "harmonized_system_code": { "name": "harmonized_system_code", "description": "海关编码", "type": "string", "example": "\"1231\"" }, "id": { "name": "id", "description": "履约单商品行id", "type": "string", "example": "\"1039283\"" }, "line_item_id": { "name": "line_item_id", "description": "商品行id", "type": "string", "example": "\"518995019\"" }, "quantity": { "name": "quantity", "description": "订单商品行商品数量", "type": "long", "example": 1 }, "shop_id": { "name": "shop_id", "description": "店铺id", "type": "string", "example": "\"1644828244663\"" }, "variant_id": { "name": "variant_id", "description": "商品sku", "type": "string", "example": "\"18055128824718541486811487\"" } }, "example": { "country_code_of_origin": "\"US\"", "fulfillable_quantity": "1", "fulfillment_order_id": "\"4005740193290131085320\"", "harmonized_system_code": "\"1231\"", "id": "\"1039283\"", "line_item_id": "\"518995019\"", "quantity": 1, "shop_id": "\"1644828244663\"", "variant_id": "\"18055128824718541486811487\"" } }, "example": [ "" ] }, "merchant_requests": { "name": "merchant_requests", "description": "请求发货信息列表", "type": "array", "items": { "name": "merchant_requests", "description": "请求发货信息列表", "type": "object", "properties": { "kind": { "name": "kind", "description": "请求类型： ① fulfillment_request ② cancellation_request", "type": "string", "example": "\"fulfillment_request\"" }, "message": { "name": "message", "description": "履约发货应用的备注", "type": "string", "example": "\"accept\"" }, "request_options": { "name": "request_options", "description": "请求参数", "type": "object", "properties": { "notify_customer": { "name": "notify_customer", "description": "是否通知客户", "type": "boolean", "example": false } }, "example": { "notify_customer": false } }, "send_at": { "name": "send_at", "description": "请求时间", "type": "string", "example": "\"2021-05-26T10:00:00-04:00\"" } }, "example": { "kind": "\"fulfillment_request\"", "message": "\"accept\"", "request_options": { "notify_customer": false }, "send_at": "\"2021-05-26T10:00:00-04:00\"" } }, "example": [ "" ] }, "order_id": { "name": "order_id", "description": "订单id", "type": "string", "example": "\"21057401932826316666967110\"" }, "request_status": { "name": "request_status", "description": "履约单请求状态，包括：accepted，cancellation_accepted，cancellation_rejected，cancellation_requested，closed，rejected，submitted，unsubmitted", "type": "string", "example": "\"submitted\"" }, "shop_id": { "name": "shop_id", "description": "店铺id", "type": "string", "example": "\"1644828244663\"" }, "status": { "name": "status", "description": "履约单状态，包括：open，in_progress，closed，cancelled，incomplete，on_hold，scheduled", "type": "string", "example": "\"open\"" }, "supported_actions": { "name": "supported_actions", "description": "履约单支持的操作,包括：create_fulfillment -- 创建发货，move -- 移动到新地点，hold -- 暂停发货，release_hold -- （暂停之后）开始发货", "type": "array", "items": { "name": "supported_actions", "description": "履约单支持的操作,包括：create_fulfillment -- 创建发货，move -- 移动到新地点，hold -- 暂停发货，release_hold -- （暂停之后）开始发货", "type": "string", "example": "\"release_hold\"" }, "example": [ "\"release_hold\"" ] } }, "example": { "assigned_location": { "address1": "\"Chestnut Street 92\"", "address2": "\"Chestnut Street 92\"", "city": "\"Louisville\"", "country": "\"United States\"", "country_code": "\"US\"", "location_id": "\"5327026538935748524\"", "name": "\"Apple Api Shipwire\"", "phone": "\"+1(502)-459-3417\"", "province": "\"Kentucky\"", "zip": "\"40202\"" }, "assigned_location_id": "\"5327026538935748524\"", "delivery_method": { "max_delivery_date_time": "\"2021-05-26T10:00:00-04:00\"", "method_type": "\"none\"", "min_delivery_date_time": "\"2021-05-26T10:00:00-04:00\"", "service_code": "", "shipping_rate_name": "", "shipping_strategy_name": "" }, "destination": { "address1": "\"Chestnut Street 92\"", "address2": "\"Chestnut Street 92\"", "city": "\"Louisville\"", "company": "\"Apple inc\"", "country": "\"US\"", "country_code": "\"US\"", "delivery_store_code": "\"A121\"", "delivery_store_name": "\"Napo Shop\"", "email": "\"bob.norman@mail.example.com\"", "first_name": "\"Bob\"", "last_name": "\"Norman\"", "name": "\"Bob Norman\"", "phone": "\"+1(502)-459-3417\"", "province": "\"Kentucky\"", "province_code": "\"KY\"", "zip": "\"40202\"" }, "fulfillment_holds": [ "" ], "id": "\"4005740193290131085320\"", "line_items": [ "" ], "merchant_requests": [ "" ], "order_id": "\"21057401932826316666967110\"", "request_status": "\"submitted\"", "shop_id": "\"1644828244663\"", "status": "\"open\"", "supported_actions": [ "\"release_hold\"" ] } } }, "example": { "fulfillment_order": { "assigned_location": { "address1": "\"Chestnut Street 92\"", "address2": "\"Chestnut Street 92\"", "city": "\"Louisville\"", "country": "\"United States\"", "country_code": "\"US\"", "location_id": "\"5327026538935748524\"", "name": "\"Apple Api Shipwire\"", "phone": "\"+1(502)-459-3417\"", "province": "\"Kentucky\"", "zip": "\"40202\"" }, "assigned_location_id": "\"5327026538935748524\"", "delivery_method": { "max_delivery_date_time": "\"2021-05-26T10:00:00-04:00\"", "method_type": "\"none\"", "min_delivery_date_time": "\"2021-05-26T10:00:00-04:00\"", "service_code": "", "shipping_rate_name": "", "shipping_strategy_name": "" }, "destination": { "address1": "\"Chestnut Street 92\"", "address2": "\"Chestnut Street 92\"", "city": "\"Louisville\"", "company": "\"Apple inc\"", "country": "\"US\"", "country_code": "\"US\"", "delivery_store_code": "\"A121\"", "delivery_store_name": "\"Napo Shop\"", "email": "\"bob.norman@mail.example.com\"", "first_name": "\"Bob\"", "last_name": "\"Norman\"", "name": "\"Bob Norman\"", "phone": "\"+1(502)-459-3417\"", "province": "\"Kentucky\"", "province_code": "\"KY\"", "zip": "\"40202\"" }, "fulfillment_holds": [ "" ], "id": "\"4005740193290131085320\"", "line_items": [ "" ], "merchant_requests": [ "" ], "order_id": "\"21057401932826316666967110\"", "request_status": "\"submitted\"", "shop_id": "\"1644828244663\"", "status": "\"open\"", "supported_actions": [ "\"release_hold\"" ] } } } } }, "required": true }, "responses": { "200": { "description": "收到 SHOPLINE 发送的 Webhook 通知后，你需要按照如下 SHOPLINE 要求的格式进行响应。\n\n``` HTTP/1.1 200 OK ``` \n\n关于如何订阅 Webhooks 及更多 Webhook 响应规则说明，请参考 [Webhook 概述](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/webhooks/overview.md)。" } }, "info": { "title": "履约单更新", "version": "v20270301" } } ```