1.1. API Integration Guide

1.1.1. 📋 Quick Start

Before you start using the Qianyi API, please follow these steps to complete the integration:

1. Get Credentials - Login to QianyiERP - Setting - Three party application docking to obtain appId and appSecret
2. Choose Environment - Select test or production environment as needed
3. Build Request - Construct request parameters according to specifications
4. Generate Signature - Generate signature using MD5 algorithm
5. Send Request - Make POST request to the specified endpoint
6. Handle Response - Parse the returned JSON data

1.1.2. 🌍 Environment Configuration

Recommendation: Complete debugging in the test environment first, then switch to production after confirmation.

1.1.3. 🔧 Basic Configuration

Request Method

• HTTP Method: POST
• Content-Type: multipart/form-data
• Charset: UTF-8
• API Version: v1

URL Format

https://{domain}/api/v1/{endpoint}

Example: https://www.qianyierp.com/api/v1/asn

1.1.4. 📝 Request Parameter Specification

Required Common Parameters

🔐 Signature Generation Steps

Signature is an important mechanism to ensure API request security. Please follow these steps strictly:

Step 1: Parameter Sorting Sort all parameters except sign in ascending order by parameter name ASCII code

Step 2: String Concatenation Concatenate all parameters in the format parameter=value, finally append appSecret

Format: appId=valuebizParam=valueserviceType=valuetimestamp=value{appSecret}

Step 3: MD5 Encryption Perform MD5 encryption on the concatenated string to get a 32-bit lowercase signature

Signature Algorithm Examples

Java Implementation:

package com.example.qianyi.sign;
import org.springframework.util.DigestUtils;
import java.nio.charset.StandardCharsets;

public class SignUtils {

    /**
     * Generate API signature
     */
    public static String generateSign(String appId, String bizParam, 
                                    String serviceType, Long timestamp, String appSecret) {
        String signStr = buildSignString(appId, bizParam, serviceType, timestamp, appSecret);
        return DigestUtils.md5DigestAsHex(signStr.getBytes(StandardCharsets.UTF_8));
    }

    /**
     * Build signature string
     */
    private static String buildSignString(String appId, String bizParam, 
                                        String serviceType, Long timestamp, String appSecret) {
        return "appId=" + appId +
               "bizParam=" + bizParam +
               "serviceType=" + serviceType + 
               "timestamp=" + timestamp +
               appSecret;
    }
}

Python Implementation:

import hashlib

def generate_sign(app_id, biz_param, service_type, timestamp, app_secret):
    """Generate API signature"""
    sign_str = f"appId={app_id}bizParam={biz_param}serviceType={service_type}timestamp={timestamp}{app_secret}"
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest()

🔍 Detailed Signature Example

Request Parameters:

appId: openApi_TEST
serviceType: CREATE_ASN_ORDER
bizParam: {"asnSkuVOList":[{"expectQuantity":"100","sku":"SKU1230"}],"warehouseName":"Test Warehouse"}
timestamp: 1662448537275
appSecret: openApi_TOKEN

Concatenated String:

appId=openApi_TESTbizParam={"asnSkuVOList":[{"expectQuantity":"100","sku":"SKU1230"}],"warehouseName":"Test Warehouse"}serviceType=CREATE_ASN_ORDERtimestamp=1662448537275openApi_TOKEN

Generated Signature:

sign: b3dfeed438e36f1f89534ce415cf4113

1.1.5. 📤 Complete Request Examples

cURL Example

curl -X POST "https://gerp-test1.800best.com/api/v1/asn" \
  -F "appId=openApi_TEST" \
  -F "serviceType=CREATE_ASN_ORDER" \
  -F "bizParam={\"warehouseName\":\"Test Warehouse\"}" \
  -F "timestamp=1662448537275" \
  -F "sign=b3dfeed438e36f1f89534ce415cf4113"

Postman Configuration

1. Method: POST
2. URL: https://gerp-test1.800best.com/api/v1/asn
3. Body: form-data
4. Add Parameters: Add all required parameters according to the table above

1.1.6. 📥 Response Format

Standard Response Structure

Success Response Example

{
  "errorCode": "0",
  "errorMsg": "",
  "state": "success",
  "bizContent": "{\"orderId\":\"12345\",\"status\":\"created\"}"
}

Error Response Example

{
  "errorCode": "AUTH_001",
  "errorMsg": "Signature verification failed",
  "state": "failure",
  "bizContent": ""
}

1.1.7. ⚠️ Common Issues

Signature Error

• Check: Parameter sorting is correct
• Check: Character encoding is UTF-8
• Check: appSecret is correctly appended at the end

Timestamp Error

• Suggestion: Use current timestamp, error within 5 minutes
• Format: 13-digit millisecond timestamp

Parameter Format Error

• bizParam: Must be a valid JSON string
• Content-Type: Must use multipart/form-data

1.1.8. 🔗 Related Links

• Error Codes
• Rate Limits
• Enum Definitions