简体中文

English

简体中文

English

显示模式

管理履约 ​

订单履约指的是从客户下单到订单最终发货完成这一整个过程的管理，包括订单处理、物流发货、配送追踪和售后服务等环节。高效的履约管理不仅能够缩短订单交付时间、提高客户满意度，还能优化库存及供应链管理，防止超卖，降低运营成本。

Genstore 允许开发者构建履约管理应用，这些应用可以与 Genstore 平台直接集成，实现订单处理全流程的自动化，进而提高物流效率并优化履约体验。

下图展示了订单管理应用在履行订单过程中的示例生命周期：

前置准备 ​

API 总览 ​

API Endpoint功能描述
/api/202412/orders?limit={n}&financialStatus=paid&fulfillmentStatus=unfulfilled查询订单列表，可通过参数过滤订单状态（如待发货订单）
/api/202412/fulfillment为订单创建履约记录
/api/202412/fulfillments/{fulfillmentId}管理指定的订单履约记录

业务场景 - 检索订单 ​

业务场景说明：

在订单履约前，需要先查询待发货订单或查询已发货订单的履约信息，确定需要处理的订单列表。

示例：查询待发货订单

GET /api/202412/orders?limit={n}&financialStatus=paid&fulfillmentStatus=unfulfilled

json
curl --request GET \
  --url 'https://{your-development-store}.genmystore.com/api/202412/orders?limit=10&financialStatus=paid&fulfillmentStatus=unfulfilled' \
  --header 'x-genstore-access-token: {access-token}' \
'

响应示例：

响应体会返回订单相关信息，包含订单 ID、订单状态、订单收货地址等，部分核心响应字段如下:

json
{
    "id":"300157930096874",
    "financialStatus":"paid",
    "fulfillmentStatus":"unfulfilled",
    "shippingAddress": {
        "address1": "Street 123",
        "address2": "Building A, Floor 5",
        "city": "Metropolis",
        "country": "XX",
        "firstName": "John",
        "lastName": "Doe",
        "zip": "000000",
        "phone": "+999000111222"
    }
}

业务场景 - 创建履约信息 ​

业务场景说明：

查询到待发货订单后，可为订单创建履约记录。物流发货后，记录运单号并同步调用 创建履约 创建履约信息。

示例：创建履约

POST /api/202412/fulfillment

json
curl --request POST \
  --url https:///{your-development-store}.genmystore.com/api/202412/fulfillment \
  --header 'Content-Type: application/json' \
  --header 'x-genstore-access-token: {access-token}' \
  --data '{
    "fulfillment":{
        "orderId":300157930096874,
        "trackingNumber":"090909090900",
        ...
    }

}'

业务场景 - 更新履约信息 ​

业务场景说明：

在订单履约后，若物流信息（如追踪链接或运单号）发生变更，可调用 更新履约物流信息 接口同步最新信息至 Genstore 系统。

示例：更新履约物流信息

PUT /api/202412/fulfillments/{fulfillmentId}

json
curl -X PUT \ 
"https://{your-development-store}.genmystore.com/api/202412/fulfillments/{fulfillmentId}/update_tracking" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillment":{
		"lineItems":[
			{
				"variantTitle":"",
				"quantity":"",
				"productId":"",
				"title":"",
				"fulfillmentStatus":"",
				"requiresShipping":"",
				"price":"",
				"giftCard":"",
				"name":"",
				"id":"",
				"variantId":"",
				"grams":"",
				"sku":""
			}
		],
		"orderId":"",
		"trackingUrl":"",
		"createTime":"",
		"originAddress":[
			{
				"zip":"",
				"address2":"",
				"city":"",
				"address1":"",
				"countryCode":"",
				"provinceCode":""
			}
		],
		"trackingCompany":"",
		"trackingNumbers":"",
		"updateTime":"",
		"id":"",
		"trackingNumber":"",
		"trackingUrls":"",
		"status":""
	}
}'

业务场景 - 取消履约 ​

业务场景说明：

在订单取消的情况下，例如通过监听 订单取消 Webhook 获取相关信息，应用需要同步取消履约记录。此时，可通过 取消履约 接口取消已创建的履约记录，传入履约订单 ID 即可:

示例：取消履约

PUT /api/202412/fulfillments/{fulfillmentId}/cancel

json
curl -X PUT \ 
"https://{your-development-store}.genmystore.com/api/202412/fulfillments/{fulfillmentId}/cancel" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillmentId":"237894043"
}'

Webhook ​

业务场景说明：
为实现订单和履约的实时自动化管理，建议订阅以下 Webhook 事件，以便及时获知订单状态或履约状态的变化，从而触发相应的业务处理。

Webhook 主题描述
orders/fulfilled通知订单已履约
orders/partiallyFulfilled通知订单部分完成履约
orders/cancelled此 Webhook 在订单被取消时触发，帮助您实时获取订单取消的信息，以便进行相应的操作或跟踪。
refunds/create退款消息，主要包括退款处理中、已退款和资金变动消息