Hanshow Data Integration API v2.0

Hanshow Data Integration API

V2.0

HS-INTEGRATION-General-B01

ABOUT THE DOCUMENT

The document mainly introduces key points of related interfaces such as interface description, address, request parameter and so on to help you to implement interface automation.

Please read this document carefully before using this system, retain the document for subsequent use or for the next owner. If the instructions contained in this manual are insufficient to resolve issues that occur during device operation or maintenance, please contact Hanshow Technical Customer Service Center (400-0365-305) directly, we will provide you with multi-channel technical services.

TARGET USERS

This file is suitable for reading and using by the following engineers:

Hand-held device developer
Technical support engineer
Java software engineer
Other language engineer

SYMBOL DESCRIPTION

Icon	Description
	Information indicated with this icon should be paid special attention to by the reader
	Information indicated with this icon is the explanation on the formal text for the readers to comprehend the text better
[X-X]	It means special noun definition is provided here

EXPLANATION OF TERMS

Term	Expanded form	Description
AP	Wireless Access Point	ESL control
API	Application Programming Interface	A set of predefined functions for applications and developers to access a routine based on a software or hardware, without having to access source code or understand detailed working mechanism
ESL	Electronic Shelf Label	ESL
PriSmart	PriSmart Smart Retail System	Manages all store product data and sends ESL updates, supports multi-store management.

1 Read before starting

In the development of system access, the system needs to meet the specifications and call frequency restrictions of each interface and to pay special attention to the use of sensitive information such as messages and data. Please call it in strict accordance with the specifications, and make sure you have fully test before use.

Please pay attention to the following information when it involves user data:

After you collect the transferring available data, you must take necessary protective measures to prevent data from being stolen or leaked.
Once you stop using this service, or we terminate your use of this service for some reason, please stop service and data access.

2 API

2.1 Integration interface (JSON data integration)

2.1.1 Interface meaning

Performs integration for the functions including updating and adding of product data (JSON data). Option: bind the product with ESL after updating and adding product data.

2.1.2 Request instruction

URL: https://{site}.hanshowcloud.net/integration/{customer_code}/{store_code}

Request Method: POST

2.1.3 Sample request

2.1.3.1 Token Obtain API

Header:

Key: Authorization

Value: Basic Z3Vlc3Q6WjNWbGMzUQ==

Z3Vlc3Q6WjNWbGMzUQ== is the Key provided by Hanshow for each client Request Method: POST

URL：https://xxx.hanshowcloud.net/proxy/token

Return result:

Succeed

json

http status: 200 
return content：
{
"access_token":eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxNzMxNTc5MzE1NzM0MzE1MDA4, 
"token_type": "Bearer"
}

Failed

json

http status: 401
return content：
{
    "resultCode": 1005,
    "result": "UNAUTHORIZED",
    "message": "Basic credentials failed"
}

json

http status: 400
return content：
{
    "resultCode": 1006, 
    "result": "Bad Request",
    "message": "Missing or invalid basic header"
}

json

http status: 500
return content：
{
    "resultCode": 1010,
    "result": "cdi_internal_error",
    "message": "Internal error: JWT creation failed"
}

2.1.3.2 Sample for updating and adding product

Only update or add product data:

Header:

Key: Authorization

Value: Bearer {access_token}

Request Method: POST

URL: https:// xxx.hanshowcloud.net/proxy/integration/{customerCode}/

Request Body(eg.):

json

{
"customerStoreCode": "Metro", 
"storeCode": "5000",
"batchNo": "2023121112385228001",
    "items": [
        {
        "IIS_COMMAND": "UPDATE", "sku": "2100000016"
        "itemName": "King Apple", "ean": "000346",
        "price1": "12.00",
        "price1_description": "Selling Price", "unit": "kg",
        "grade": "advanced", "supplier_name": "FarmBoy"
        }
    ]
}

Return Results:

1. Succeed

json

http status: 200
Return content：
{
	"resultCode": 1001, 
	"result": "succeed", 
	"message": "succeed"
}

2. Failed

json

http status: 400
Return content:
{
    "resultCode": 1406,
    "result": "cdi_store_not_exist", 
    "message": "The store not exist"
}

json

http status: 400
Return content:
{
    "resultCode": 1401,
    "result": "cdi_illegal_integration_data",
    "message": "The number of batches cannot exceed 0"
}

json

http status: 200
Return content:
{
    "resultCode": 1003,
    "result": "cdi_illegal_field_value_format", 
    "message": "Illegal field value format", 
    "data": {
            "1002": [
            "$.items[0].itemName: integer found, string expected"
            ]
        }
}

json

http status:401
Return content:
{
    "resultCode": 1005,
    "result": "UNAUTHORIZED", 
    "message": " UNAUTHORIZED",
    "data": null,
}

json

http status: 400 
Return content:
{
    "resultCode": 1006, 
    "result": "Bad Request",
    "message": "Missing or invalid Authorization header", 
    "data": null,
}

json

http status: 400
Return content:
{
    "resultCode": 1004,
    "result": "cdi_json_data_parse_error", 
    "message": "Json data parse error",
    "data": null,
}

json

http status: 400
Return content:
{
    "resultCode": 1010,
    "result": "cdi_internal_error", 
    "message": "Internal error",
    "data": null
}

json

http status: 401
Return content:
{
    "resultCode": 1005,
    "result": "UNAUTHORIZED",
    "message": "API-Key Failed"
}

json

http status: 400
Return content:
{
    "resultCode": 1006, 
    "result": "Bad Request",
	"message": "Missing or invalid API KEY header"
}

2.1.3.3 Additional Instructions for IIS_COMMAND:

IIS_COMMAND: String. Required. Operation type. Values include:

UPDATE:

Adding new product or incremental update of existing product data, that is, only updating product attributes in the update interface without changing other attributes. If the product is bound to an ESL, the update will be simultaneously sent to the ESL.

COMPLETE_UPDATE:

Overwrite update of all product data. Product attributes not provided in the interface will be set to the default values. If the product is bound to an ESL, the update will be simultaneously sent to the ESL. ® BIND: Binding products with ESLs according to product SKU and ESL ID.

BIND:

Binding product and ESL according to product SKU and ESL ID.

UNBIND_GOODS:

Unbinding product from ESL according to product SKU.

UNBIND_ESLID:

Unbinding product from ESL according to ESL ID.

UNBIND_DELETE_GOODS:

Unbinding product from ESL according to product ID and simultaneously deleting the product.

CUTPAGE_FLASHLIGHTS:

Controlling page switch and/or flashing according to ESL ID or product SKU. If both ESL ID or product SKU are provided, the system will execute the command on both the ESL bound to the product SKU and the ESL corresponding to the ESL ID.

If IIS_COMMAND is set to UPDATE or COMPLETE_UPDATE, the parameters include:

customerStoreCode: String. Required. Customer ID.