{ "module": "openapi", "description": "开放 API 统一入口,独立链路,HTTP POST /openapi,记录入口校验/鉴权规则与返回格式。", "version": "2026.06.05-openapi-15", "updatedAt": "2026-06-05", "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" ] } ] } ] } }