本文详解如何利用 Shopware Admin API 的 /api/search/order 接口，通过时间范围过滤（range filter）精准获取过去 X 小时内创建的订单，涵盖请求结构、时间格式规范、动态时间计算及完整示例。
本文详解如何利用 shopware admin api 的 `/api/search/order` 接口，通过时间范围过滤（range filter）精准获取过去 x 小时内创建的订单，涵盖请求结构、时间格式规范、动态时间计算及完整示例。
Shopware Admin API 不支持直接传入“过去 24 小时”这类相对时间参数，但可通过标准的 range 过滤器结合 ISO 8601 格式的 createdAt 字段实现精确时间窗口查询。核心在于构造符合 OpenSearch 兼容语法的 JSON filter，并将其嵌入 /api/search/order 的 POST 请求体中。
✅ 正确的过滤器结构
以下为获取「过去 6 小时内创建的订单」的完整请求示例（含认证头）：
curl -X POST 'https://your-shop.com/api/search/order' \
-H 'Authorization: Bearer <your-admin-api-token>' \
-H 'Content-Type: application/json' \
-d '{
"filter": [
{
"type": "range",
"field": "createdAt",
"parameters": {
"gte": "2024-06-15T08:00:00.000+00:00",
"lte": "2024-06-15T14:00:00.000+00:00"
}
}
],
"limit": 100
}'? 关键说明：
- gte（greater than or equal）表示起始时间（含），lte（less than or equal）表示截止时间（含）；
- 时间必须为 ISO 8601 格式，且强烈建议带 UTC 时区偏移（如 +00:00），避免因服务器时区差异导致漏单；
- createdAt 是订单实体的标准时间字段，区分大小写，不可写作 createdat 或 created_at。
⏱ 动态生成时间范围（推荐实践）
在实际开发中，应使用服务端逻辑动态计算时间范围。例如 Node.js 示例：
const now = new Date();
const sixHoursAgo = new Date(now.getTime() - 6 * 60 * 60 * 1000);
const formatISO = (date) => date.toISOString().replace(/\.\d{3}/, ''); // 去掉毫秒后三位，保持兼容性
const filter = {
filter: [{
type: 'range',
field: 'createdAt',
parameters: {
gte: `${formatISO(sixHoursAgo)}+00:00`,
lte: `${formatISO(now)}+00:00`
}
}],
limit: 250
};Python（requests）示例：
from datetime import datetime, timedelta
import requests
now = datetime.utcnow()
since = now - timedelta(hours=24)
payload = {
"filter": [{
"type": "range",
"field": "createdAt",
"parameters": {
"gte": since.strftime("%Y-%m-%dT%H:%M:%S") + ".000+00:00",
"lte": now.strftime("%Y-%m-%dT%H:%M:%S") + ".000+00:00"
}
}],
"limit": 500
}
response = requests.post(
"https://your-shop.com/api/search/order",
headers={"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"},
json=payload
)⚠ 注意事项与最佳实践
- 必填认证头：Admin API 要求有效的 Bearer Token，需通过 /api/oauth/token 获取（scope admin）；
- 分页处理：单次请求默认返回最多 100 条，若订单量大，请配合 page 和 limit 参数实现分页；
- 性能提示：对 createdAt 字段的 range 查询已优化索引，但跨数月或数年的大范围查询仍可能影响响应速度，建议按天/小时分段拉取；
- 错误排查：若返回空结果，请检查：① 时间格式是否含非法空格（如 "2021-01-17T12: 00: 00" 中的空格）；② Token 是否过期或权限不足；③ 商城是否启用订单同步延迟（如异步订单创建场景）。
掌握此方法后，你可灵活构建定时任务、BI 数据同步或运营看板，稳定获取任意时间粒度的订单快照——这是 Shopware 自动化集成的关键基础能力。
