扫码加入微信群科力普采购助手
帮助 AI Agent 在科力普 B2B 平台代用户完成「搜索 → 下单 → 查询」全流程，并对用户确认环节做强制校验。
1. 适用范围
| 适用 | 不适用 | |------|-------| | 在科力普平台采购日常办公用品 | 非科力普的其他平台采购 | | 单 SKU 或多 SKU 合并下单 | 合同谈判 / 议价 | | 订单状态查询与取消 | 售后退换货 | | 通过 API 直接交互 | 网页端模拟点击 |
2. 强制约束（必读）
- 用户确认是必经环节：展示完整订单信息（商品清单、合计金额、收件人、成本中心）后，用户输入
y才可正式提交，严禁跳过确认自动下单。 - 不做预算校验：金额合理性由用户判断。
- 敏感信息保密：账号 / 密码 / Cookie / TraceId 严禁写入代码仓库或日志，必须从环境变量或密钥管理服务读取。
- 预提交失败立即终止：
/api/confirm/create返回Data.Success != true时不得继续调用/api/confirm/orderConfirm。 - 统一使用
Direct=true模式：购物车 API 已废弃（/api/cart/add添加无效，/api/cart/clear返回 404），不再支持Direct=false。 - 多 SKU 合并为一单：
Direct=true的Items数组支持 1~N 个商品，所有 SKU 一次性提交合并为单个订单，禁止为每个 SKU 单独发起预提交。
3. Agent 快速决策
| 用户场景 | 推荐入口 |
|---------|---------|
| 用户已经给出 ItemId，想直接下单 | python scripts/colipu_order.py "${ITEM_ID},${QTY}" ... |
| 用户给关键词，希望先看再选 | 先调 colipu_search.py，由用户口头反馈编号后再走 colipu_order.py |
| 用户希望一站式完成（搜索 → 选号 → 确认 → 下单） | python scripts/buy_products.py ${KEYWORD} ${MAX_PRICE} ${NUM_ITEMS} |
| 自定义流程 / 嵌入到其他逻辑 | from colipu_client import ColipuClient 直接 import |
| 仅查询订单列表 / 取消订单 | 直接调 ColipuClient.get_orders() / ColipuClient.cancel_order() |
| 拿到 GuId 后查询异步生成的订单号 | ColipuClient.wait_order_create_result(${GUID}) |
| 根据订单号查询订单详情（商品明细 / 收件人 / 状态 / 金额） | ColipuClient.get_order_detail(${SO_ID}) |
4. 公共信息
| 项目 | 内容 |
|------|------|
| 域名 | https://h5vip.colipu.com |
| 鉴权 | 登录响应头 Set-Cookie 中的 EGG_SESS，后续请求头携带 Cookie: EGG_SESS=${EGG_SESS} |
| Content-Type | application/json;charset=UTF-8 |
| 默认 SiteId | 211 |
| 默认 WarehouseId | 111 |
| 默认 ProvinceId | 2（仅搜索时需要） |
5. 接口速查
| # | 接口 | 方法 | 用途 | 关键返回字段 |
|---|------|------|------|-------------|
| 1 | /api/vip/login | POST | 账号密码登录 | 响应头 Set-Cookie.EGG_SESS、Data.customerId |
| 2 | /api/b2bSearchApi/SearchByKeyWord | POST | 关键词搜索商品 | Data[].ItemId、Data[].SalePrice、Data[].ItemFullName |
| 3 | /api/b2bApi/GetAttributeGroupList | GET | 商品详情（属性、起订量等） | Data[].AttributeList、Data[].ItemAtte |
| 4 | /api/accountApi/receiver/list/0 | GET | 收货地址列表 | [].ReceiverId、[].Status==A |
| 5 | /api/crm/getConcenter?IsGroupPower=N | GET | 成本中心列表 | Data[].CostCenterId、Data[].Status==A |
| 6 | /api/confirm/create | POST | 预提交订单（拿 GuId） | Data.Success、Data.Message(=GuId) |
| 7 | /api/confirm/orderConfirm | POST | 确认提交订单（异步） | Data.Success（SoId 不在此接口返回） |
| 8 | /api/confirm/getOrderCreateResult | POST | 异步查询订单号（拿 SoId） | Code==200 时 Data 即订单号（int） |
| 9 | /api/order/orderlist | POST | 查询订单列表 | data[].soId、data[].status |
| 10 | /api/order/getOrderDetail?soSysno=${SO_ID} | GET | 根据订单号查订单详情 | Data.SoMaster、Data.SoItem[] |
| 11 | /api/order/CancelOrder | POST | 取消订单 | Code==1 且 Data=={"1":"操作成功"} |
完整字段说明、请求示例与响应字段表参见
references/api.md。
6. 下单请求格式（统一 Direct=true）
{
"SiteId": 211,
"Direct": true,
"Receiver": {
"CostCenterId": 1532475,
"ReceiverId": 33239
},
"Items": [
{ "ItemSkuId": 1384061, "SalePrice": 134, "SaleQty": 1, "ItemType": 1 },
{ "ItemSkuId": 13577742, "SalePrice": 60, "SaleQty": 1, "ItemType": 1 }
],
"ItemPicPath": "https://pic.colipu.com/pmspic/ItemPicture/"
}
Direct=true 模式下 无需 传
NetPrice / ProvinceId / SkuName / ToTalPrice / Checked / IsValid等字段，最小 4 字段即可下单。
7. 字段取值规则（重要）
| 目标字段 | 来源 | 备注 |
|---------|------|------|
| Items[].ItemSkuId | 搜索结果的 Data[].ItemId | 使用 ItemId，不是 ProductSkuId |
| Items[].SalePrice | 搜索结果的 Data[].SalePrice | 直接透传 |
| Items[].SaleQty | 用户指定数量 | 默认 1 |
| Items[].ItemType | 固定 1 | 普通商品 |
| Receiver.ReceiverId | 收货地址列表 | 优先 IsDefault=true，否则取第一个 |
| Receiver.CostCenterId | 成本中心列表 | 必须 Status=="A"，取第一个有效项 |
| GuId（确认提交用） | 预提交响应 Data.Message | Code==200 && Data.Success==true 才取 |
| 订单号（SoId） | /api/confirm/getOrderCreateResult 响应 Data（int） | 订单异步生成，confirm_order 不直接返回 SoId；建议轮询 1~30s（Python 用 wait_order_create_result(guid)）；超时再退化到 orderlist 取 data[0].soId |
| 显示用订单号 | getOrderDetail 响应 Data.SoMaster.SOID | 字符串（如 1026344136），用于向用户展示；内部传参仍用 SysNo（int） |
| 订单状态 | Data.SoMaster.Status 或 WebStatus | 数值码，配合 getOrderDetail 详情页展示 |
| 实付金额 | Data.SoMaster.RealSOAmt | 元，可直接展示 |
| 商品明细 | Data.SoItem[] | 关键字段：ProductName / Quantity / Price / RealPrice / SaleUnit |
8. 完整下单流程（伪代码）
登录 → 取 EGG_SESS → 搜索商品 → 取收货地址 → 取成本中心
→ 预提交订单 → ★用户确认(y) → 确认提交 → 异步查询订单号 → 查询订单
# 1. 登录 → 拿到 EGG_SESS
POST /api/vip/login
{ "loginName":"${COLIPU_LOGIN_NAME}", "pwd":"${COLIPU_PASSWORD}",
"cleartext":"Y", "hasMobileLogin":false, "scene":"h5" }
→ Set-Cookie 中提取 EGG_SESS
# 2. 搜索商品
POST /api/b2bSearchApi/SearchByKeyWord
Cookie: EGG_SESS=${EGG_SESS}
{ "siteId":211, "warehouseIds":[111], "keyWord":"${KEYWORD}",
"pageIndex":1, "pageSize":20, "provinceId":2,
"consumer":{ "customerId":${CUSTOMER_ID}, "showType":"" } }
→ 取 Data[].ItemId / Data[].ItemFullName / Data[].SalePrice
# 3. 收货地址
GET /api/accountApi/receiver/list/0
→ 取 ReceiverId（数组，优先 IsDefault=true）
# 4. 成本中心
GET /api/crm/getConcenter?IsGroupPower=N
→ 取 Status=="A" 的 CostCenterId
# 5. 预提交（多 SKU 合并为一单）
POST /api/confirm/create
{ "SiteId":211, "Direct":true,
"Receiver":{ "CostCenterId":${COST_CENTER_ID}, "ReceiverId":${RECEIVER_ID} },
"Items":[ { "ItemSkuId":${ITEM_ID}, "SalePrice":${PRICE}, "SaleQty":${QTY}, "ItemType":1 } ],
"ItemPicPath":"https://pic.colipu.com/pmspic/ItemPicture/" }
→ Code==200 && Data.Success==true 时，Data.Message 即 ${GUID}
# 6. ★ 用户确认（强制环节，不可省略）
向用户展示：商品清单 / 合计金额 / 收件人 / 成本中心
等待用户输入 y；输入其他字符 → 直接退出，不再调用第 7 步
# 7. 确认提交（异步：本接口不直接返回 SoId）
POST /api/confirm/orderConfirm
{ "GuId":"${GUID}", "SOEvidenceList":[] }
→ Data.Success==true 表示提交成功；订单号需走第 8 步异步查询
# 8. 异步查询订单号（轮询，间隔 ~1s，总超时 ~30s）
POST /api/confirm/getOrderCreateResult
{ "GuId":"${GUID}" }
→ Code==200 && Data 为 int(>0) 时，Data 即 ${SO_ID}
→ Data 为 null/0 表示订单仍在创建中，继续轮询
# 9. 查询订单（可选验证 / 兜底）
POST /api/order/orderlist
{ "type":1, "pageNo":1, "pageSize":10, "searchWord":"", "soId":"", "doId":"" }
→ data[0] 为最新订单
# 10. 查询订单详情（向用户回显商品明细 / 状态 / 金额）
GET /api/order/getOrderDetail?soSysno=${SO_ID}
→ Code==1 时：
Data.SoMaster.SOID / Status / RealSOAmt / OrderDate / ReceiveContact / ReceiveAddress
Data.SoItem[]: ProductName / Quantity / Price / RealPrice / SaleUnit
9. 附加操作：取消订单
POST /api/order/CancelOrder
Cookie: EGG_SESS=${EGG_SESS}
{ "OrderId":"${SO_ID}", "CancelReason":"${REASON}" }
→ Code==1 && Data=={"1":"操作成功"} 表示取消成功
仅可取消「审批中」或「待发货」状态的订单；已发货 / 已完成订单需走售后流程。
10. 订单类型枚举
| type | 含义 |
|-------|------|
| 1 | 全部订单 |
| 2 | 审批中 |
| 3 | 待发货 |
| 4 | 已发货 |
11. 配套脚本
全部位于
scripts/，依赖colipu_client.py，凭据从环境变量COLIPU_LOGIN_NAME/COLIPU_PASSWORD读取（customerId由登录响应自动回填）。
| 脚本 | 用途 | 适用场景 |
|------|------|---------|
| colipu_client.py | ColipuClient 基础类，封装全部接口 | 自定义流程时直接 import |
| colipu_search.py | 搜索 + 价格过滤 + 列表展示 | 用户先看再决定的两步流程 |
| colipu_order.py | 按「ItemId,数量」批量下单 | 用户已经确定 SKU |
| buy_products.py | 一站式：搜索 → 选号 → 用户确认 → 下单 | 单次完整下单交互 |
输出约定：[OK] 成功、[X] 失败、[i] 提示。
12. 错误处理
| 现象 | 处理方式 |
|------|---------|
| 登录返回 code != 1 | 终止，提示用户检查账号 / 密码 |
| 401 / EGG_SESS 失效（其他接口提示未登录） | 重新调用 /api/vip/login 取新 EGG_SESS 后重试 |
| 搜索 Data 为空 | 提示更换关键词 |
| 价格过滤后无结果 | 提示放宽 ${MAX_PRICE} 或换商品 |
| 收货地址 / 成本中心列表为空 | 终止，提示去网页端先维护一条 |
| 预提交 Data.Success != true | 输出 Data.Message，直接终止，不得调用确认接口 |
| 确认提交 Data.Success != true | 输出原因；如需重试需重新走预提交 |
| getOrderCreateResult 长时间 Data 为 0 / null | 已超过轮询超时（如 30s），提示用户「订单已提交但仍在异步生成」，并去 orderlist 兜底查询；多次复现需走技术支持邮箱 |
| 取消订单 Code != 1 | 输出 Data 中的错误信息，建议人工到网页端操作 |
| 以上任一情况无法解决 / 接口持续报错 / 字段含义不明 | 终止当前流程，提示用户发邮件至 cip_tech@colipu.com（科力普技术支持），邮件内容附上：账号、接口路径、请求体、完整响应体、复现时间 |
13. 技术支持
| 项目 | 内容 |
|------|------|
| 邮箱 | cip_tech@colipu.com |
| 适用场景 | 接口持续异常、字段含义不明、账号 / 权限问题、新增需求等无法通过本技能自动处理的情况 |
| 邮件建议附带 | 登录账号、接口路径、请求体（脱敏）、完整响应体、复现时间、TraceId（如有） |
Agent 在自动重试 / 错误处理失败后，应主动告知用户上述邮箱并给出邮件草稿模板，不要无限重试。
14. 详细接口文档
完整接口参数说明、响应字段说明、枚举值参见 references/api.md。
最后更新：2026-05-06 | 技术支持：
cip_tech@colipu.com