1.1 坤同开放平台接口文档（API）

业务流程说明

此方案主要用户金蝶、用友、SAP等外部ERP系统与坤同对接；坤同的自助领料可对接MES、WMS、ERP，将领料作为出库，补货作为入库，客户拉到交易数据后在自身数据中台做汇总，让各个系统的数据汇集在中台，实现数据统一化管理。

一般需要对接：

1. 基础数据同步或映射
2. 出入库相关接口：（1）交易记录查询：对应wms的出入库记录 （2）库存查询
3. 其余接口根据自身需要对接
   

文档说明

(1) 接口说明

1. 无特殊说明情况下，所有的接口的Content-Type均为application/json;charset=UTF-8
2. 无特殊说明情况下，所有的数据变更类型(新增、修改、删除、同步)均为批量操作，即接口的参数均为list类型，且单次调用list长度不应超过100项，详见各个接口的示例，批量处理时，如果遇到处理失败，则停止处理，并且返回失败状态码，已成功处理数据不会回滚
3. 无特殊说明情况下，所有接口中参数的最大长度字段单位均为字符
4. 无特殊说明情况下，同步接口可用于新增、修改，且同步接口为无状态接口，与前一次调用无逻辑关系，接口调用时，如果不存在，则新建该数据项，如果存在，则以接口参数更新该数据项
5. 无特殊说明情况下，所有接口响应内容均以如下数据结构返回，HTTP状态码为200

{
  "code": xxx,
  "msg": xxx,
  "data": xxx
}

参数说明

(2) 鉴权说明

用户接入坤同开放平台时，平台管理员会提供对应的appKey、secretKey，简称ak、sk，该key在使用时区分环境，即测试、生产环境所对应的key不同，用户凭借key按照指定方式生成对应的签名信息，并且在访问平台接口时携带相应的签名信息用于身份鉴定，该key非常重要，请妥善保管，避免因key泄露导致的数据安全问题。

签名生成步骤

1. 获取当前系统时间戳(毫秒级)，注意该时间戳与平台时间保持在10min差距以内
2. 将sk作为HmacSHA256算法的key，对1获取的内容进行摘要计算
3. 将2计算的内容以base64形式输出
4. 将ak、3计算的内容以英文冒号，即 : 符号拼接，作为签名

签名使用方式

1. 将1获取的内容作为HTTP请求头参数X-Kt-Time的值
2. 将4获取的内容作为HTTP请求头参数X-Kt-Authorization的值
3. 在访问坤同开放平台接口时，附带1、2内容进行访问即可

签名生成方式示例(Java)

public static void main(String[] args) throws Exception {
  String ak = "your_ak";
  String sk = "your_sk";

  Charset utf8 = StandardCharsets.UTF_8;

  String currentTimeStr = 
    String.valueOf(System.currentTimeMillis());
  Mac mac = Mac.getInstance("HmacSHA256");
  SecretKeySpec secretKeySpec = 
     new SecretKeySpec(sk.getBytes(utf8), "HmacSHA256");
  mac.init(secretKeySpec);
    byte[] digest = mac.doFinal(currentTimeStr.getBytes(utf8));

  String sign = Base64.getEncoder().encodeToString(digest);

  System.out.println("currentTime: " + currentTimeStr);
  System.out.println(String.join(":", ak, sign));
}

签名生成方式示例(Python)

import time
import hashlib
import base64
import hmac

ak = "your_ak"
sk = "your_sk"

currentTimeStr = str(int(time.time() * 1000))

digest = hmac.new(
    bytes(sk, "UTF-8"), 
    bytes(currentTimeStr, "UTF-8"), 
    hashlib.sha256
  )

sign = base64.b64encode(digest.digest()).decode()

print("currentTime:", currentTimeStr)
print("sign", ak + ":" + sign)

签名生成方式示例(C#)

using System;
using System.Security.Cryptography;
using System.Text;
namespace HelloWorldApplication
{
   class HelloWorld
   {      static void Main(string[] args)
      {
        string ak = "your_ak";
        string sk = "your_sk";

        Encoding utf8 = Encoding.UTF8;

        string currentTimeStr = DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalMilliseconds.ToString("F0");
        HMACSHA256 mac = new HMACSHA256(Encoding.UTF8.GetBytes(sk));        byte[] digest = mac.ComputeHash(Encoding.UTF8.GetBytes(currentTimeStr));

        string sign = Convert.ToBase64String(digest);

        Console.WriteLine("currentTime: " + currentTimeStr);
        Console.WriteLine(ak + ":" + sign);
      }
   }
}

(3) 环境说明

一、 部门管理

(1) 同步部门

请求URL：/department/v1/syncDepartment

请求方式：POST

请求参数：

注：接口支持层级同步部门，但需确保当前部门的上级部门已经存在，如例子所示

响应参数：

注：(code>=50XXX时存在)

接口示例：

请求

[
  {
    "deptCode": "Openy",
    "deptName": "Open-y 测试"
  },
  {
    "deptCode": "Openy1",
    "deptName": "Open-y-1 测试",
    "parentCode": "Openy"
  },
  {
    "deptCode": "Openy11",
    "deptName": "Openy11 测试",
    "parentCode": "Openy1"
  }]

响应

{
  "errorIdx": 1
}

(2) 删除部门

请求URL：/department/v1/deleteDepartment

请求方式：POST

请求参数：

注：接口支持层级删除，但需确保当前部门对应的子部门已经删除，如例子所示

响应参数：

注：(code>=50XXX时存在)

接口示例：

请求

[
  "Openy11", "Openy1", "Openy"
]

响应

{
  "errorIdx": 1
}

二、 员工管理

(1) 同步员工

请求URL：/user/v1/syncUser/

请求方式：POST

请求参数：

注：卡号、卡序列号要么同时填写，要么同时不填写

响应参数：

注：(code>=50XXX时存在)

接口示例：

请求

[
  {
    "userCode": "test",
    "userName": "测试账号",
    "deptCode": "A100",
    "cardCode": "cardCode100",
    "cardUniqueCode": "cardUniqueCode100",
    "telephone": "15811111111",
    "email": "test@szkunton.com",
    "remark": "测试账号",
    "lockStatus": 0,
    "englishName": "test"

  }
]

响应

{
  "errorIdx": 0
}

(2) 删除员工

请求URL：/user/v1/deleteUser

请求方式：POST

请求参数：

接口示例：

请求

[
  "test", "test100"
]

(3) 同步员工照片

请求URL：/user/v1/syncUserImg

请求方式：POST

Content-Type：multipart/form-data

请求参数：

(4) 生成员工二维码

请求URL：/user/v1/createQrCode

请求方式：Get

请求参数：

注：二维码有效期为1min，过期需要重新生成才能进行操作，特别注意，该接口返回内容为序列化后的字段串，如下所示：{\"type\":0,\"data\":\"KBALZ1ZfcAoGQUFAQAoMCipWT3xDVjVeDXdfB0FPQUFFXlhzUkh9QlptV1h2WQ==\"}，在实际生成二维码时，需要将转义符进行替换，即最终生成的二维码内容为：{"type":0,"data":"KBALZ1ZfcAoGQUFAQAoMCipWT3xDVjVeDXdfB0FPQUFFXlhzUkh9QlptV1h2WQ=="}

三、 商品管理

(1) 同步商品

请求URL：/sku/v1/syncSku

请求方法：POST

请求参数：

接口示例：

请求

[
  {
    "skuNo": "Test123",
    "skuName": "测试商品名称",
    "price": 1.23,
    "description": "这是一个测试商品",
    "manufacture": "制造厂商",
    "brand": "品牌",
    "pack": "100个/盒",
    "unit": "个",
    "weight": 0.1,
    "onSale": 1
  }
]

(2) 获取在架商品

请求URL：/sku/v1/listOnShelfSkus

请求方法：GET

请求参数：

响应内容：

接口示例：

请求

GET /sku/v1/listOnSaleSkus?showMinComboPlanNum=true&skuNo=AA0048111

响应

[
  {
    "skuNo":"AA0048111",
    "skuName":"断丝取出器套装1-evm测试5",
    "skuOrigin":1,
    "nodeSkuNo":"AA0048111gcbh",
    "nodeSkuName":"AA0048111工厂商品名称",
    "unit": "个",
    "description":"这是商品描述",
    "minComboPlanNum":1,

    "channelDetails": [
        {
          "deviceCode": "SC0011",
          "channelLabelCodes": [
            9
          ]
        }
    ]
  }
]

四、 交易管理

（1）设备领料

（2）设备补货

（3）设备还料

（4）设备退货

（5）设备盘点

（6）智能仓领料

（7）智能仓补货

当前提供的交易管理接口中，查询的参数与响应内容字段一致，仅接口不同，不同类型交易查询接口如下表所示

请求参数：

注：单次查询时间跨度不能超过一年

响应内容：

接口示例：

请求

{
    "page": 1,
    "size": 20,
    "startTime": "2022-04-10 00:00:00",
    "endTime": "2022-04-20 00:00:00",
    "deviceCode": "Test",
    "skuNo": "test"
}

响应

{
    "page": {
        "page": 1,
        "size": 20,
        "total": 100,
        "totalPage": 5
    },
    "rows": [
        {
            "tradeNumber": "TS2204291055183360523262464",
            "tradeItemNumber": "TS2204291055183360523262464001",
            "tradeTime": "2022-04-15 12:21:21",
            "deviceCode": "主机设备编号",
            "auxiliaryDeviceCode": "XDZ017",
            "channelCode": "12",
            "channelLabelCode": "30",
            "userNo": "Test",
            "userName": "张三",
            "deptNo": "TestDept",
            "deptName": "生产部",
            "projectCode": "项目编号",
            "projectName": "项目名称",
            "costCode": "成本中心编号",
            "costName": "成本中心名称",
            "skuNo": "sku0002",
            "skuName": "劳保手套a",
            "skuTaxPrice": "26",
            "skuNoTaxPrice": "23.01",
            "tradeNum": "1",
            "tradeTaxPrice": "26",
            "tradeNoTaxPrice": "23.01",
            "skuUnit": "个",
            "skuPack": "12个/盒",
            "saleType": 1,
            "remark": "这是备注"
        }
    ]
}

五、 库存管理

(1) 查询设备商品库存

请求URL：/stock/v1/listVmStock

请求方法：POST

请求参数：

响应内容：

接口示例：

请求

{
    "page": 1,
    "size": 20,
    "deviceCode": "Test",
    "skuNo": "Test"
}

响应

{
    "page": {
        "page": 1,
        "size": 20,
        "total": 100,
        "totalPage": 5
    },
    "rows": [
        {
            "deviceCode": "Test",
            "skuNo": "Test",
            "skuName": "测试商品",
            "stockQuantity": 100,
            "stockDetail": [
                {
                    "channelLabelCode": 48,
                    "stockQuantity": 2,
                    "channelCapacity": 5
                },
                {
                    "channelLabelCode": 49,
                    "stockQuantity": 1,
                    "channelCapacity": 8
                }
            ]
        }
    ]
}

接口处理逻辑说明

请求参数说明:

1. customerSkuNo、skuNo说明
   1. 同时查询则表示需要匹配两者
   2. 如果与震坤行合作，且需要查询震坤行物料，则传skuNo，如果需要查询自定义物料编号，则传customerSkuNo(需提前维护)
   3. 如果非与震坤行合作，则传skuNo即可
2. 如果deviceCode、skuNo同时为空，则查询客户下全面设备库存信息
3. 如果deviceCode非空，skuNo为空，则查询指定设备所有商品库存信息
4. 如果deviceCode非空，skuNo非空，则查询指定设备指定商品库存信息

响应内容说明：

1. 如果客户未绑定设备或者未绑定商品，则rows为空

六、 领料工单

(1) 新建领料工单

请求URL：/comboOrder/v1/createOrder

请求方法：POST

请求参数：

注：

1. 同一个工单内，同一种商品仅能下单一次，数量不限制
2. 当orderDetails为空时，表示创建空工单，即工单仅包含工单号，不包含工单明细
3. 如果orderDetails非空时，对于每一个明细，skuNo、nodeSkuNo至少选择包含一个，如果包含两者，则表示同时匹配

响应参数：

注：(code=60103、60104时存在)

接口示例：

请求

空工单

{
    "orderNumber": "TEST001",
    "pickUserCode": "领用员工",
    "remark": "备注"
}

非空工单

1. 明细行第一行仅指定商品编号
2. 明细行第二行仅指定工厂商品编号
3. 明细行第三行同时指定商品编号、工厂商品编号

{
    "orderNumber": "TEST001",
    "pickUserCode": "领用员工",
    "remark": "备注",
    "orderDetails": [
        {
            "skuOrigin": "1",
            "plannedNum": "10",
            "skuNo": "AA9293949"
        },
        {
            "skuOrigin": "1",
            "plannedNum": "10",
            "nodeSkuNo": "4-2329-694-65-1"
        },
        {
            "skuOrigin": "1",
            "plannedNum": "10",
            "skuNo": "AE3359938",
            "nodeSkuNo": "AE3359938-Test"
        }
    ]
}

(2) 关闭领料工单

请求URL：/comboOrder/v1/closeOrders

请求方法：POST

请求参数：

接口示例：

请求

[
  "ORDERNUMBER_1", "ORDERNUMBER_2"
]

(3) 查询领料记录

请求URL：/comboOrder/v1/listTradeLogs

请求方法：POST

请求参数：

注：单次查询时间跨度不能超过一年

响应内容：

接口示例：

请求

{
    "startTime": "2022-07-29 18:00:00",
    "endTime": "2022-08-10 18:00:00",
    "page": 1,
    "size": 100,
    "orderNumbers": [

    ]
}

响应

{
    "code": 200,
    "msg": null,
    "data": {
        "page": {
            "page": 1,
            "size": 100,
            "total": 1,
            "totalPage": 1
        },
        "rows": [
            {
                "orderNumber": "XXXX",
                "userNo": "XXXX",
                "userName": "XXXX",
                "deptNo": "Y002",
                "deptName": "产品部",
                "skuNo": "XY003",
                "skuName": "测试产品3",
                "skuUnit": null,
                "skuPack": null,
                "skuDescription": "测试商品描述",
                "tradeNum": 2,
                "deviceCode": "XY3",
                "channelLabelCode": "2",
                "tradeTime": "2022-08-05 11:46:08",
                "tradeNumber": "TS2208091053392040620659200",
                "tradeItemNumber": "TS2208091053392040620659200001"
            }
        ]
    }
}

七、 对账单查询

1、对账单查询–总账

请求参数：

响应内容：

接口示例：

请求

{
    "page": 1,
    "size": 50,
    "beginSettlementDate": "2021-11-03",
    "endSettlementDate": "2021-11-10",
    "costCode": null
}

响应

{
    "page": {
        "page": 1,
        "size": 50,
        "total": 1,
        "totalPage": 1
    },
    "rows": {
        "beginSettlementDate": "2022-07-02",
        "endSettlementDate": "2022-07-02",
        "settlementDate": "2022-07-03",
        "costCode": null,
        "costName": null,
        "taxStatus": true,
        "settlementTotalPrice": 0.09
    }
}

(1) 对账单明细账—按员工汇总

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null
}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1

  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "userNo": "111",
        "userName": "111",
        "tradePrice": 0.01
      }
    ]
  }
}

(2) 对账单明细账—交易明细

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null
}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1

  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "tradeNumber": "TS2209011141251190648207360",
        "tradeItemNumber": "TS2209011141251190648260001",
        "tradeTime": null,
        "tradeNum": 9,
        "deviceCode": "LC0002",
        "auxiliaryDeviceCode": null,
        "channelCode": null,
        "channelLabelCode": 19,
        "userNo": null,
        "userName": null,
        "deptNo": null,
        "deptName": null,
        "projectCode": "Project018",
        "projectName": "项目名称018",
        "costCode": "CostCode043",
        "costName": "成本中心名称043",
        "skuNo": null,
        "skuName": null,
        "skuTaxPrice": null,
        "tradeTaxPrice": null,
        "skuNoTaxPrice": null,
        "tradeNoTaxPrice": null,
        "skuUnit": null,
        "skuPack": null,
        "saleType": 0,
        "remark": null
      }
    ]
  }
}

(3) 对账单明细账—按部门汇总

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null
}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1

  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "deptNo": "111",
        "deptName": "111",
        "tradePrice": 0.01,
      }
    ]
  }
}

(4) 对账单明细账—按商品分类汇总

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null
}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1

  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "skuTypeCode": "111",
        "skuTypeName": "111",
        "tradePrice": 0.01,
      }
    ]
  }
}

(5) 对账单明细账—按员工领用商品汇总

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null

}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1

  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "tradeNum": 10,
        "userNo": "111",
        "userName": "111",
        "skuNo": "111",
        "skuName": "111",
        "skuPrice": 0.01,
        "tradePrice": 0.09,
        "nodeSkuCode": "111",
        "nodeSkuName": "111",
      }
    ]
  }
}

(6) 对账单明细账—按部门领用商品汇总

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null
}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1
  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "tradeNum": 10,
        "deptNo": "111",
        "deptName": "111",
        "skuNo": "111",
        "skuName": "111",
        "skuPrice": 0.01,
        "tradePrice": 0.09,
        "nodeSkuCode": "111",
        "nodeSkuName": "111",
      }
    ]
  }
}

(7) 对账单明细账—按商品汇总

请求参数：

注：查询参数的对账周期起始时间必须和实际的对账周期起始时间一致，成本中心为空时只能查询到成本中心为空的数据

响应内容：

接口示例：

请求

{
  "page": 1,
  "size": 50,
  "beginSettlementDate": "2021-11-03",
  "endSettlementDate": "2021-11-10",
  "costCode": null
}

响应

{
  "page": {
    "page": 1,
    "size": 50,
    "total": 1,
    "totalPage": 1

  },
  "settlement": {
    "beginSettlementDate": "2022-07-02",
    "endSettlementDate": "2022-07-02",
    "costCode": null,
    "costName": null,
    "taxStatus": true,
    "settlementTotalPrice": 0.09,
    "rows": [
      {
        "tradeNum": 10,
        "skuNo": "111",
        "skuName": "111",
        "skuPrice": 0.01,
        "tradePrice": 0.09,
        "nodeSkuCode": "111",
        "nodeSkuName": "111",
      }
    ]
  }
}

八、 成本中心管理

注：此模块接口用于震坤行客户的物料开票结算，如非震坤行客户，则按需使用

(1) 同步成本中心

请求URL：/cost/v1/syncCost

请求方式：POST

请求参数：

接口示例：

请求

[
    {
        "costCode": "CostTest",
        "costName": "成本中心测试"
    }
]

(2) 同步成本中心员工

请求URL：/cost/v1/syncCostUser

请求方式：POST

请求参数：

响应参数：

注：如果costCode为空，则表示将userCodes对应的员工从成本中心移出
接口示例：

请求

[
    {
        "costCode": "CostTest",
        "userCodes": [
            "test"
        ]
    },
    {
        "costCode": "CostTest01",
        "userCodes": [
            "test01",
            "test02",
            "test03"
        ]
    }
]

响应

{
    "errorIdx": 1
}

注：当code=80102/80103时，errorIdx字段存在

附录：

(1) 错误状态码

(2) 单位枚举表

(3) 平台辅助接口

平台提供如下接口，用于开发阶段辅助用户调试接口

(4) 文档更新记录