公共参数

本文档说明智能采购平台 API 中所有接口共用的请求参数和响应参数。

请求参数

公共请求头

所有 API 请求都需要在 HTTP 请求头中包含以下参数：

参数名	类型	必填	说明	示例
`X-App-Id`	string	是	应用标识符，从控制台获取	`dev_app_local`
`X-Timestamp`	string	是	当前时间戳（毫秒），用于防重放攻击	`1708851000000`
`X-Signature`	string	是	请求签名，使用 HMAC-SHA256 算法计算	`abc123...`
`Content-Type`	string	条件	有请求体时必填，固定为 `application/json`	`application/json`

签名计算

签名用于验证请求的合法性和完整性。计算方法：


signature = HMAC-SHA256(
  appSecret,
  METHOD + PATH + TIMESTAMP + BODY
)

参数说明：

METHOD - HTTP 方法（大写），如：GET、POST、PUT、DELETE
PATH - 请求路径（包含查询参数），如：/api/v1/intents?status=SUBMITTED
TIMESTAMP - 请求头中的时间戳值
BODY - 请求体的 JSON 字符串（GET 请求为空字符串）

代码示例：


import crypto from 'crypto';
 
function calculateSignature(
  method: string,
  path: string,
  timestamp: string,
  body: string,
  appSecret: string
): string {
  const signString = `${method}${path}${timestamp}${body}`;
  
  return crypto
    .createHmac('sha256', appSecret)
    .update(signString)
    .digest('hex');
}
 
// 示例
const signature = calculateSignature(
  'POST',
  '/api/v1/intents',
  '1708851000000',
  '{"userId":"user_001","platform":"TAOBAO"}',
  'your_app_secret'
);

时间戳要求

格式：Unix 时间戳（毫秒）
有效期：与服务器时间相差不超过 5 分钟

生成方式：


const timestamp = Date.now().toString();

请求限制

限制项	说明	限制值
请求频率	单个 App ID 的 QPS 限制	100 次/秒
请求体大小	POST/PUT 请求体最大尺寸	1 MB
URL 长度	GET 请求 URL 最大长度	8192 字符
超时时间	单个请求的最长处理时间	30 秒

响应参数

公共响应头

参数名	类型	说明	示例
`Content-Type`	string	响应内容类型	`application/json; charset=utf-8`
`X-Request-Id`	string	请求追踪 ID，用于问题排查	`req_1708851000000_abc123`
`X-RateLimit-Limit`	number	速率限制上限	`100`
`X-RateLimit-Remaining`	number	剩余请求次数	`95`
`X-RateLimit-Reset`	number	速率限制重置时间（Unix 时间戳）	`1708851060`

标准响应格式

所有 API 接口均返回统一格式的 JSON 响应：


interface ApiResponse<T> {
  code: number;        // 业务状态码，0 表示成功
  message: string;     // 响应消息，成功为"操作成功"
  data: T | null;      // 响应数据，类型根据接口而定
}

成功响应示例：


{
  "code": 0,
  "message": "操作成功",
  "data": {
    "id": "intent_123",
    "status": "SUBMITTED"
  }
}

失败响应示例：


{
  "code": 40001,
  "message": "请求参数错误",
  "data": {
    "field": "price",
    "reason": "价格必须大于0"
  }
}

HTTP 状态码

状态码	说明	业务含义
`200`	OK	请求成功
`201`	Created	资源创建成功
`204`	No Content	删除成功，无返回内容
`400`	Bad Request	请求参数错误
`401`	Unauthorized	认证失败（签名错误、时间戳过期等）
`403`	Forbidden	权限不足或 IP 不在白名单
`404`	Not Found	请求的资源不存在
`409`	Conflict	资源状态冲突（如重复创建）
`429`	Too Many Requests	请求频率超限
`500`	Internal Server Error	服务器内部错误
`503`	Service Unavailable	服务暂时不可用

业务状态码

业务状态码（code 字段）用于表示具体的业务处理结果：

状态码	说明	HTTP 状态
`0`	操作成功	200/201
`40001`	请求参数错误	400
`40002`	必填参数缺失	400
`40003`	参数格式错误	400
`40101`	签名验证失败	401
`40102`	时间戳过期	401
`40103`	App ID 不存在	401
`40301`	IP 不在白名单	403
`40302`	权限不足	403
`40401`	资源不存在	404
`40901`	资源已存在	409
`40902`	状态冲突	409
`42901`	请求频率超限	429
`50001`	服务器内部错误	500
`50301`	服务暂时不可用	503

详细错误码说明请参考错误码文档。

分页参数

对于支持分页的接口（如查询列表），使用以下标准分页参数：

请求参数

参数名	类型	必填	说明	默认值	示例
`page`	number	否	页码，从 1 开始	`1`	`1`
`pageSize`	number	否	每页数量	`20`	`10`
`sortBy`	string	否	排序字段	`createdAt`	`updatedAt`
`sortOrder`	string	否	排序方向：`asc` 或 `desc`	`desc`	`asc`

响应格式

分页接口的响应数据格式：


interface PaginatedResponse<T> {
  items: T[];           // 当前页数据
  total: number;        // 总记录数
  page: number;         // 当前页码
  pageSize: number;     // 每页数量
  totalPages: number;   // 总页数
}

示例：


{
  "code": 0,
  "message": "操作成功",
  "data": {
    "items": [
      { "id": "intent_001", "status": "SUBMITTED" },
      { "id": "intent_002", "status": "PROCESSING" }
    ],
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

过滤参数

支持查询条件的接口可以使用以下过滤参数：

通用过滤器

参数名	类型	说明	示例
`filter[field]`	string	字段值精确匹配	`filter[status]=SUBMITTED`
`filter[field][in]`	string	字段值在列表中	`filter[status][in]=SUBMITTED,PROCESSING`
`filter[field][gte]`	string	字段值大于等于	`filter[price][gte]=100`
`filter[field][lte]`	string	字段值小于等于	`filter[price][lte]=1000`
`filter[field][like]`	string	字段值模糊匹配	`filter[title][like]=iPhone`

时间范围过滤

参数名	类型	说明	示例
`startTime`	string	开始时间（ISO 8601）	`2026-02-01T00:00:00Z`
`endTime`	string	结束时间（ISO 8601）	`2026-02-28T23:59:59Z`

示例请求：


GET /api/v1/intents?filter[status][in]=SUBMITTED,PROCESSING&filter[price][gte]=100&startTime=2026-02-01T00:00:00Z

字段选择

某些接口支持通过 fields 参数选择返回的字段，减少数据传输量：


GET /api/v1/intents?fields=id,status,createdAt

返回结果将只包含指定的字段：


{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": "intent_001",
      "status": "SUBMITTED",
      "createdAt": "2026-02-25T10:00:00Z"
    }
  ]
}

请求示例

GET 请求


curl -X GET "https://api.procure-core.com/api/v1/intents?page=1&pageSize=10" \
  -H "X-App-Id: your_app_id" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: calculated_signature"

POST 请求


curl -X POST "https://api.procure-core.com/api/v1/intents" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: your_app_id" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: calculated_signature" \
  -d '{
    "userId": "user_001",
    "platform": "TAOBAO",
    "productUrl": "https://item.taobao.com/item.htm?id=123456"
  }'

PUT 请求


curl -X PUT "https://api.procure-core.com/api/v1/intents/intent_123" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: your_app_id" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: calculated_signature" \
  -d '{
    "status": "CANCELLED"
  }'

DELETE 请求


curl -X DELETE "https://api.procure-core.com/api/v1/intents/intent_123" \
  -H "X-App-Id: your_app_id" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: calculated_signature"

调试技巧

1. 查看请求追踪 ID

所有响应都包含 X-Request-Id 响应头，在报告问题时请提供此 ID：


curl -i https://api.procure-core.com/api/v1/intents
# 响应头中：X-Request-Id: req_1708851000000_abc123

2. 验证签名

使用以下工具验证签名计算是否正确：


# 使用项目中的签名验证工具
cd apps/api
node generate-signature.ts

3. 检查速率限制

通过响应头查看当前速率限制状态：


curl -i https://api.procure-core.com/api/v1/intents
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1708851060

公共参数

请求参数

公共请求头

签名计算

时间戳要求

请求限制

响应参数

公共响应头

标准响应格式

HTTP 状态码

业务状态码

分页参数

请求参数

响应格式

过滤参数

通用过滤器

时间范围过滤

字段选择

请求示例

GET 请求

POST 请求

PUT 请求

DELETE 请求

调试技巧

1. 查看请求追踪 ID

2. 验证签名

3. 检查速率限制

相关文档