API 参考文档
欢迎使用智能采购意图平台 API 参考文档。本文档提供完整的 API 接口规范,帮助您快速集成智能采购平台到企业系统中。
文档导航
🚀 快速入门
5 分钟快速接入 API,从申请凭证到完成第一次调用
🔐 认证鉴权
了解 HMAC-SHA256 签名认证机制和安全最佳实践
📋 公共参数
所有接口共用的请求头、响应格式和分页参数
📡 API 接口
完整的 API 接口列表,包含详细的参数和示例
🗂️ 数据结构
API 中使用的所有数据结构和枚举类型定义
⚠️ 错误码
完整的错误码列表和错误处理最佳实践
API 特性
RESTful 设计
遵循 REST架构规范,使用标准 HTTP 方法和状态码。
GET /api/v1/intents # 查询列表
POST /api/v1/intents # 创建资源
GET /api/v1/intents/{id} # 查询详情
PUT /api/v1/intents/{id} # 更新资源
DELETE /api/v1/intents/{id} # 删除资源JSON 数据格式
所有请求和响应均使用 JSON 格式,易于解析和使用。
{
"code": 0,
"message": "操作成功",
"data": {
"id": "intent_123",
"status": "SUBMITTED"
}
}HMAC-SHA256 认证
基于签名的安全认证机制,确保请求的合法性和完整性。
signature = HMAC-SHA256(
appSecret,
METHOD + PATH + TIMESTAMP + BODY
)标准化错误响应
统一的错误响应格式,包含详细的错误信息和处理建议。
{
"code": 40001,
"message": "请求参数错误",
"data": {
"field": "price",
"reason": "价格必须大于0"
}
}快速体验
健康检查(无需认证)
curl -X GET "https://api.procure-core.com/api/v1/health"创建采购意图
# 本地开发凭证
APP_ID="dev_app_local"
APP_SECRET="dev_secret_local_do_not_use_in_production"
# 生成签名并发送请求
curl -X POST "https://api.procure-core.com/api/v1/intents" \
-H "Content-Type: application/json" \
-H "X-App-Id: ${APP_ID}" \
-H "X-Timestamp: $(date +%s%3N)" \
-H "X-Signature: ${SIGNATURE}" \
-d '{
"userId": "user_001",
"platform": "TAOBAO",
"productUrl": "https://item.taobao.com/item.htm?id=123456",
"title": "测试商品",
"price": 99.99,
"quantity": 1,
"recipientName": "张三",
"address": "北京市朝阳区",
"phone": "13800138000"
}'详细的签名计算方法请参考 快速入门。
基础信息
| 项目 | 说明 |
|---|---|
| API 版本 | v1.0 |
| Base URL | https://api.procure-core.com |
| 测试环境 | https://api-test.procure-core.com |
| 协议 | HTTPS (TLS 1.3) |
| 数据格式 | JSON |
| 字符编码 | UTF-8 |
| 时区 | UTC |
| 认证方式 | HMAC-SHA256 签名 |
速率限制
| 接口类型 | QPS 限制 | 说明 |
|---|---|---|
| 健康检查 | 无限制 | 无需认证 |
| 创建接口 | 10/秒 | 单个 App ID |
| 查询接口 | 100/秒 | 单个 App ID |
| 更新/删除 | 20/秒 | 单个 App ID |
超出限制将返回 429 Too Many Requests 错误。
支持的平台
| 平台 | 标识 | 说明 |
|---|---|---|
| 淘宝 | TAOBAO | 淘宝网、天猫 |
| 京东 | JD | 京东商城 |
| 拼多多 | PDD | 拼多多 |
SDK 和工具
官方 SDK
# Node.js / TypeScript
npm install @procure-core/sdk
# Python
pip install procure-core-sdk
# Java
# Maven 依赖(即将支持)API 工具
- Postman Collection - 下载
- OpenAPI 规范 - openapi.json
- 签名生成工具 - 在项目
apps/api目录中
开发环境
本地开发凭证
仅用于开发测试,切勿在生产环境使用:
APP_ID="dev_app_local"
APP_SECRET="dev_secret_local_do_not_use_in_production"生产环境凭证
在 控制台 中申请:
- 创建应用
- 获取 App ID 和 App Secret
- 配置 IP 白名单
- 设置 Webhook 地址(可选)
版本历史
| 版本 | 发布日期 | 主要变更 |
|---|---|---|
| v1.0 | 2026-01-15 | 初始版本发布 |
| v1.1 | 2026-02-01 | 增加采购意图管理接口 |
相关文档
产品文档
技术文档
技术支持
获取帮助
- 📧 技术支持邮箱:support@procure-core.com
- 💬 开发者社区:GitHub Discussions
- 📝 问题反馈:GitHub Issues
- 📊 服务状态:status.procure-core.com
报告问题时请提供
- Request ID - 响应头中的
X-Request-Id - 错误码和错误消息
- 请求时间和请求参数(脱敏后)
- 复现步骤
安全建议
凭证管理
- ✅ 使用环境变量或密钥管理服务存储凭证
- ✅ 定期轮换 API 密钥
- ✅ 为不同环境使用不同的凭证
- ❌ 不要在代码中硬编码密钥
- ❌ 不要在公开仓库中提交密钥
网络安全
- ✅ 仅使用 HTTPS 协议
- ✅ 验证服务器 SSL 证书
- ✅ 配置 IP 白名单
- ✅ 实施请求速率限制
- ✅ 记录审计日志
数据安全
- ✅ 对敏感数据进行加密存储
- ✅ 最小化数据传输
- ✅ 定期备份重要数据
- ✅ 遵守数据保护法规
最佳实践
错误处理
async function apiCallWithRetry<T>(
fn: () => Promise<T>,
maxRetries = 3
): Promise<T> {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.code >= 50000 && i < maxRetries - 1) {
// 服务器错误,重试
await sleep(Math.pow(2, i) * 1000);
continue;
}
throw error;
}
}
}请求优化
- 使用批量接口减少请求次数
- 合理设置缓存策略
- 实施请求去重
- 使用 HTTP/2 提升性能
监控告警
- 监控 API 调用成功率
- 追踪响应时间
- 设置错误率告警
- 记录异常日志
开始使用
准备好开始了吗?
获取 OpenAPI 规范
完整的 OpenAPI 3.0 规范文档:
可以使用 Postman、Swagger UI 等工具导入 OpenAPI 规范进行接口测试。