订单物流轨迹

提供订单物流轨迹的查询能力，支持通过西月订单号或物流单号获取对应的物流运输节点信息，包括各阶段的时间、地点和状态描述，适用于追踪订单的物流运输全过程。

适用场景

查询订单的完整物流轨迹（从发货到签收的各节点信息）

通过物流单号追踪包裹的实时运输状态

分析物流运输的时效和异常情况（如投递失败、运输过久等）

接口类型

POST

请求频率限制

默认频率：以平台配额为准

请求说明

请求URL

正式环境：https://www.westmonth.com/openapi/v2/order/track
测试环境：https://testing.westmonth.com/openapi/v2/order/track

请求参数

Header参数

参数名	类型	必填	示例值	说明
Authorization	string	是	authorization	身份验证Token
Content-Type	string	是	application/json	建议固定传此值

Body参数

根字段

参数名	类型	必填	默认值	说明
order_nos	array	否	-	西月订单号集合，与express_numbers可二选一或同时传入
express_numbers	array	否	-	物流单号集合，与order_nos可二选一或同时传入
page	integer	是	1	页数，默认1
size	integer	是	20	每页条数，默认20

⚠️ 注意：order_nos和express_numbers至少需传入一个，若同时传入则返回两者匹配的结果集合。

响应字段说明

成功响应（HTTP 200）

根字段

字段	类型	说明
code	integer	业务状态码（0表示成功）
msg	string	提示信息（成功时为空）
data	object	业务数据

data对象字段

字段	类型	说明
list	array	物流轨迹列表（当前页数据）
total	integer	符合条件的物流轨迹总条数

list数组字段

字段	类型	说明
number	string	西月订单号
type	string	物流类型（如：订单物流、售后退货物流、第三方自提）
logistics_company	string	物流公司名称（如：USPS）
shipment_no	string	物流单号
events	array	运输节点列表（按时间倒序排列，最新节点在前）

events数组字段

字段	类型	说明
time_raw	string	节点时间（格式：yyyy-MM-dd HH:mm:ss）
description	string	节点描述（如：Delivered, In/At Mailbox）

调用示例

URL请求

请求示例

{
    "order_nos": [
        "xxxx"
    ],
    "express_numbers": [],
    "page": 1,
    "size": 20
}

成功返回示例

{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {
                "number": "xxxx",
                "type": "订单物流",
                "logistics_company": "USPS",
                "shipment_no": "xxxxx",
                "events": [
                    {
                        "time_raw": "2025-07-31 22:43:00 ",
                        "description": "HOUSTON, TX 77047, Shipping Label Created, USPS Awaiting Item -> A shipping label has been prepared for your item. A delivery date will be provided when USPS receives the package; contact the shipper or shipping partner with any inquiries."
                    }
                ]
            }
        ],
        "total": 1
    }
}

失败返回示例

{
    "code": 3,
    "msg": "授权无效 authorization timestamp error",
    "data": []
}

错误处理

公共错误码

HTTP status code	错误码	错误信息	描述

注意事项

运输节点列表（events）按时间倒序排列，最新的节点（如签收）会显示在最前面

若订单尚未发货，list可能返回空数组或仅包含初始节点（如InfoReceived）

部分物流公司的节点信息可能存在延迟，建议间隔一段时间后再次查询

常见问题

Q1：如何判断物流是否已签收？

A：events数组中description包含"Delivered"信息。

Q2：物流单号存在，但查询不到轨迹信息是什么原因？

A：可能原因：1. 物流单号刚生成，物流公司尚未更新信息；2. 物流公司接口故障，暂时无法获取数据；3. 单号错误或已作废。建议1-2小时后再次查询。

Q3：events数组中的节点顺序是怎样的？

A：按时间倒序排列，即最新发生的节点在数组的最前面，方便快速查看最新状态。

版本历史

版本	日期	修改说明
v1.0	2025-03-15	初始版本，支持物流轨迹查询

application/json

Bodyapplication/json

示例

{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {
                "number": "xxx",
                "type": "订单物流",
                "logistics_company": "UniUni",
                "shipment_no": "xxxx",
                "events": [
                    {
                        "time_raw": "2025-07-30 13:29:04 ",
                        "description": "Las Vegas NV, Delivered"
                    },
                    {
                        "time_raw": "2025-07-30 07:45:52 ",
                        "description": "Las Vegas NV, Out for delivery"
                    },
                    {
                        "time_raw": "2025-07-30 07:21:37 ",
                        "description": "Las Vegas NV, Arrival scan"
                    },
                    {
                        "time_raw": "2025-07-29 23:11:24 ",
                        "description": "Los Angeles CA, Gateway transit out"
                    },
                    {
                        "time_raw": "2025-07-28 22:34:57 ",
                        "description": "Los Angeles CA, Gateway transit in"
                    },
                    {
                        "time_raw": "2025-07-28 09:39:51 ",
                        "description": "UNI DATA CENTER, Order received"
                    }
                ]
            }
        ],
        "total": 1
    }
}

订单物流轨迹

订单物流轨迹

适用场景

接口类型

请求频率限制

请求说明

请求参数

Header参数

Body参数

响应字段说明

调用示例

URL请求

请求示例

成功返回示例

失败返回示例

错误处理

注意事项

常见问题

Q1：如何判断物流是否已签收？

Q2：物流单号存在，但查询不到轨迹信息是什么原因？

Q3：events数组中的节点顺序是怎样的？

版本历史

请求参数

请求示例代码

返回响应

订单物流轨迹

订单物流轨迹#

适用场景#

接口类型#

请求频率限制#

请求说明#

请求参数#

Header参数#

Body参数#

响应字段说明#

调用示例#

URL请求#

请求示例#

成功返回示例#

失败返回示例#

错误处理#

注意事项#

常见问题#

Q1：如何判断物流是否已签收？#

Q2：物流单号存在，但查询不到轨迹信息是什么原因？#

Q3：events数组中的节点顺序是怎样的？#

版本历史#

请求参数

请求示例代码

返回响应

订单物流轨迹

适用场景

接口类型

请求频率限制

请求说明

请求参数

Header参数

Body参数

响应字段说明

调用示例

URL请求

请求示例

成功返回示例

失败返回示例

错误处理

注意事项

常见问题

Q1：如何判断物流是否已签收？

Q2：物流单号存在，但查询不到轨迹信息是什么原因？

Q3：events数组中的节点顺序是怎样的？

版本历史