WMS_MAIN/methods/openapi.json
liufumingren 77435aeb79 1
2026-06-23 18:48:33 +08:00

1911 lines
96 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"module": "openapi",
"description": "开放 API 统一入口,独立链路,HTTP POST /openapi,记录入口校验/鉴权规则与返回格式。",
"version": "1.1.0",
"updatedAt": "2026-06-23",
"http": {
"path": "/openapi",
"method": "POST"
},
"headers": [],
"methods": {
"groups": [
{
"groupName": "基础模块",
"module": "index",
"list": [
{
"method": "index.ping",
"description": "基础模块 心跳接口,返回服务可用性(部署在 openapiMethods 中)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功通常为 200 或 1"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "返回数据,ping 一般为空或包含版本/uptime 等信息"
}
],
"errors": [],
"notes": [
"模块:基础模块",
"方法部署位置:openapiMethods/index.ping",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
},
{
"groupName": "发货单模块",
"module": "deliveryorder",
"list": [
{
"method": "deliveryorder.create",
"description": "deliveryorder 模块 创建发货单接口,支持传入订单主信息、收件人信息和订单明细",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "deliveryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "发货单主信息对象"
},
{
"name": "deliveryOrder.deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(必填),外部系统的唯一订单号"
},
{
"name": "deliveryOrder.preDeliveryOrderCode",
"type": "string",
"required": false,
"source": "body",
"description": "前发货单编码,用于关联前置订单"
},
{
"name": "deliveryOrder.preDeliveryOrderId",
"type": "string",
"required": false,
"source": "body",
"description": "前发货单ID,用于关联前置订单"
},
{
"name": "deliveryOrder.orderType",
"type": "string",
"required": false,
"source": "body",
"description": "订单类型,如 JYCK(一般出库)、PTCK(普通出库)等"
},
{
"name": "deliveryOrder.warehouseCode",
"type": "string",
"required": false,
"source": "body",
"description": "仓库编码,用于指定发货仓库"
},
{
"name": "deliveryOrder.orderFlag",
"type": "string",
"required": false,
"source": "body",
"description": "订单标记,自定义标记位"
},
{
"name": "deliveryOrder.sourcePlatformCode",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台编码,如 TB(淘宝)、JD(京东)、PDD(拼多多)等;匹配不到时自动使用货主默认平台"
},
{
"name": "deliveryOrder.sourcePlatformName",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台名称"
},
{
"name": "deliveryOrder.createTime",
"type": "string",
"required": false,
"source": "body",
"description": "订单创建时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.placeOrderTime",
"type": "string",
"required": false,
"source": "body",
"description": "下单时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.payTime",
"type": "string",
"required": false,
"source": "body",
"description": "支付时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.payNo",
"type": "string",
"required": false,
"source": "body",
"description": "支付单号"
},
{
"name": "deliveryOrder.shopNick",
"type": "string",
"required": false,
"source": "body",
"description": "店铺昵称"
},
{
"name": "deliveryOrder.sellerNick",
"type": "string",
"required": false,
"source": "body",
"description": "卖家昵称"
},
{
"name": "deliveryOrder.buyerNick",
"type": "string",
"required": false,
"source": "body",
"description": "买家昵称"
},
{
"name": "deliveryOrder.operatorName",
"type": "string",
"required": false,
"source": "body",
"description": "操作人姓名,未传入时自动按 API 应用名称回填"
},
{
"name": "deliveryOrder.operateTime",
"type": "string",
"required": false,
"source": "body",
"description": "操作时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.totalAmount",
"type": "number",
"required": false,
"source": "body",
"description": "订单总金额"
},
{
"name": "deliveryOrder.itemAmount",
"type": "number",
"required": false,
"source": "body",
"description": "商品总金额"
},
{
"name": "deliveryOrder.discountAmount",
"type": "number",
"required": false,
"source": "body",
"description": "折扣金额"
},
{
"name": "deliveryOrder.freight",
"type": "number",
"required": false,
"source": "body",
"description": "运费"
},
{
"name": "deliveryOrder.arAmount",
"type": "number",
"required": false,
"source": "body",
"description": "应收金额"
},
{
"name": "deliveryOrder.gotAmount",
"type": "number",
"required": false,
"source": "body",
"description": "实收金额"
},
{
"name": "deliveryOrder.logisticsCode",
"type": "string",
"required": false,
"source": "body",
"description": "快递编码,用于指定物流公司;匹配不到时自动使用货主默认快递"
},
{
"name": "deliveryOrder.expressCode",
"type": "string",
"required": false,
"source": "body",
"description": "快递公司编码"
},
{
"name": "deliveryOrder.logisticsAreaCode",
"type": "string",
"required": false,
"source": "body",
"description": "快递区域编码"
},
{
"name": "deliveryOrder.isUrgency",
"type": "string",
"required": false,
"source": "body",
"description": "是否加急,Y=是,N=否,默认 N"
},
{
"name": "deliveryOrder.invoiceFlag",
"type": "string",
"required": false,
"source": "body",
"description": "是否需要发票,Y=是,N=否,默认 N"
},
{
"name": "deliveryOrder.enableExternalExpressCode",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否启用外部快递编码匹配,开启后将优先按传入的 logisticsCode 匹配快递设置表"
},
{
"name": "deliveryOrder.receiverInfo",
"type": "object",
"required": false,
"source": "body",
"description": "收件人信息对象"
},
{
"name": "deliveryOrder.receiverInfo.name",
"type": "string",
"required": true,
"source": "body",
"description": "收件人姓名"
},
{
"name": "deliveryOrder.receiverInfo.tel",
"type": "string",
"required": false,
"source": "body",
"description": "收件人固定电话"
},
{
"name": "deliveryOrder.receiverInfo.mobile",
"type": "string",
"required": true,
"source": "body",
"description": "收件人手机号码"
},
{
"name": "deliveryOrder.receiverInfo.email",
"type": "string",
"required": false,
"source": "body",
"description": "收件人邮箱"
},
{
"name": "deliveryOrder.receiverInfo.countryCode",
"type": "string",
"required": false,
"source": "body",
"description": "国家编码"
},
{
"name": "deliveryOrder.receiverInfo.province",
"type": "string",
"required": true,
"source": "body",
"description": "省份"
},
{
"name": "deliveryOrder.receiverInfo.city",
"type": "string",
"required": true,
"source": "body",
"description": "城市"
},
{
"name": "deliveryOrder.receiverInfo.area",
"type": "string",
"required": true,
"source": "body",
"description": "区县"
},
{
"name": "deliveryOrder.receiverInfo.town",
"type": "string",
"required": false,
"source": "body",
"description": "乡镇/街道"
},
{
"name": "deliveryOrder.receiverInfo.detailAddress",
"type": "string",
"required": true,
"source": "body",
"description": "详细地址"
},
{
"name": "deliveryOrder.receiverInfo.zipCode",
"type": "string",
"required": false,
"source": "body",
"description": "邮政编码"
},
{
"name": "orderLines",
"type": "object",
"required": true,
"source": "body",
"description": "订单明细对象,包含 orderLine 数组"
},
{
"name": "orderLines.orderLine",
"type": "array",
"required": true,
"source": "body",
"description": "订单明细列表,数组中每项为一个订单行对象"
},
{
"name": "[].orderLine.itemCode",
"type": "string",
"required": false,
"source": "body",
"description": "商品编码,与 itemId 二选一,用于匹配仓库中的商品"
},
{
"name": "[].orderLine.itemId",
"type": "number",
"required": false,
"source": "body",
"description": "仓库商品主键ID,与 itemCode 二选一"
},
{
"name": "[].orderLine.itemName",
"type": "string",
"required": false,
"source": "body",
"description": "商品名称,用于错误提示中的商品识别"
},
{
"name": "[].orderLine.planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划发货数量(必填),必须大于 0"
},
{
"name": "[].orderLine.actualPrice",
"type": "number",
"required": false,
"source": "body",
"description": "实际单价"
},
{
"name": "[].orderLine.retailPrice",
"type": "number",
"required": false,
"source": "body",
"description": "零售单价"
},
{
"name": "[].orderLine.extCode",
"type": "string",
"required": false,
"source": "body",
"description": "外部商品编码"
},
{
"name": "[].orderLine.inventoryType",
"type": "string",
"required": false,
"source": "body",
"description": "库存类型,如 ZP(正品)、CC(残次品)"
},
{
"name": "[].orderLine.orderLineNo",
"type": "string",
"required": false,
"source": "body",
"description": "订单行号,未传入时自动按序号生成(1、2、3...)"
},
{
"name": "[].orderLine.ownerCode",
"type": "string",
"required": false,
"source": "body",
"description": "货主编码"
},
{
"name": "[].orderLine.sourceOrderCode",
"type": "string",
"required": false,
"source": "body",
"description": "来源订单编码,用于关联上游订单"
},
{
"name": "[].orderLine.subSourceOrderCode",
"type": "string",
"required": false,
"source": "body",
"description": "子来源订单编码"
},
{
"name": "[].orderLine.extendProps",
"type": "string",
"required": false,
"source": "body",
"description": "扩展属性,JSON 字符串或对象,用于存储自定义字段"
}
],
"requestBody": [
{
"name": "deliveryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "发货单主信息对象"
},
{
"name": "deliveryOrder.deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(必填),外部系统的唯一订单号"
},
{
"name": "deliveryOrder.preDeliveryOrderCode",
"type": "string",
"required": false,
"source": "body",
"description": "前发货单编码,用于关联前置订单"
},
{
"name": "deliveryOrder.preDeliveryOrderId",
"type": "string",
"required": false,
"source": "body",
"description": "前发货单ID,用于关联前置订单"
},
{
"name": "deliveryOrder.orderType",
"type": "string",
"required": false,
"source": "body",
"description": "订单类型,如 JYCK(一般出库)、PTCK(普通出库)等"
},
{
"name": "deliveryOrder.warehouseCode",
"type": "string",
"required": false,
"source": "body",
"description": "仓库编码,用于指定发货仓库"
},
{
"name": "deliveryOrder.orderFlag",
"type": "string",
"required": false,
"source": "body",
"description": "订单标记,自定义标记位"
},
{
"name": "deliveryOrder.sourcePlatformCode",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台编码,如 TB(淘宝)、JD(京东)、PDD(拼多多)等;匹配不到时自动使用货主默认平台"
},
{
"name": "deliveryOrder.sourcePlatformName",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台名称"
},
{
"name": "deliveryOrder.createTime",
"type": "string",
"required": false,
"source": "body",
"description": "订单创建时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.placeOrderTime",
"type": "string",
"required": false,
"source": "body",
"description": "下单时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.payTime",
"type": "string",
"required": false,
"source": "body",
"description": "支付时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.payNo",
"type": "string",
"required": false,
"source": "body",
"description": "支付单号"
},
{
"name": "deliveryOrder.shopNick",
"type": "string",
"required": false,
"source": "body",
"description": "店铺昵称"
},
{
"name": "deliveryOrder.sellerNick",
"type": "string",
"required": false,
"source": "body",
"description": "卖家昵称"
},
{
"name": "deliveryOrder.buyerNick",
"type": "string",
"required": false,
"source": "body",
"description": "买家昵称"
},
{
"name": "deliveryOrder.operatorName",
"type": "string",
"required": false,
"source": "body",
"description": "操作人姓名,未传入时自动按 API 应用名称回填"
},
{
"name": "deliveryOrder.operateTime",
"type": "string",
"required": false,
"source": "body",
"description": "操作时间,支持 ISO 8601 格式"
},
{
"name": "deliveryOrder.totalAmount",
"type": "number",
"required": false,
"source": "body",
"description": "订单总金额"
},
{
"name": "deliveryOrder.itemAmount",
"type": "number",
"required": false,
"source": "body",
"description": "商品总金额"
},
{
"name": "deliveryOrder.discountAmount",
"type": "number",
"required": false,
"source": "body",
"description": "折扣金额"
},
{
"name": "deliveryOrder.freight",
"type": "number",
"required": false,
"source": "body",
"description": "运费"
},
{
"name": "deliveryOrder.arAmount",
"type": "number",
"required": false,
"source": "body",
"description": "应收金额"
},
{
"name": "deliveryOrder.gotAmount",
"type": "number",
"required": false,
"source": "body",
"description": "实收金额"
},
{
"name": "deliveryOrder.logisticsCode",
"type": "string",
"required": false,
"source": "body",
"description": "快递编码,用于指定物流公司;匹配不到时自动使用货主默认快递"
},
{
"name": "deliveryOrder.expressCode",
"type": "string",
"required": false,
"source": "body",
"description": "快递公司编码"
},
{
"name": "deliveryOrder.logisticsAreaCode",
"type": "string",
"required": false,
"source": "body",
"description": "快递区域编码"
},
{
"name": "deliveryOrder.isUrgency",
"type": "string",
"required": false,
"source": "body",
"description": "是否加急,Y=是,N=否,默认 N"
},
{
"name": "deliveryOrder.invoiceFlag",
"type": "string",
"required": false,
"source": "body",
"description": "是否需要发票,Y=是,N=否,默认 N"
},
{
"name": "deliveryOrder.enableExternalExpressCode",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否启用外部快递编码匹配,开启后将优先按传入的 logisticsCode 匹配快递设置表"
},
{
"name": "deliveryOrder.receiverInfo",
"type": "object",
"required": false,
"source": "body",
"description": "收件人信息对象"
},
{
"name": "deliveryOrder.receiverInfo.name",
"type": "string",
"required": true,
"source": "body",
"description": "收件人姓名"
},
{
"name": "deliveryOrder.receiverInfo.tel",
"type": "string",
"required": false,
"source": "body",
"description": "收件人固定电话"
},
{
"name": "deliveryOrder.receiverInfo.mobile",
"type": "string",
"required": true,
"source": "body",
"description": "收件人手机号码"
},
{
"name": "deliveryOrder.receiverInfo.email",
"type": "string",
"required": false,
"source": "body",
"description": "收件人邮箱"
},
{
"name": "deliveryOrder.receiverInfo.countryCode",
"type": "string",
"required": false,
"source": "body",
"description": "国家编码"
},
{
"name": "deliveryOrder.receiverInfo.province",
"type": "string",
"required": true,
"source": "body",
"description": "省份"
},
{
"name": "deliveryOrder.receiverInfo.city",
"type": "string",
"required": true,
"source": "body",
"description": "城市"
},
{
"name": "deliveryOrder.receiverInfo.area",
"type": "string",
"required": true,
"source": "body",
"description": "区县"
},
{
"name": "deliveryOrder.receiverInfo.town",
"type": "string",
"required": false,
"source": "body",
"description": "乡镇/街道"
},
{
"name": "deliveryOrder.receiverInfo.detailAddress",
"type": "string",
"required": true,
"source": "body",
"description": "详细地址"
},
{
"name": "deliveryOrder.receiverInfo.zipCode",
"type": "string",
"required": false,
"source": "body",
"description": "邮政编码"
},
{
"name": "orderLines",
"type": "object",
"required": true,
"source": "body",
"description": "订单明细对象,包含 orderLine 数组"
},
{
"name": "orderLines.orderLine",
"type": "array",
"required": true,
"source": "body",
"description": "订单明细列表,数组中每项为一个订单行对象"
},
{
"name": "[].orderLine.itemCode",
"type": "string",
"required": false,
"source": "body",
"description": "商品编码,与 itemId 二选一,用于匹配仓库中的商品"
},
{
"name": "[].orderLine.itemId",
"type": "number",
"required": false,
"source": "body",
"description": "仓库商品主键ID,与 itemCode 二选一"
},
{
"name": "[].orderLine.itemName",
"type": "string",
"required": false,
"source": "body",
"description": "商品名称,用于错误提示中的商品识别"
},
{
"name": "[].orderLine.planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划发货数量(必填),必须大于 0"
},
{
"name": "[].orderLine.actualPrice",
"type": "number",
"required": false,
"source": "body",
"description": "实际单价"
},
{
"name": "[].orderLine.retailPrice",
"type": "number",
"required": false,
"source": "body",
"description": "零售单价"
},
{
"name": "[].orderLine.extCode",
"type": "string",
"required": false,
"source": "body",
"description": "外部商品编码"
},
{
"name": "[].orderLine.inventoryType",
"type": "string",
"required": false,
"source": "body",
"description": "库存类型,如 ZP(正品)、CC(残次品)"
},
{
"name": "[].orderLine.orderLineNo",
"type": "string",
"required": false,
"source": "body",
"description": "订单行号,未传入时自动按序号生成(1、2、3...)"
},
{
"name": "[].orderLine.ownerCode",
"type": "string",
"required": false,
"source": "body",
"description": "货主编码"
},
{
"name": "[].orderLine.sourceOrderCode",
"type": "string",
"required": false,
"source": "body",
"description": "来源订单编码,用于关联上游订单"
},
{
"name": "[].orderLine.subSourceOrderCode",
"type": "string",
"required": false,
"source": "body",
"description": "子来源订单编码"
},
{
"name": "[].orderLine.extendProps",
"type": "string",
"required": false,
"source": "body",
"description": "扩展属性,JSON 字符串或对象,用于存储自定义字段"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "创建成功时返回 orderId、step、stats(items_count/item_total/items_weight/source_order_codes)等"
}
],
"errors": [
{
"code": 400,
"message": "订单信息不完整(deliveryOrder.deliveryOrderCode 缺失)"
},
{
"code": 400,
"message": "没有有效的订单明细数据(orderLines.orderLine 为空或数量 ≤0)"
},
{
"code": 400,
"message": "商品《xxx》编码《xxx》未同步推送到仓库"
},
{
"code": 409,
"message": "订单已存在(相同 deliveryOrderCode + store_id + warehouse_id)"
}
],
"notes": [
"模块:deliveryorder 模块",
"方法部署位置:openapiMethods/deliveryorder.create",
"创建渠道固定为 API,操作人未传入时自动按 API 应用名称回填",
"sourcePlatformCode 传入后优先匹配平台列表;匹配不到则使用货主默认平台",
"logisticsCode 传入后按快递设置表 → 快递列表 → 货主默认快递的优先级匹配",
"orderLines.orderLine 支持单对象或数组格式",
"同一订单中不允许重复的商品(按 itemId 去重)",
"返回的 data.orderId 为系统内部订单主键ID",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400",
"receiverInfo.name / mobile / province / city / area / detailAddress 为快递取号必填字段,请务必传入完整收件人信息",
"mobile 和 tel 二选一必填(快递取号需要至少一个联系电话)"
]
},
{
"method": "deliveryorder.query",
"description": "deliveryorder 模块 查询发货单接口,根据发货单编码返回订单详情",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(必填),要查询的订单号"
}
],
"requestBody": [
{
"name": "deliveryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(必填),要查询的订单号"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "查询成功时返回 totalLines、deliveryOrder(deliveryOrderCode/deliveryOrderId/warehouseCode/orderType/status/orderConfirmTime/operatorCode/operatorName/operateTime)、packages、orderLines"
}
],
"errors": [
{
"code": 400,
"message": "deliveryOrderCode 参数缺失"
},
{
"code": 404,
"message": "未找到订单"
}
],
"notes": [
"模块:deliveryorder 模块",
"方法部署位置:openapiMethods/deliveryorder.query",
"查询范围为当前 app_key 绑定的仓库,跨仓库订单无法查询",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
},
{
"groupName": "订单模块",
"module": "order",
"list": [
{
"method": "order.cancel",
"description": "order 模块 取消发货单接口,支持直接取消未拣货/未打印的订单;已拣货或已打印的订单改为拦截状态",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "orderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(必填),要取消的订单号"
},
{
"name": "orderType",
"type": "string",
"required": false,
"source": "body",
"description": "订单类型,默认 JYCK(一般交易出库单);当前支持 JYCK(一般交易出库)、HHCK(换货出库)、BFCK(补发出库)"
}
],
"requestBody": [
{
"name": "orderCode",
"type": "string",
"required": true,
"source": "body",
"description": "发货单编码(必填),要取消的订单号"
},
{
"name": "orderType",
"type": "string",
"required": false,
"source": "body",
"description": "订单类型,默认 JYCK(一般交易出库单);当前支持 JYCK(一般交易出库)、HHCK(换货出库)、BFCK(补发出库)"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "取消成功时可能包含订单状态信息"
}
],
"errors": [
{
"code": 400,
"message": "订单号不能为空"
},
{
"code": 400,
"message": "暂不支持该订单类型的取消操作"
},
{
"code": 404,
"message": "未找到对应的订单"
},
{
"code": 409,
"message": "取消失败,已通知拦截执行(订单已拣货或已打印,改为拦截状态)"
}
],
"notes": [
"模块:order 模块",
"方法部署位置:openapiMethods/order.cancel",
"取消逻辑:未拣货且未打印的订单直接取消(status=cancel, outbound_status=fin, step=4);已拣货或已打印的订单标记为拦截状态(intercept_status=intercepting),不直接取消",
"订单类型映射:JYCK/HHCK/BFCK → 出库单取消;其他类型暂不支持",
"使用事务 + 行锁保证并发安全",
"取消操作为不可逆操作,请谨慎调用",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
},
{
"groupName": "商品模块",
"module": "singleitem",
"list": [
{
"method": "singleitem.synchronize",
"description": "singleitem 模块 商品同步接口,创建或更新商品信息(itemCode 唯一约束,已存在则更新)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "item",
"type": "object",
"required": true,
"source": "body",
"description": "商品信息对象(必填)"
},
{
"name": "item.itemCode",
"type": "string",
"required": true,
"source": "body",
"description": "商品编码(必填),唯一标识商品"
},
{
"name": "item.goodsCode",
"type": "string",
"required": false,
"source": "body",
"description": "商品货号"
},
{
"name": "item.itemName",
"type": "string",
"required": false,
"source": "body",
"description": "商品名称"
},
{
"name": "item.skuProperty",
"type": "string",
"required": false,
"source": "body",
"description": "SKU 属性描述,如颜色:红色;尺码:XL"
},
{
"name": "item.stockUnit",
"type": "string",
"required": false,
"source": "body",
"description": "库存单位,如 件、箱、个"
},
{
"name": "item.length",
"type": "number",
"required": false,
"source": "body",
"description": "长(cm)"
},
{
"name": "item.width",
"type": "number",
"required": false,
"source": "body",
"description": "宽(cm)"
},
{
"name": "item.height",
"type": "number",
"required": false,
"source": "body",
"description": "高(cm)"
},
{
"name": "item.volume",
"type": "number",
"required": false,
"source": "body",
"description": "体积(cm³)"
},
{
"name": "item.grossWeight",
"type": "number",
"required": false,
"source": "body",
"description": "毛重(kg)"
},
{
"name": "item.netWeight",
"type": "number",
"required": false,
"source": "body",
"description": "净重(kg)"
},
{
"name": "item.categoryId",
"type": "number",
"required": false,
"source": "body",
"description": "商品分类 ID"
},
{
"name": "item.categoryName",
"type": "string",
"required": false,
"source": "body",
"description": "商品分类名称"
},
{
"name": "item.itemType",
"type": "string",
"required": false,
"source": "body",
"description": "商品类型,如 NORMAL(普通商品)、SUIT(套装)"
},
{
"name": "item.tagPrice",
"type": "number",
"required": false,
"source": "body",
"description": "吊牌价"
},
{
"name": "item.retailPrice",
"type": "number",
"required": false,
"source": "body",
"description": "零售价"
},
{
"name": "item.brandName",
"type": "string",
"required": false,
"source": "body",
"description": "品牌名称"
},
{
"name": "item.isSNMgmt",
"type": "string",
"required": false,
"source": "body",
"description": "是否 SN 序列号管理,Y=是,N=否,默认 N"
},
{
"name": "item.isShelfLifeMgmt",
"type": "string",
"required": false,
"source": "body",
"description": "是否保质期管理,Y=是,N=否,默认 N"
},
{
"name": "item.isBatchMgmt",
"type": "string",
"required": false,
"source": "body",
"description": "是否批次管理,Y=是,N=否,默认 N"
},
{
"name": "item.isAreaSale",
"type": "string",
"required": false,
"source": "body",
"description": "是否区域销售,Y=是,N=否,默认 N"
},
{
"name": "item.createTime",
"type": "string",
"required": false,
"source": "body",
"description": "创建时间,ISO 8601 格式"
},
{
"name": "item.isValid",
"type": "string",
"required": false,
"source": "body",
"description": "是否有效,Y=是,N=否,默认 Y"
},
{
"name": "item.barCode",
"type": "string",
"required": false,
"source": "body",
"description": "条形码"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "同步成功时返回 itemId(系统内部商品 ID)"
}
],
"errors": [
{
"code": 400,
"message": "参数缺失: item.itemCode"
}
],
"notes": [
"模块:singleitem 模块",
"方法部署位置:openapiMethods/singleitem.synchronize",
"同步策略:按 itemCode + app_key + warehouse_id + store_id 唯一约束判断,已存在则更新,不存在则创建",
"同步后会联动创建/更新库存表(StockWarehouse)记录",
"create_from 固定为 qimen(与奇门共用同一套底层逻辑)",
"warehouseCode 和 ownerCode 由 app_key 绑定的仓库/货主自动解析,不可通过请求参数覆盖",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
},
{
"method": "singleitem.query",
"description": "singleitem 模块 商品查询接口,按商品 ID 返回完整商品信息",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "itemId",
"type": "number",
"required": true,
"source": "body",
"description": "商品 ID(必填),系统内部商品主键"
}
],
"requestBody": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "查询成功时返回 item 对象,包含 itemId/itemCode/goodsCode/itemName/skuProperty/stockUnit/length/width/height/volume/grossWeight/netWeight/categoryId/categoryName/itemType/tagPrice/retailPrice/brandName/isSNMgmt/isShelfLifeMgmt/isBatchMgmt/isAreaSale/barCode/isValid/createTime 等全部商品字段"
}
],
"errors": [
{
"code": 400,
"message": "参数错误: itemId 不存在"
},
{
"code": 404,
"message": "wms 的 SKUID 为 xxx 未找到"
}
],
"notes": [
"模块:singleitem 模块",
"方法部署位置:openapiMethods/singleitem.query",
"返回格式与奇门 convertToQimenFormat 一致,字段名使用驼峰命名",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
},
{
"groupName": "库存模块",
"module": "inventory",
"list": [
{
"method": "inventory.query",
"description": "inventory 模块 库存查询接口,按商品 ID 批量查询库存量(可用量、锁定量)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "itemIds",
"type": "array",
"required": true,
"source": "body",
"description": "商品 ID 列表(必填),如 [1000693, 1000694],支持单个或多个商品批量查询"
},
{
"name": "[].itemIds",
"type": "number",
"required": true,
"source": "body",
"description": "单个商品 ID,系统内部商品主键,可通过 singleitem.query 或 singleitem.synchronize 返回的 itemId 获取"
}
],
"requestBody": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "查询成功时返回 items 数组"
},
{
"name": "data.items",
"type": "array",
"required": false,
"description": "库存信息列表"
},
{
"name": "[].items.itemId",
"type": "number",
"required": false,
"description": "商品 ID"
},
{
"name": "[].items.itemCode",
"type": "string",
"required": false,
"description": "商品编码"
},
{
"name": "[].items.warehouseCode",
"type": "string",
"required": false,
"description": "仓库编码"
},
{
"name": "[].items.quantity",
"type": "number",
"required": false,
"description": "总库存量"
},
{
"name": "[].items.lockQuantity",
"type": "number",
"required": false,
"description": "锁定量(已被订单预占的库存)"
},
{
"name": "[].items.inventoryType",
"type": "string",
"required": false,
"description": "库存类型,固定返回 ZP(正品)"
}
],
"errors": [
{
"code": 400,
"message": "itemIds 参数缺失或为空"
},
{
"code": 404,
"message": "未查询到有效库存信息"
}
],
"notes": [
"模块:inventory 模块",
"方法部署位置:openapiMethods/inventory.query",
"支持批量查询多个商品的库存,减少请求次数",
"库存不足(可用量 ≤0)或商品未绑定库存记录时,该条商品不会出现在返回结果中",
"查询范围为当前 app_key 绑定的仓库",
"可用量 = quantity - lockQuantity",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
},
{
"groupName": "入库单模块",
"module": "entryorder",
"list": [
{
"method": "entryorder.create",
"description": "entryorder 模块 创建入库单接口,支持传入入库单主信息和商品明细。创建成功后返回的状态 status 为 CREATING(明细行未全部插入)或 CREATED(明细行已全部插入完成)。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "entryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "入库单主信息对象"
},
{
"name": "entryOrder.entryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "入库单号(必填),外部系统的唯一入库单号"
},
{
"name": "entryOrder.entryOrderType",
"type": "string",
"required": false,
"source": "body",
"description": "入库单类型,默认 SCRK(生产入库)"
},
{
"name": "entryOrder.warehouseCode",
"type": "string",
"required": false,
"source": "body",
"description": "仓库编码"
},
{
"name": "entryOrder.ownerCode",
"type": "string",
"required": false,
"source": "body",
"description": "货主编码"
},
{
"name": "entryOrder.expectedArriveTime",
"type": "string",
"required": false,
"source": "body",
"description": "预计到货时间,ISO 8601 格式"
},
{
"name": "entryOrder.totalOrderLines",
"type": "number",
"required": false,
"source": "body",
"description": "总行数"
},
{
"name": "entryOrder.operateTime",
"type": "string",
"required": false,
"source": "body",
"description": "操作时间,ISO 8601 格式"
},
{
"name": "entryOrder.operatorName",
"type": "string",
"required": false,
"source": "body",
"description": "操作人"
},
{
"name": "entryOrder.supplierCode",
"type": "string",
"required": false,
"source": "body",
"description": "供应商编码"
},
{
"name": "entryOrder.supplierName",
"type": "string",
"required": false,
"source": "body",
"description": "供应商名称"
},
{
"name": "entryOrder.remark",
"type": "string",
"required": false,
"source": "body",
"description": "备注"
},
{
"name": "orderLines",
"type": "object",
"required": true,
"source": "body",
"description": "订单明细对象,包含 orderLine 数组"
},
{
"name": "orderLines.orderLine",
"type": "array",
"required": true,
"source": "body",
"description": "商品明细列表,数组中每项为一个入库单行对象"
},
{
"name": "[].orderLine.itemCode",
"type": "string",
"required": false,
"source": "body",
"description": "商品编码,与 itemId 二选一,用于匹配仓库中的商品"
},
{
"name": "[].orderLine.itemId",
"type": "number",
"required": false,
"source": "body",
"description": "仓库商品主键ID,与 itemCode 二选一,优先使用 itemId"
},
{
"name": "[].orderLine.itemName",
"type": "string",
"required": false,
"source": "body",
"description": "商品名称,用于错误提示中的商品识别"
},
{
"name": "[].orderLine.planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划入库数量(必填),必须大于 0"
},
{
"name": "[].orderLine.inventoryType",
"type": "string",
"required": false,
"source": "body",
"description": "库存类型,默认 ZP(正品)"
},
{
"name": "[].orderLine.orderLineNo",
"type": "string",
"required": false,
"source": "body",
"description": "行号"
}
],
"requestBody": [
{
"name": "entryOrder",
"type": "object",
"required": true,
"source": "body",
"description": "入库单主信息对象"
},
{
"name": "entryOrder.entryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "入库单号(必填),外部系统的唯一入库单号"
},
{
"name": "entryOrder.entryOrderType",
"type": "string",
"required": false,
"source": "body",
"description": "入库单类型,默认 SCRK(生产入库)"
},
{
"name": "entryOrder.warehouseCode",
"type": "string",
"required": false,
"source": "body",
"description": "仓库编码"
},
{
"name": "entryOrder.ownerCode",
"type": "string",
"required": false,
"source": "body",
"description": "货主编码"
},
{
"name": "entryOrder.expectedArriveTime",
"type": "string",
"required": false,
"source": "body",
"description": "预计到货时间,ISO 8601 格式"
},
{
"name": "entryOrder.totalOrderLines",
"type": "number",
"required": false,
"source": "body",
"description": "总行数"
},
{
"name": "entryOrder.operateTime",
"type": "string",
"required": false,
"source": "body",
"description": "操作时间,ISO 8601 格式"
},
{
"name": "entryOrder.operatorName",
"type": "string",
"required": false,
"source": "body",
"description": "操作人"
},
{
"name": "entryOrder.supplierCode",
"type": "string",
"required": false,
"source": "body",
"description": "供应商编码"
},
{
"name": "entryOrder.supplierName",
"type": "string",
"required": false,
"source": "body",
"description": "供应商名称"
},
{
"name": "entryOrder.remark",
"type": "string",
"required": false,
"source": "body",
"description": "备注"
},
{
"name": "orderLines",
"type": "object",
"required": true,
"source": "body",
"description": "订单明细对象,包含 orderLine 数组"
},
{
"name": "orderLines.orderLine",
"type": "array",
"required": true,
"source": "body",
"description": "商品明细列表,数组中每项为一个入库单行对象"
},
{
"name": "[].orderLine.itemCode",
"type": "string",
"required": false,
"source": "body",
"description": "商品编码,与 itemId 二选一"
},
{
"name": "[].orderLine.itemId",
"type": "number",
"required": false,
"source": "body",
"description": "仓库商品主键ID,与 itemCode 二选一,优先使用 itemId"
},
{
"name": "[].orderLine.itemName",
"type": "string",
"required": false,
"source": "body",
"description": "商品名称"
},
{
"name": "[].orderLine.planQty",
"type": "number",
"required": true,
"source": "body",
"description": "计划入库数量(必填),必须大于 0"
},
{
"name": "[].orderLine.inventoryType",
"type": "string",
"required": false,
"source": "body",
"description": "库存类型,默认 ZP(正品)"
},
{
"name": "[].orderLine.orderLineNo",
"type": "string",
"required": false,
"source": "body",
"description": "行号"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "创建成功时返回 entryOrderId、entryOrderCode、status(CREATING=创建中明细行未全部插入,CREATED=已创建完成)、createTime"
}
],
"errors": [
{
"code": 400,
"message": "entryOrder.entryOrderCode 参数缺失"
},
{
"code": 400,
"message": "orderLines.orderLine 参数缺失"
},
{
"code": 400,
"message": "商品未同步推送到仓库"
}
],
"notes": [
"模块:entryorder 模块",
"方法部署位置:openapiMethods/entryorder.create",
"创建渠道固定为 API",
"orderLines.orderLine 支持单对象或数组格式",
"itemCode 与 itemId 二选一,优先使用 itemId",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
},
{
"method": "entryorder.query",
"description": "entryorder 模块 查询入库单接口,根据入库单号返回入库单详情。返回的 status 字段可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "entryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "入库单号(必填),要查询的入库单号"
}
],
"requestBody": [
{
"name": "entryOrderCode",
"type": "string",
"required": true,
"source": "body",
"description": "入库单号(必填),要查询的入库单号"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "查询成功时返回 entryOrderCode、entryOrderId、status、entryOrderType、expectedArriveTime、supplierCode、supplierName、remark、createTime、operateTime、operatorName、warehouseCode、ownerCode、totalOrderLines、orderLines"
},
{
"name": "data.orderLines",
"type": "array",
"required": false,
"description": "商品明细列表"
},
{
"name": "[].orderLines.itemId",
"type": "number",
"required": false,
"description": "商品ID"
},
{
"name": "[].orderLines.itemCode",
"type": "string",
"required": false,
"description": "商品编码"
},
{
"name": "[].orderLines.itemName",
"type": "string",
"required": false,
"description": "商品名称"
},
{
"name": "[].orderLines.planQty",
"type": "number",
"required": false,
"description": "计划入库数量"
},
{
"name": "[].orderLines.actualQty",
"type": "number",
"required": false,
"description": "实际入库数量"
},
{
"name": "[].orderLines.inventoryType",
"type": "string",
"required": false,
"description": "库存类型"
},
{
"name": "[].orderLines.orderLineNo",
"type": "string",
"required": false,
"description": "行号"
}
],
"errors": [
{
"code": 400,
"message": "entryOrderCode 参数缺失"
},
{
"code": 404,
"message": "入库单未找到"
}
],
"notes": [
"模块:entryorder 模块",
"方法部署位置:openapiMethods/entryorder.query",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
}
]
}
}