1.1 Kunton open platform interface document（API）

Business Process Description

This plan is mainly used for external ERP systems such as Kingdee, UFIDA, SAP, etc. to connect with Kunton; Kunton Small Warehouse can be integrated with MES, WMS, and ERP, using material requisition as outbound and replenishment as inbound. Customers can pull transaction data and summarize it in their own data center, allowing data from various systems to be collected in the center, achieving unified data management。

Document Description

(1) Interface Description

1. Unless otherwise specified, the Content Type of all interfaces is application/JSON; Charset=UTF-8
2. Unless otherwise specified, all data change types (add, modify, delete, synchronize) are batch operations, which means that the parameters of the interface are all list types, and the length of a single call to the list should not exceed 100 items. Please refer to the examples of each interface for details. During batch processing, if a processing failure is encountered, the processing will stop and a failure status code will be returned. If the data has been successfully processed, it will not be rolled back
3. Unless otherwise specified, the field units for parameters in all interfaces are in characters
4. Unless otherwise specified, the synchronization interface can be used for adding or modifying, and it is a stateless interface with no logical relationship to the previous call. When calling the interface, if it does not exist, a new data item will be created. If it exists, the data item will be updated with interface parameters
5. Unless otherwise specified, all interface response content is returned in the following data structure with an HTTP status code of 200

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

parameter description

(2) Authentication Statement

When a user accesses the Kunton Open Platform, the platform administrator will provide the corresponding appKey, secretKey, abbreviated as ak or sk. The user generates the corresponding signature information in a specified way using the key, and carries the corresponding signature information for identity authentication when accessing the platform interface. This key is very important, please keep it properly to avoid data security issues caused by key leakage。

Signature generation steps

1. Obtain the current system timestamp (in milliseconds), ensuring that the timestamp is within 10 minutes of the platform time
2. Using sk as the key of the HmacSHA256 algorithm, perform summary calculation on the content obtained from step 1
3. Output the content calculated by step 2 in base64 format
4. Splice the content calculated by ak and step 3 with English colons, i.e. symbols, as a signature

Signature usage method

1. Use the content obtained from step 1 as the value of the HTTP request header parameter X-Kt-Time
2. Use the content obtained from step 4 as the value of the HTTP request header parameter X-Kt-Authorization
3. When accessing the Kuntong Open Platform interface, attach step 1 and step 2 contents for access

Example of signature generation demo(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));
}

Example of signature generation demo(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)

Example of signature generation demo(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);
      }
   }
}

Example of calling interface - Taking the synchronization department interface as an example(Python)

import requests
import time
import hashlib
import base64
import hmac

ak = "ak"
sk = "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)

# Synchronization department
response = requests.post("https://openapi.szkunton.com/department/v1/syncDepartment",
                         json=[{"deptCode": "OpenCode123", "deptName": "OpenName123"}],
                         headers={
                             "X-Kt-Time": currentTimeStr,
                             "X-Kt-Authorization": ak + ":" + sign,
                             'Accept-Language': 'zh-CN'
                         })
print(response.text)

(3) Environmental Description

One、 Department Management

(1) Synchronize department

URL：/department/v1/syncDepartment

method：POST

parameter：

Note: The interface supports hierarchical synchronization of departments, but it is necessary to ensure that the current department’s superior department already exists, as shown in the example

response parameter：
Note：(Exists when code>=50XXX)

interface demo：

request

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

response parameter：
Note：(Exists when code>=50XXX)

{
  "errorIdx": 1
}

(2) Delete department

URL：/department/v1/deleteDepartment

method：POST

parameter：

Note：The interface supports hierarchical deletion, but it is necessary to ensure that the corresponding sub departments of the current department have been deleted, as shown in the example

response parameter：
Note：(Exists when code>=50XXX)

Note：(Exists when code>=50XXX)

interface demo：

request

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

response:

{
  "errorIdx": 1
}

Two、 Emploee management

(1) Synchronize emploee

URL：/user/v1/syncUser/

method：POST

parameter：

Note：The card number and card serial number can either be filled in simultaneously or not filled in simultaneously

response parameter：
Note：(Exists when code>=50XXX)

interface demo：

Request

[
  {
    "userCode": "test",
    "userName": "testaaa",
    "deptCode": "A100",
    "cardCode": "cardCode100",
    "cardUniqueCode": "cardUniqueCode100",
    "telephone": "15811111111",
    "email": "test@szkunton.com",
    "remark": "testbbb",
    "lockStatus": 0,
    "englishName": "test"
  }
]

Response

{
  "errorIdx": 0
}

(2) Delete emploee

URL：/user/v1/deleteUser

method：POST

request parameter：

interface demo：

Request

[
  "test", "test100"
]

(3) Synchronize emploee photos

URL：/user/v1/syncUserImg

method：POST

Content-Type：multipart/form-data

request parameter：

(4) Generate employee QR code

URL：/user/v1/createQrCode

method：Get

request parameter：

Note：The validity period of the QR code is 1 minute, and it needs to be regenerated before operation can be performed. Please note that the interface returns a serialized field string, as shown below：{\"type\":0,\"data\":\"KBALZ1ZfcAoGQUFAQAoMCipWT3xDVjVeDXdfB0FPQUFFXlhzUkh9QlptV1h2WQ==\"}，When actually generating a QR code, it is necessary to replace the escape character, that is, the final generated QR code content is：{"type":0,"data":"KBALZ1ZfcAoGQUFAQAoMCipWT3xDVjVeDXdfB0FPQUFFXlhzUkh9QlptV1h2WQ=="}

(5) Employee Bind Machine

URL：/user/v1/userBindMachine

method：Post

request parameter：

{
  "userCode": "GUEST1a9b9c",
  "deviceCodeList": ["WC0016"]
}

Three、 Product manager

(1) Synchronize product

URL：/sku/v1/syncSku

method：POST

request parameter：

interface demo：

Request

[
  {
    "skuNo": "Test123",
    "skuName": "Test product name",
    "price": 1.23,
    "description": "This is a test product",
    "manufacture": "manufacturer",
    "brand": "brand",
    "pack": "100 PCS/box",
    "unit": "PCS",
    "weight": 0.1,
    "onSale": 1
  }
]

(2) Get product on the shelves

URL：/sku/v1/listOnShelfSkus

method：GET

Request parameter：

Response content：

interface demo：

Request

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

Response

[
  {
    "skuNo":"AA0048111",
    "skuName":"A35994",
    "skuOrigin":1,
    "nodeSkuNo":"AA0048111gcbh",
    "nodeSkuName":"AA0048111 node product name",
    "unit": "个",
    "description":"This is product describe",
    "minComboPlanNum":1
    "channelDetails": [
        {
            "deviceCode": "SC0011",
            "channelLabelCodes": [9]
        }
    ]
  }
]

Four、 Transaction Management

（1）Equipment material requisition

（2）Equipment replenishment

（3）Equipment recycling materials

（4）Equipment return materials

In the currently provided transaction management interface, the query parameters are consistent with the response content fields, only the interface is different. Different types of transaction query interfaces are shown in the table below

Request parameter：

Note：The time span for a single query cannot exceed one year

Response content：

interface demo：

Request

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

Response

{
  "page": {
    "page": 1,
    "size": 20,
    "total": 100,
    "totalPage": 5
  },
  "rows": [
    {
        "tradeNumber": "TS2204291055183360523262464",
        "tradeItemNumber":"TS2204291055183360523262464001",
        "tradeTime": "2022-04-15 12:21:21",
        "deviceCode": "3344444",
        "auxiliaryDeviceCode": "XDZ017",
        "channelCode": "12",
        "channelLabelCode": "30",
        "userNo": "Test",
        "userName": "san zhang",
        "deptNo": "TestDept",
        "deptName": "Production Department",
        "projectCode": "099",
        "projectName": "R&D",
        "costCode": "3333",
        "costName": "R&D",
        "skuNo": "sku0002",
        "skuName": "Labor protection gloves a",
        "skuTaxPrice":"26" ,
        "skuNoTaxPrice": "23.01",
        "tradeNum": "1",
        "tradeTaxPrice": "26",
        "tradeNoTaxPrice":"23.01",
        "skuUnit": "piece",
        "skuPack": "12 pieces/box",
        "saleType": 1,
        "remark": "dddd"
    }
  ]
}

Five、 Inventory management

(1) Query device product inventory

URL：/stock/v1/listVmStock

method：POST

request parameter：

response content：

interface demo：

Request

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

Response

{

  "page": {
     "page": 1,
    "size": 20,
    "total": 100,
    "totalPage": 5
  },
  "rows": [
    {
       "deviceCode": "Test",
       "skuNo": "Test",
       "skuName": "Test product",
       "stockQuantity": 100
       "stockDetail": [
           {
             "channelLabelCode": 48,
             "stockQuantity": 2
           },
            {
             "channelLabelCode": 49,
             "stockQuantity": 1
           }
        ]
     }
  ]
}

Interface processing logic description

Request parameter description:
If both deviceCode and skuNo are empty, query the comprehensive equipment inventory information under the customer’s order

2. If deviceCode is not empty and skuNo is empty, query the inventory information of all products on the specified device
3. If deviceCode is not empty and skuNo is not empty, query the inventory information of the specified product on the specified device

Response content description：

1. If the customer has not bound the device or product, then rows is empty

Six、 Work Order

(1) create work order

request URL：/comboOrder/v1/createOrder

request method：POST

request parameter：

Note：

1. Within the same work order, the same product can only be ordered once, with no quantity limit
2. When orderDetails is empty, it means creating an empty work order, which only includes the work order number and not the work order details
3. If orderDetails is not empty, for each detail, select at least one of skuNo and nodeSkuNo. If both are included, it means they match at the same time
4. The product needs to be bound to the machine

Response Parameter：

note：(exist when code=60103 or 60104)

Interface demo：

request

Empty work order

{
    "orderNumber": "TEST001",
    "pickUserCode": ["KT001"]
}

Non empty work order parameter description

1. The first line of the detailed line, when the product source is 3 self built products, specify the product number
2. On the second line of the details, when the source of the product is 1 supplier, specify either the corresponding product number or the factory product number
3. In the third line of the detailed line, when the source of the product is 1 supplier, both the product number and the factory product number can be specified, but both must match. Therefore, it is recommended to use the second option

{
    "orderNumber": "TEST001",
    "pickUserCode": ["KT001"]
    "orderDetails": [
        {
            "skuOrigin": "3",
            "plannedNum": "10",
            "skuNo": "AA9293949"
        },
        {
            "skuOrigin": "1",
            "plannedNum": "10",
            "nodeSkuNo": "4-2329-694-65-1"
        },
        {
            "skuOrigin": "1",
            "plannedNum": "10",
            "skuNo": "AE3359938",
            "nodeSkuNo": "AE3359938-Test"
        }
    ]
}

(2) close work order

request URL：/comboOrder/v1/closeOrders

reqeust method：POST

request parameter：

Interface demo：

request

[
  "ORDERNUMBER_1", "ORDERNUMBER_2"
]

(3) query work order material requisition records

request URL：/comboOrder/v1/listTradeLogs

request method：POST

request parameter：

Note：The time span of a single query cannot exceed one year

response content：

Interface demo：

request

{
    "startTime": "2022-07-29 18:00:00",
    "endTime": "2022-08-10 18:00:00",
    "page": 1,
    "size": 100,
    "orderNumber": "240705BWHR"
}

response

{
    "code": 200,
    "msg": null,
    "data": {
        "page": {
            "page": 1,
            "size": 100,
            "total": 1,
            "totalPage": 1
        },
        "rows": [
            {
                "orderNumber": "XXXX",
                "userNo": "XXXX",
                "userName": "XXXX",
                "deptNo": "Y002",
                "deptName": "IT",
                "skuNo": "XY003",
                "skuName": "test 01",
                "skuUnit": "unit",
                "skuPack": "pack",
                "skuDescription": "describe of the product",
                "tradeNum": 2,
                "deviceCode": "XY3",
                "channelLabelCode": "2",
                "tradeTime": "2022-08-05 11:46:08",
                "tradeNumber": "TS2208091053392040620659200",
                "tradeItemNumber": "TS2208091053392040620659200001"
            }
        ]
    }
}

appendix：

(1) Error status code

(2) Unit enumeration list

(3) Platform auxiliary interface

The platform provides the following interfaces to assist users in debugging interfaces during the development phase