4. 订单接口

本章节提供订单相关接口，包括订单查询、发货、签收文件上传、退货单查询及交货单获取等。

⚠️ 提示：订单接口需配合消息中心使用，通过消息中心获取订单编号后调用对应接口查询详情。

4.1 订单查询

接口说明

根据消息中心推送的订单编号，获取订单详细信息（包含订单主信息、明细、扩展字段及收货地址等）。

请求方式与路径

GET /api/v1/order/getByOrderCode

请求参数

参数名	参数位置	类型	长度	必填	说明
clientCode	requestParam	string	100	是	客户端编码
orderCode	requestParam	string	20	是	业务单据编码（采购单号）

响应参数

参数名	类型	必填	说明
orderCode	string	是	采购单号
orderDate	string	是	下单时间（yyyy-MM-dd HH:mm:ss）
expectDate	string	否	期望收货时间（yyyy-MM-dd HH:mm:ss）
orderStatus	string	是	订单状态（0:取消、20:新建、30:已发货、80:部分收货、40：签收中、90:签收完成）
vendorId	int	是	供应商ID
contractId	int	否	合同编号
salesOrderCode	string	否	科力普订单单号
deliveryOrderCode	string	否	科力普出库单号
platformOrderCode	string	否	客户平台单号
customerCode	string	否	客户编码
customerName	string	否	客户名称（科力普客户名称）
customerNote	string	否	配送要求
departmentName	string	否	成本中心（客户部门名称）
cooperationProjecName	string	否	合作项目名称
totalAmt	decimal	是	实收金额
orderAmt	decimal	是	采购金额
grossProfitPoints	decimal	是	采购毛利点（百分比）
orderItems	object[]	是	订单明细列表
orderExtend	object[]	是	订单扩展信息（键值对）
orderAddress	object	是	收货地址信息

子结构说明

(1) 订单明细 `orderItems[]`

⚠️ 注意：不可用 skuCode 去实时查询商品信息，该接口返回的是下单时的快照。

参数名	类型	必填	说明
skuCode	string	是	商品编码（科力普商品编码）
skuName	string	是	商品名称
skuSpec	string	是	规格
skuModel	string	是	型号
skuUnit	string	是	单位
quantity	int	是	采购数量
price	decimal	是	含税采购价
nakedPrice	decimal	是	未税采购价
taxRate	decimal	是	税率（0,6,9,13）
taxCode	string	是	税收编码
salePrice	decimal	否	销售含税价（属地客户）
saleNakedPrice	decimal	否	销售未税价（属地客户）

(2) 订单扩展信息 `orderExtend[]`

参数名	类型	必填	说明
orderCode	string	是	采购单号
extendName	string	否	扩展字段名
extendValue	string	否	扩展字段值

(3) 收货地址 `orderAddress`

参数名	类型	必填	说明
contactName	string	是	联系人
mobilePhone	string	是	联系电话
provinceId	int	是	省ID
provinceName	string	是	省名称
cityId	int	是	市ID
cityName	string	是	市名称
districtId	int	是	区ID
districtName	string	是	区名称
address	string	是	详细地址

响应示例

json

{
  "orderCode": "2001457555W",
  "totalAmt": 12.1252,
  "orderItems": [
    {"skuCode": "13839", "skuName": "A4打印纸80g"},
    {"skuCode": "15122", "skuName": "晨光签字笔"}
  ],
  "orderAddress": {
    "contactName": "张三",
    "address": "上海市徐汇区古美路1528号A2幢11-12层"
  },
  "orderExtend": [
    {
      "extendName": "SignOrderBackType",
      "extendValue": "签收单回传：C需复印件、N不需、O需原件"
    },
    {
      "extendName": "IsAttachDeliveryBill",
      "extendValue": "送货需求：1无、2客户发货单、3客户发货单并盖章等"
    }
  ]
}

4.2 订单发货

接口说明

供应商向系统推送订单发货信息，支持自配和三方快递两种方式。

请求方式与路径

POST /api/v1/order/delivery

请求参数

参数名	类型	必填	说明
orderCode	string	是	采购单号
clientCode	string	是	客户端编码
deliveryType	string	是	发货方式（1-自配；2-3PL快递）
storehouseId	int	否	仓库ID（仅自配）
deliveryInfo	object	否	自配发货信息
deliveryParcel	object[]	否	快递包裹列表

(1) 快递包裹列表 `deliveryParcel[]`

参数名	类型	必填	说明
expressId	int	是	快递公司编号
expressNum	string	是	快递单号
expressName	string	否	快递公司名称（可自定义）
weight	decimal	否	重量(kg)
volume	decimal	否	体积(dm³)
driverId	int	否	快递司机编号
truckId	int	否	快递车辆编号

(2) 自配发货信息 `deliveryInfo`

参数名	类型	必填	说明
truckId	string	否	车牌号
driverId	int	否	司机ID
contactName	string	否	联系人
contactPhone	string	否	联系电话
weight	decimal	否	重量(kg)
volume	decimal	否	体积(dm³)
note	string	否	发货备注

请求示例

json

{
  "clientCode": "V0001",
  "deliveryType": "2",
  "orderCode": "2001465458W",
  "deliveryParcel": [
    {"expressId": 1, "expressNum": "DPH12323321", "expressName": "德邦"}
  ]
}

响应参数

json

{ "result": true }

4.3 上传签收文件

接口说明

上传签收文件并完成签收操作。

请求方式与路径

POST /api/v1/order/uploadSignFile

请求参数

参数名	类型	必填	说明
orderCode	string	是	采购单号
clientCode	string	是	客户端编码
fileName	string	是	文件名
base64String	string	是	文件Base64字符串

示例

json

{
  "clientCode": "V0001",
  "orderCode": "2001457555W",
  "fileName": "20230111.jpg",
  "base64String": "iVBORw0KGgoAAAANSUhEUgAAA08AAAC..."
}

响应

json

{ "result": true }

4.4 批量上传签收文件

POST /api/v1/order/batchUploadSignFile

参数名	类型	必填	说明
orderCode	string	是	采购单号
clientCode	string	是	客户端编码
signFiles	object[]	是	签收文件集合

子项 `signFiles[]`

参数名	类型	必填	说明
fileName	string	是	文件名
base64String	string	是	文件Base64字符串

示例

json

{
  "clientCode": "V0001",
  "orderCode": "2001457555W",
  "signFiles": [
    {"fileName": "20230111.jpg", "base64String": "iVBORw0K..."},
    {"fileName": "20240813.jpg", "base64String": "iVBORw0K..."}
  ]
}

响应

json

{ "result": true }

4.6 查询退货采购单

GET /api/v1/return/getByReturnCode

说明

根据退货单编号查询退货信息。

参数名	类型	必填	说明
clientCode	string	是	客户端编码
returnCode	string	是	退货单号

响应结构

名称	类型	长度	必须	描述
returnCode	string	20	是	业务单据编码（退货单编码）
orderCode	string	20	是	业务单据编码（原采购单编码）
returnDate	string	20	是	退货日期（yyyy-MM-dd HH:mm:ss）
orderStatus	string	1	是	单据状态（0:取消、20:新建、90:完成）
branchId	int	4	是	分公司Id
vendorId	int	4	是	供应商Id
contractId	int	4	否	合同编号
takeType	int	4	是	取件类型（1上门取件，2快递退回）
returnItems	object[]	-	否	退单明细
senderAddress	object	-	否	寄件人、发货地址【上面取件】

退单明细（SKU明细）【returnItem】

名称	类型	长度	必须	描述
skuCode	string	100	是	商品编码（科力普商品编码）
skuName	string	300	是	商品名称
skuUnit	string	50	是	商品单位
quantity	int	4	是	退货数量
price	decimal	-	是	含税价格（4位有效数字）
nakedPrice	decimal	-	是	未税价格
taxRate	decimal	-	是	税率（0，6，9，13）

4.7 获取交货单

POST /api/v1/order/getReceiptByCode

参数名	类型	必填	说明
clientCode	string	是	客户端编码
orderCode	string	是	采购单号

响应字段（简化）

字段	说明
fileName	文件名称
fileCategory	交货单分类（RECEIPT、MARK）
fileType	文件类型（见详细说明）
fileUrl	文件地址
validityPeriod	有效期（yyyy-MM-dd HH:mm:ss）

示例

json

[
  {
    "orderCode": "2001457555W",
    "fileName": "国网商城交货单.pdf",
    "fileCategory": "RECEIPT",
    "fileType": "OutboundFormSignWithStamped",
    "fileUrl": "https://clpres.oss-cn-shanghai.aliyuncs.com/..."
  }
]

4. 订单接口 ​

4.1 订单查询 ​

接口说明 ​

请求方式与路径 ​

请求参数 ​

响应参数 ​

子结构说明 ​

(1) 订单明细 orderItems[] ​

(2) 订单扩展信息 orderExtend[] ​

(3) 收货地址 orderAddress ​

响应示例 ​

4.2 订单发货 ​

接口说明 ​

请求方式与路径 ​

请求参数 ​

(1) 快递包裹列表 deliveryParcel[] ​

(2) 自配发货信息 deliveryInfo ​

请求示例 ​

响应参数 ​

4.3 上传签收文件 ​

接口说明 ​

请求方式与路径 ​

请求参数 ​

示例 ​

响应 ​

4.4 批量上传签收文件 ​

子项 signFiles[] ​

示例 ​

响应 ​

4.6 查询退货采购单 ​

说明 ​

响应结构 ​

4.7 获取交货单 ​

响应字段（简化） ​

示例 ​

4. 订单接口

4.1 订单查询

接口说明

请求方式与路径

请求参数

响应参数

子结构说明

(1) 订单明细 `orderItems[]`

(2) 订单扩展信息 `orderExtend[]`

(3) 收货地址 `orderAddress`

响应示例

4.2 订单发货

接口说明

请求方式与路径

请求参数

(1) 快递包裹列表 `deliveryParcel[]`

(2) 自配发货信息 `deliveryInfo`

请求示例

响应参数

4.3 上传签收文件

接口说明

请求方式与路径

请求参数

示例

响应

4.4 批量上传签收文件

子项 `signFiles[]`

示例

响应

4.6 查询退货采购单

说明

响应结构

4.7 获取交货单

响应字段（简化）

示例