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

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