GET /api/v1/intents
查询采购意图列表，支持分页和筛选。
接口说明
- 需要认证 - 需要提供签名请求头
- 用途 - 获取采购意图列表，支持按状态、用户等条件筛选
- 分页 - 支持分页查询，默认每页 20 条
请求头
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
X-App-Id | string | 是 | 应用 ID |
X-Timestamp | string | 是 | 请求时间戳（毫秒） |
X-Signature | string | 是 | 请求签名 |
请求参数（Query Parameters）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | number | 否 | 页码，从 1 开始，默认 1 |
pageSize | number | 否 | 每页数量，默认 20，最大 100 |
status | string | 否 | 按状态筛选：DRAFT / SUBMITTED / PROCESSING / COMPLETED / FAILED / CANCELLED |
userId | string | 否 | 按用户 ID 筛选 |
platform | string | 否 | 按平台筛选：TAOBAO / JD / PDD |
startDate | string | 否 | 开始日期筛选，ISO 8601 格式 |
endDate | string | 否 | 结束日期筛选，ISO 8601 格式 |
sortBy | string | 否 | 排序字段：createdAt / updatedAt / price，默认 createdAt |
order | string | 否 | 排序方向：asc / desc，默认 desc |
请求示例
基础查询
curl -X GET "https://api.procure-core.com/api/v1/intents?page=1&pageSize=10" \
-H "X-App-Id: dev_app_local" \
-H "X-Timestamp: 1708851000000" \
-H "X-Signature: abc123..."按状态筛选
curl -X GET "https://api.procure-core.com/api/v1/intents?status=SUBMITTED&page=1&pageSize=20" \
-H "X-App-Id: dev_app_local" \
-H "X-Timestamp: 1708851000000" \
-H "X-Signature: abc123..."按用户筛选
curl -X GET "https://api.procure-core.com/api/v1/intents?userId=user_001" \
-H "X-App-Id: dev_app_local" \
-H "X-Timestamp: 1708851000000" \
-H "X-Signature: abc123..."组合筛选
curl -X GET "https://api.procure-core.com/api/v1/intents?userId=user_001&status=SUBMITTED&platform=TAOBAO&sortBy=createdAt&order=desc" \
-H "X-App-Id: dev_app_local" \
-H "X-Timestamp: 1708851000000" \
-H "X-Signature: abc123..."TypeScript / JavaScript
import { ProcureClient } from '@procure-core/sdk';
const client = new ProcureClient({
appId: 'your_app_id',
appSecret: 'your_app_secret',
baseURL: 'https://api.procure-core.com'
});
// 基础查询
const intents = await client.intents.list({
page: 1,
pageSize: 10
});
// 按状态筛选
const submittedIntents = await client.intents.list({
status: 'SUBMITTED',
page: 1,
pageSize: 20
});
// 按用户筛选
const userIntents = await client.intents.list({
userId: 'user_001',
sortBy: 'createdAt',
order: 'desc'
});Python
from procure_core import ProcureClient
client = ProcureClient(
app_id='your_app_id',
app_secret='your_app_secret',
base_url='https://api.procure-core.com'
)
# 基础查询
intents = client.intents.list(page=1, page_size=10)
# 按状态筛选
submitted_intents = client.intents.list(status='SUBMITTED', page=1, page_size=20)
# 按用户筛选
user_intents = client.intents.list(user_id='user_001', sort_by='createdAt', order='desc')响应参数
| 参数 | 类型 | 说明 |
|---|---|---|
code | number | 状态码，0 表示成功 |
message | string | 响应消息 |
data.items | array | 意图列表 |
data.total | number | 总记录数 |
data.page | number | 当前页码 |
data.pageSize | number | 每页数量 |
data.totalPages | number | 总页数 |
data.items 中每个对象的结构
| 参数 | 类型 | 说明 |
|---|---|---|
id | string | 采购意图 ID |
userId | string | 用户 ID |
platform | string | 电商平台 |
title | string | 商品标题 |
price | number | 商品单价 |
quantity | number | 采购数量 |
totalAmount | number | 总金额 |
status | string | 当前状态 |
createdAt | string | 创建时间 |
updatedAt | string | 更新时间 |
响应示例
成功响应
{
"code": 0,
"message": "操作成功",
"data": {
"items": [
{
"id": "intent_001",
"userId": "user_001",
"platform": "TAOBAO",
"title": "Apple iPhone 15 Pro 256GB",
"price": 8999,
"quantity": 1,
"totalAmount": 8999,
"status": "SUBMITTED",
"createdAt": "2026-02-25T10:00:00.000Z",
"updatedAt": "2026-02-25T10:00:00.000Z"
},
{
"id": "intent_002",
"userId": "user_001",
"platform": "JD",
"title": "MacBook Pro 14英寸 M3",
"price": 14999,
"quantity": 1,
"totalAmount": 14999,
"status": "PROCESSING",
"createdAt": "2026-02-24T15:30:00.000Z",
"updatedAt": "2026-02-25T09:00:00.000Z"
}
],
"total": 42,
"page": 1,
"pageSize": 10,
"totalPages": 5
}
}空结果响应
{
"code": 0,
"message": "操作成功",
"data": {
"items": [],
"total": 0,
"page": 1,
"pageSize": 10,
"totalPages": 0
}
}使用场景
1. 分页加载
async function loadAllIntents() {
const allIntents = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const response = await client.intents.list({ page, pageSize: 50 });
allIntents.push(...response.data.items);
hasMore = page < response.data.totalPages;
page++;
}
return allIntents;
}2. 状态监控
// 监控处理中的意图
const processingIntents = await client.intents.list({
status: 'PROCESSING',
sortBy: 'createdAt',
order: 'asc'
});
console.log(`当前有 ${processingIntents.data.total} 个意图正在处理`);3. 用户订单历史
// 获取用户的采购历史
async function getUserPurchaseHistory(userId: string) {
return await client.intents.list({
userId,
sortBy: 'createdAt',
order: 'desc',
pageSize: 50
});
}4. 日期范围查询
// 查询本月的采购意图
const startOfMonth = new Date(2026, 1, 1).toISOString();
const endOfMonth = new Date(2026, 2, 0).toISOString();
const monthlyIntents = await client.intents.list({
startDate: startOfMonth,
endDate: endOfMonth,
sortBy: 'createdAt',
order: 'desc'
});常见错误
| 错误码 | 错误消息 | 解决方案 |
|---|---|---|
| 40001 | 参数验证失败 | 检查分页参数是否合法 |
| 40101 | 签名验证失败 | 检查签名算法和密钥 |
| 42901 | 请求过于频繁 | 降低请求频率 |
性能优化建议
- 合理设置 pageSize - 根据需求设置合适的每页数量，避免过大或过小
- 使用筛选条件 - 优先使用状态、用户等筛选条件减少数据量
- 避免深度分页 - 深度分页性能较差，建议使用游标分页（未来版本支持）
- 缓存策略 - 对于变化不频繁的数据可以客户端缓存
注意事项
- pageSize 限制 - 最大 100 条/页，超过会自动调整为 100
- 排序字段 - 仅支持 createdAt、updatedAt、price 三个字段
- 日期格式 - 必须使用 ISO 8601 格式
- 速率限制 - 100 次/秒（单个 App ID）