本文详解如何使用 Shopware Admin API 的 /api/search/order 接口，结合 range 类型过滤器精准查询过去 N 小时内创建的订单，并提供可直接运行的请求示例与关键注意事项。
本文详解如何使用 shopware admin api 的 `/api/search/order` 接口，结合 `range` 类型过滤器精准查询过去 n 小时内创建的订单，并提供可直接运行的请求示例与关键注意事项。
Shopware Admin API 不支持直接传入“过去 24 小时”这类相对时间表达式，但可通过标准 ISO 8601 时间格式的 range 过滤器实现精确时间范围筛选。核心在于向 /api/search/order 发送 POST 请求，并在请求体中构造符合规范的 filter 数组。
✅ 正确的请求结构示例（获取过去 6 小时内的订单）
POST https://your-shop-url.com/api/search/order
Authorization: Bearer <your-admin-api-token>
Content-Type: application/json
{
"filter": [
{
"type": "range",
"field": "createdAt",
"parameters": {
"gte": "2024-06-15T10:30:00.000+00:00",
"lte": "2024-06-15T16:30:00.000+00:00"
}
}
],
"limit": 100,
"page": 1
}⚠️ 注意：gte（greater than or equal）和 lte（less than or equal）需同时设置以限定闭区间；时间必须为 UTC 格式（推荐带 +00:00 时区偏移），避免因服务器时区导致漏单。
? 动态生成时间范围（推荐实践）
实际开发中，建议用代码动态计算时间边界。例如 Node.js 中：
const now = new Date();
const sixHoursAgo = new Date(now.getTime() - 6 * 60 * 60 * 1000);
const formatISO = (d) => d.toISOString().slice(0, 23) + '+00:00';
const payload = {
filter: [{
type: 'range',
field: 'createdAt',
parameters: {
gte: formatISO(sixHoursAgo),
lte: formatISO(now)
}
}],
limit: 50
};Python 示例（使用 datetime 和 timezone.utc）：
from datetime import datetime, timedelta, timezone
now = datetime.now(timezone.utc)
six_hours_ago = now - timedelta(hours=6)
payload = {
"filter": [{
"type": "range",
"field": "createdAt",
"parameters": {
"gte": six_hours_ago.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00",
"lte": now.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00"
}
}],
"limit": 50
}? 关键注意事项
- 认证必需：所有 Admin API 请求必须携带有效的 Bearer Token（通过 /api/oauth/token 获取，作用域需含 read:order）；
- 字段名严格区分大小写：createdAt 是 Shopware 6 的标准字段名，不可写作 created_at 或 createdat；
- 性能优化：对大订单量店铺，建议配合 limit + page 分页，避免超时或内存溢出；
- 索引影响：确保数据库中 order.created_at 字段已建立索引（Shopware 默认已建），否则范围查询可能显著变慢；
- 空结果排查：若返回空数组，请验证时间格式是否合法（如空格、冒号间距错误）、时区是否一致、以及订单是否确实处于该时间段内。
通过合理构造 range 过滤器并动态生成时间戳，即可稳定、高效地拉取任意历史窗口内的订单数据，适用于监控告警、报表同步、第三方系统对接等典型场景。
