Skip to Content
API 参考API 接口查询意图详情

GET /api/v1/intents/{id}

查询单个采购意图的完整详细信息。

接口说明

  • 需要认证 - 需要提供签名请求头
  • 用途 - 获取采购意图的完整信息，包括所有字段和处理状态
  • 权限 - 仅能查询自己 App 创建的意图

请求头

参数类型必填说明
X-App-Idstring是应用 ID
X-Timestampstring是请求时间戳（毫秒）
X-Signaturestring是请求签名

路径参数

参数类型必填说明
idstring是采购意图 ID，如：intent_67890

请求示例

cURL

curl -X GET "https://api.procure-core.com/api/v1/intents/intent_67890" \
  -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 intent = await client.intents.get('intent_67890');
 
console.log('意图状态:', intent.status);
console.log('商品标题:', intent.title);
console.log('总金额:', intent.totalAmount);

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'
)
 
intent = client.intents.get('intent_67890')
 
print(f'意图状态: {intent.status}')
print(f'商品标题: {intent.title}')
print(f'总金额: {intent.total_amount}')

响应参数

参数类型说明
codenumber状态码，0 表示成功
messagestring响应消息
dataobject意图详细信息

data 对象结构

参数类型说明
idstring采购意图 ID
userIdstring用户 ID
platformstring电商平台：TAOBAO / JD / PDD
productUrlstring商品原始链接
titlestring商品标题
pricenumber商品单价（元）
quantitynumber采购数量
totalAmountnumber总金额（元）
recipientNamestring收货人姓名
addressstring收货详细地址
phonestring收货人联系电话
remarksstring备注信息
statusstring状态：DRAFT / SUBMITTED / PROCESSING / COMPLETED / FAILED / CANCELLED
statusMessagestring状态说明
failureReasonstring失败原因（仅在 status 为 FAILED 时存在）
trackingNumberstring物流单号（仅在有物流信息时存在）
trackingCompanystring物流公司（仅在有物流信息时存在）
orderIdstring电商平台订单号（仅在下单成功后存在）
createdAtstring创建时间（ISO 8601 格式）
updatedAtstring更新时间（ISO 8601 格式）
submittedAtstring提交时间（ISO 8601 格式）
completedAtstring完成时间（ISO 8601 格式，仅在完成时存在）

响应示例

处理中的意图

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "id": "intent_67890",
    "userId": "user_001",
    "platform": "TAOBAO",
    "productUrl": "https://item.taobao.com/item.htm?id=123456",
    "title": "Apple iPhone 15 Pro 256GB",
    "price": 8999,
    "quantity": 1,
    "totalAmount": 8999,
    "recipientName": "张三",
    "address": "北京市朝阳区望京SOHO T1 1001",
    "phone": "13800138000",
    "remarks": "请在工作日送达",
    "status": "PROCESSING",
    "statusMessage": "正在处理采购订单",
    "createdAt": "2026-02-25T10:30:00.000Z",
    "updatedAt": "2026-02-25T10:35:00.000Z",
    "submittedAt": "2026-02-25T10:30:00.000Z"
  }
}

已完成的意图

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "id": "intent_67890",
    "userId": "user_001",
    "platform": "TAOBAO",
    "productUrl": "https://item.taobao.com/item.htm?id=123456",
    "title": "Apple iPhone 15 Pro 256GB",
    "price": 8999,
    "quantity": 1,
    "totalAmount": 8999,
    "recipientName": "张三",
    "address": "北京市朝阳区望京SOHO T1 1001",
    "phone": "13800138000",
    "remarks": "请在工作日送达",
    "status": "COMPLETED",
    "statusMessage": "采购订单已完成",
    "orderId": "TB2026022512345678",
    "trackingNumber": "SF1234567890",
    "trackingCompany": "顺丰速运",
    "createdAt": "2026-02-25T10:30:00.000Z",
    "updatedAt": "2026-02-26T15:20:00.000Z",
    "submittedAt": "2026-02-25T10:30:00.000Z",
    "completedAt": "2026-02-26T15:20:00.000Z"
  }
}

失败的意图

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "id": "intent_67890",
    "userId": "user_001",
    "platform": "TAOBAO",
    "productUrl": "https://item.taobao.com/item.htm?id=123456",
    "title": "Apple iPhone 15 Pro 256GB",
    "price": 8999,
    "quantity": 1,
    "totalAmount": 8999,
    "recipientName": "张三",
    "address": "北京市朝阳区望京SOHO T1 1001",
    "phone": "13800138000",
    "status": "FAILED",
    "statusMessage": "采购失败",
    "failureReason": "商品已下架",
    "createdAt": "2026-02-25T10:30:00.000Z",
    "updatedAt": "2026-02-25T11:00:00.000Z",
    "submittedAt": "2026-02-25T10:30:00.000Z"
  }
}

错误响应

意图不存在

状态码： 404 Not Found

{
  "code": 40401,
  "message": "采购意图不存在",
  "data": null
}

无权访问

状态码： 403 Forbidden

{
  "code": 40301,
  "message": "无权访问该资源",
  "data": null
}

使用场景

1. 轮询查询状态

async function waitForCompletion(intentId: string, timeout = 300000) {
  const startTime = Date.now();
  
  while (Date.now() - startTime < timeout) {
    const intent = await client.intents.get(intentId);
    
    if (intent.status === 'COMPLETED') {
      console.log('采购完成！');
      return intent;
    }
    
    if (intent.status === 'FAILED') {
      throw new Error(`采购失败: ${intent.failureReason}`);
    }
    
    // 等待 5 秒后再次查询
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
  
  throw new Error('查询超时');
}

2. 获取物流信息

async function getTrackingInfo(intentId: string) {
  const intent = await client.intents.get(intentId);
  
  if (intent.trackingNumber) {
    return {
      number: intent.trackingNumber,
      company: intent.trackingCompany,
      url: `https://tracking.example.com/${intent.trackingNumber}`
    };
  }
  
  return null;
}

3. 状态展示

function getStatusDisplay(status: string): { text: string; color: string } {
  const statusMap = {
    DRAFT: { text: '草稿', color: 'gray' },
    SUBMITTED: { text: '已提交', color: 'blue' },
    PROCESSING: { text: '处理中', color: 'yellow' },
    COMPLETED: { text: '已完成', color: 'green' },
    FAILED: { text: '失败', color: 'red' },
    CANCELLED: { text: '已取消', color: 'gray' }
  };
  
  return statusMap[status] || { text: '未知', color: 'gray' };
}
 
const intent = await client.intents.get('intent_67890');
const display = getStatusDisplay(intent.status);
console.log(`状态: ${display.text} (${display.color})`);

状态说明

状态说明可执行操作
DRAFT草稿更新、删除、提交
SUBMITTED已提交取消、查询
PROCESSING处理中取消、查询
COMPLETED已完成查询
FAILED失败查询、删除
CANCELLED已取消查询、删除

常见错误

错误码错误消息解决方案
40401采购意图不存在检查意图 ID 是否正确
40301无权访问该资源确认该意图属于当前 App
40101签名验证失败检查签名算法和密钥
42901请求过于频繁降低轮询频率

性能优化建议

  1. 轮询间隔 - 建议设置合理的轮询间隔（5-10 秒）
  2. Webhook 通知 - 建议使用 Webhook 接收状态变更通知（未来版本支持）
  3. 缓存策略 - 对已完成的意图可以进行缓存

注意事项

  1. 权限控制 - 只能查询自己 App 创建的意图
  2. 速率限制 - 100 次/秒（单个 App ID）
  3. 敏感信息 - 手机号等敏感信息会部分脱敏显示

相关接口

查询意图列表更新采购意图