Skip to Content
API 参考API 接口更新采购意图

PUT /api/v1/intents/{id}

更新采购意图的部分信息。

接口说明

  • 需要认证 - 需要提供签名请求头
  • 用途 - 修改采购意图的可变信息
  • 限制 - 仅能更新 DRAFT 和 SUBMITTED 状态的意图

请求头

参数类型必填说明
Content-Typestring是固定值：application/json
X-App-Idstring是应用 ID
X-Timestampstring是请求时间戳（毫秒）
X-Signaturestring是请求签名

路径参数

参数类型必填说明
idstring是采购意图 ID

请求参数

所有参数均为可选，仅提交需要更新的字段：

参数类型说明
quantitynumber采购数量，必须为正整数
recipientNamestring收货人姓名，2-50 个字符
addressstring收货详细地址，5-200 个字符
phonestring收货人联系电话，11 位手机号码
remarksstring备注信息，最长 500 字符

不可更新的字段：

  • userId - 用户 ID
  • platform - 电商平台
  • productUrl - 商品链接
  • title - 商品标题
  • price - 商品单价

请求示例

更新数量

curl -X PUT "https://api.procure-core.com/api/v1/intents/intent_67890" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: dev_app_local" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: abc123..." \
  -d '{
    "quantity": 2
  }'

更新收货信息

curl -X PUT "https://api.procure-core.com/api/v1/intents/intent_67890" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: dev_app_local" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: abc123..." \
  -d '{
    "recipientName": "李四",
    "address": "上海市浦东新区陆家嘴环路1000号",
    "phone": "13900139000"
  }'

更新备注

curl -X PUT "https://api.procure-core.com/api/v1/intents/intent_67890" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: dev_app_local" \
  -H "X-Timestamp: 1708851000000" \
  -H "X-Signature: abc123..." \
  -d '{
    "remarks": "请在周末送达，需要本人签收"
  }'

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'
});
 
// 更新数量
await client.intents.update('intent_67890', {
  quantity: 2
});
 
// 更新收货信息
await client.intents.update('intent_67890', {
  recipientName: '李四',
  address: '上海市浦东新区陆家嘴环路1000号',
  phone: '13900139000'
});
 
// 批量更新
await client.intents.update('intent_67890', {
  quantity: 3,
  remarks: '请在周末送达，需要本人签收'
});

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'
)
 
# 更新数量
client.intents.update('intent_67890', quantity=2)
 
# 更新收货信息
client.intents.update(
    'intent_67890',
    recipient_name='李四',
    address='上海市浦东新区陆家嘴环路1000号',
    phone='13900139000'
)
 
# 批量更新
client.intents.update(
    'intent_67890',
    quantity=3,
    remarks='请在周末送达，需要本人签收'
)

响应参数

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

data 对象结构

返回完整的意图对象，参考 查询意图详情 接口的响应结构。

响应示例

成功响应

{
  "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": 2,
    "totalAmount": 17998,
    "recipientName": "张三",
    "address": "北京市朝阳区望京SOHO T1 1001",
    "phone": "13800138000",
    "remarks": "请在工作日送达",
    "status": "SUBMITTED",
    "createdAt": "2026-02-25T10:30:00.000Z",
    "updatedAt": "2026-02-25T11:00:00.000Z"
  }
}

错误响应

意图不存在

状态码： 404 Not Found

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

状态不允许更新

状态码： 400 Bad Request

{
  "code": 40002,
  "message": "当前状态不允许更新",
  "data": {
    "currentStatus": "PROCESSING",
    "allowedStatuses": ["DRAFT", "SUBMITTED"]
  }
}

参数验证失败

状态码： 400 Bad Request

{
  "code": 40001,
  "message": "参数验证失败",
  "data": {
    "errors": [
      {
        "field": "quantity",
        "message": "数量必须为正整数"
      }
    ]
  }
}

使用场景

1. 修改采购数量

// 用户增加采购数量
async function increaseQuantity(intentId: string, additionalQuantity: number) {
  const intent = await client.intents.get(intentId);
  
  if (!['DRAFT', 'SUBMITTED'].includes(intent.status)) {
    throw new Error('当前状态不允许修改数量');
  }
  
  return await client.intents.update(intentId, {
    quantity: intent.quantity + additionalQuantity
  });
}

2. 更新收货地址

// 用户修改收货地址
async function updateShippingAddress(intentId: string, newAddress: {
  recipientName: string;
  address: string;
  phone: string;
}) {
  return await client.intents.update(intentId, newAddress);
}

3. 添加备注

// 添加或更新备注信息
async function addRemarks(intentId: string, remarks: string) {
  return await client.intents.update(intentId, { remarks });
}

4. 批量字段更新

// 一次性更新多个字段
async function batchUpdate(intentId: string, updates: {
  quantity?: number;
  recipientName?: string;
  address?: string;
  phone?: string;
  remarks?: string;
}) {
  // 移除 undefined 的字段
  const validUpdates = Object.fromEntries(
    Object.entries(updates).filter(([_, v]) => v !== undefined)
  );
  
  return await client.intents.update(intentId, validUpdates);
}

状态限制

状态是否可更新说明
DRAFT✅ 是草稿状态，所有字段都可更新
SUBMITTED✅ 是已提交，仅收货信息和备注可更新
PROCESSING❌ 否处理中，不可更新
COMPLETED❌ 否已完成，不可更新
FAILED❌ 否已失败，不可更新
CANCELLED❌ 否已取消，不可更新

常见错误

错误码错误消息解决方案
40001参数验证失败检查参数格式是否正确
40002当前状态不允许更新检查意图当前状态
40401采购意图不存在检查意图 ID 是否正确
40301无权访问该资源确认该意图属于当前 App
40101签名验证失败检查签名算法和密钥

注意事项

  1. 部分更新 - 只会更新提交的字段，未提交的字段保持不变
  2. 状态限制 - PROCESSING 及之后的状态不可更新
  3. 总金额自动计算 - 更新数量后，totalAmount 会自动重新计算
  4. 并发控制 - 使用乐观锁机制，并发更新可能失败
  5. 速率限制 - 20 次/秒（单个 App ID）

最佳实践

  1. 更新前检查 - 先查询当前状态，确认可以更新
  2. 最小更新 - 只更新必要的字段，减少冲突
  3. 错误处理 - 妥善处理状态不允许更新的情况
  4. 用户提示 - 更新前向用户确认，提供清晰的提示

相关接口

查询意图详情取消采购意图