Open Hupun

https://open.hupun.com/
Admin
Open Hupun is an open platform API for Hupun ERP system that enables developers to integrate Hupun...
Tokens:10,178
Snippets:90
Trust Score:8.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example of String with Secret for Signature

Source: https://open.hupun.com/guide/api-spec

This demonstrates the string format after prepending and appending the secret key to the URL-encoded parameter string, prior to MD5 hashing.

```text
ea5b29320cb3d15a9883c1fa4654bd02_app=3823532979&_t=1672213377&bill_code=OFL20221212164119384010001%2COFL20221212155533384009005&limit=200&page=1&query_extend=%7B%22query_relation_trade%22%3Atrue%2C%22encry_address%22%3Atrue%7Dea5b29320cb3d15a9883c1fa4654bd02
```

--------------------------------

### Example of URL-encoded Form Data

Source: https://open.hupun.com/guide/api-spec

This example shows how parameters are encoded and concatenated into a string for signature generation. Ensure values are URL-encoded using functions like `URLEncoder.encode()` or `encodeURIComponent()`.

```text
_app=3823532979&_t=1672213377&bill_code=OFL20221212164119384010001%2COFL20221212155533384009005&limit=200&page=1&query_extend=%7B%22query_relation_trade%22%3Atrue%2C%22encry_address%22%3Atrue%7D
```

--------------------------------

### 查询ERP订单发货状态

Source: https://open.hupun.com/guide/erp-djcj

商城可通过此接口轮训查询订单在万里牛ERP中的发货状态。

```APIDOC
## GET trades/erp/status

### Description
查询万里牛ERP中订单的发货状态。

### Method
GET

### Endpoint
/trades/erp/status

### Parameters
#### Query Parameters
- **trade_id** (string) - Required - 订单 ID

### Response
#### Success Response (200)
- **status** (int) - 订单发货状态
- **delivery_code** (string) - 物流公司编码
- **delivery_name** (string) - 物流公司名称
- **waybill** (string) - 物流单号

#### Response Example
```json
{
  "status": 1, 
  "delivery_code": "EMS",
  "delivery_name": "EMS快递",
  "waybill": "1234567890"
}
```
```

--------------------------------

### 商城售后单接口

Source: https://open.hupun.com/guide/erp-zysc

通过此接口实现将商城的售后单推送至ERP进行处理。当前已支持仅退款类型和退货类型售后。

```APIDOC
## erp/b2c/refunds/open

### Description
推送售后单至万里牛ERP（如信息更新重推即可）

### Method
POST

### Endpoint
/erp/b2c/refunds/open

### Parameters
#### Request Body
- **refund_id** (string) - Required - 售后单ID
- **trade_id** (string) - Required - 关联的订单ID
- **reason** (string) - Required - 退款原因
- **type** (string) - Required - 售后类型 (e.g., "refund", "return")
- **amount** (number) - Required - 退款金额

### Request Example
```json
{
  "refund_id": "REFUND001",
  "trade_id": "TRADE789",
  "reason": "商品质量问题",
  "type": "return",
  "amount": 50.00
}
```

### Response
#### Success Response (200)
- **success** (boolean) - 调用是否成功
- **message** (string) - 成功或失败信息

#### Response Example
```json
{
  "success": true,
  "message": "售后单推送成功"
}
```
```

--------------------------------

### Sending the Request

Source: https://open.hupun.com/guide/api-spec

After generating the `_sign` parameter, include it along with other system and business parameters in your POST request.

```APIDOC
## Sending the Request

Once the `_sign` is generated according to the algorithm, include it as a form parameter in your POST request. The complete set of parameters (system and business) along with the `_sign` will be sent to the server.
```

--------------------------------

### Signature Generation Algorithm

Source: https://open.hupun.com/guide/api-spec

This section details the step-by-step process for generating the `_sign` parameter, which is crucial for API authentication and data integrity.

```APIDOC
## Signature Generation Algorithm

To generate the `_sign` parameter, follow these steps:

### Step 1: Sort All Parameter Names
Sort all parameter names (including system and business parameters, excluding `_sign`) in natural programming language order (ASCII order).

### Step 2: Concatenate All Parameters into a String
Concatenate all parameters in the sorted order into a string with the format `key1=value1&key2=value2&...`. Ensure each parameter value is URL-encoded using functions like `URLEncoder.encode()` or `encodeURIComponent()`.

### Step 3: Prepend and Append Secret
Concatenate your `secret` to the beginning and end of the string generated in Step 2. The format is `secret` + `string` + `secret`.

### Step 4: Calculate the MD5 Hash
Compute the MD5 hash of the final string from Step 3. This hash value is your `_sign`.
```

--------------------------------

### 库存同步接口

Source: https://open.hupun.com/guide/erp-djcj

用于将自有商城的库存信息同步到万里牛ERP。

```APIDOC
## POST /erp/open/inventory/syn

### Description
同步自有商城的库存信息至万里牛ERP。

### Method
POST

### Endpoint
/erp/open/inventory/syn

### Parameters
#### Request Body
- **sku_no** (string) - Required - 商品规格编码 (若无规格则使用商品编码)
- **quantity** (int) - Required - 库存数量

### Request Example
```json
{
  "sku_no": "SKU123-RED",
  "quantity": 50
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### 商品资料推送接口

Source: https://open.hupun.com/guide/erp-djcj

通过此接口实现商城的单品、套装商品与万里牛的单品、组合商品的对应。

```APIDOC
## POST /erp/b2c/items/open

### Description
推送商品资料至万里牛ERP。

### Method
POST

### Endpoint
/erp/b2c/items/open

### Parameters
#### Request Body
- **itemcode** (string) - Required - 商品编码
- **sku_code** (string) - Optional - 商品规格编码
- **status** (int) - Optional - 商品状态 (0:停用, 1:启用)

### Request Example
```json
{
  "itemcode": "SKU123",
  "sku_code": "SKU123-RED",
  "status": 1
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Generate Signature in Java

Source: https://open.hupun.com/guide/sdk

This Java code demonstrates how to generate a signature for API requests by signing parameters with your AppKey and Secret. It includes utility methods for MD5 hashing and URL encoding.

```Java
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HashMap;
import java.util.Map;
import java.util.TreeMap;
import java.util.Map.Entry;

public class ApiExample {

    public static void main(String[] args) {
        try {
            // 示例业务参数
            Map<String, String> parameters = new HashMap<>();
            parameters.put("param1", "value1");
            parameters.put("param2", "value2");

            // AppKey 和 Secret
            String appKey = "yourAppKey";
            String secret = "yourSecret";

            // 获取签名后的参数集合
            Map<String, String> signedParameters = signParameters(parameters, appKey, secret);

            // 打印签名后的参数集合
            for (Entry<String, String> entry : signedParameters.entrySet()) {
                System.out.println(entry.getKey() + ": " + entry.getValue());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * 对传入的参数集合进行签名处理
     *
     * @param parameters 带有业务参数的Map
     * @param appKey 您的AppKey
     * @param secret 您的Secret
     * @return 返回
     * @throws IOException
     */
    public static Map<String, String> signParameters(Map<String, String> parameters, String appKey, String secret) throws UnsupportedEncodingException {
        // 利用TreeMap对参数按key进行排序
        Map<String, String> tree = new TreeMap<>(parameters);
        tree.put("_app", appKey);
        tree.putIfAbsent("_t", String.valueOf(System.currentTimeMillis()));

        // 拼接参数串
        String content = join(tree);

        // 将参数串前后拼上密钥
        content = secret + content + secret;

        // 计算sign值并添加到参数集合中
        String sign = md5(content);
        tree.put("_sign", sign);

        return tree;
    }

    /**
     * 连接参数串
     *
     * @param cs 参数集
     * @return 参数串
     * @throws IOException
     */
    private static String join(Map<String, String> tree) throws UnsupportedEncodingException {
        StringBuilder buf = new StringBuilder();
        for (Entry<String, String> entry : tree.entrySet()) {
            if (buf.length() > 0) buf.append('&');
            buf.append(entry.getKey());
            buf.append('=');
            buf.append(URLEncoder.encode(entry.getValue(), "UTF-8"));
        }
        return buf.toString();
    }

    /**
     * 生成 MD5
     *
     * @param content需要计算MD5的字符串
     * @return 签名
     * @throws IOException
     */
    private static String md5(String content) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] array = md.digest(content.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : array) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}

```

--------------------------------

### 推送订单至万里牛ERP

Source: https://open.hupun.com/guide/erp-djcj

通过此接口实现将需发货的订单推送到万里牛ERP进行处理，并可推送订单状态变更。

```APIDOC
## POST /erp/b2c/trades/open

### Description
推送订单至万里牛ERP，包括订单信息和状态变更。

### Method
POST

### Endpoint
/erp/b2c/trades/open

### Parameters
#### Request Body
- **data** (string) - Optional - 订单 JSON 串
- **trade_id** (string) - Optional - 订单 ID
- **status** (int) - Optional - 订单状态 (例如: 0:待付款, 1:待发货, 2:已付款, 3:已完成, 4:已关闭)

### Request Example
```json
{
  "trade_id": "T12345",
  "status": 2
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### 推送售后单至万里牛ERP

Source: https://open.hupun.com/guide/erp-djcj

通过此接口将商城的售后单（仅退款、退货类型）推送到万里牛ERP进行处理。

```APIDOC
## POST /erp/b2c/refunds/open

### Description
推送售后单至万里牛ERP进行处理。

### Method
POST

### Endpoint
/erp/b2c/refunds/open

### Parameters
#### Request Body
- **refund_id** (string) - Required - 售后单ID
- **type** (string) - Required - 售后类型 (e.g., "refund", "return")
- **order_id** (string) - Required - 关联的订单ID
- **status** (string) - Required - 售后状态

### Request Example
```json
{
  "refund_id": "RF1001",
  "type": "return",
  "order_id": "T12345",
  "status": "pending"
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### 商品分类推送接口

Source: https://open.hupun.com/guide/erp-djcj

通过此接口实现商城的商品分类与万里牛的商品分类对应。

```APIDOC
## POST /erp/b2c/categories/open

### Description
推送商品分类资料至万里牛ERP。

### Method
POST

### Endpoint
/erp/b2c/categories/open

### Parameters
#### Request Body
- **category_id** (string) - Required - 分类ID
- **category_name** (string) - Required - 分类名称
- **parent_id** (string) - Optional - 父分类ID

### Request Example
```json
{
  "category_id": "CAT001",
  "category_name": "Electronics",
  "parent_id": ""
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### 订单推送与发货同步接口

Source: https://open.hupun.com/guide/erp-zysc

通过下面接口实现推送需发货订单至仓库，订单若申请退款/关闭取消等也以此接口推送订单状态变更。当订单发货后ERP将主动推送发货状态变更，回传快递公司+单号信息。

```APIDOC
## erp/b2c/trades/open

### Description
推送订单至万里牛ERP（如信息更新重推即可）

### Method
POST

### Endpoint
/erp/b2c/trades/open

### Parameters
#### Request Body
- **trade_id** (string) - Required - 订单ID
- **order_list** (array) - Required - 订单详情列表
  - **item_id** (string) - Required - 商品ID
  - **quantity** (integer) - Required - 商品数量
  - **price** (number) - Required - 商品单价

### Request Example
```json
{
  "trade_id": "TRADE789",
  "order_list": [
    {
      "item_id": "SKU123",
      "quantity": 2,
      "price": 99.99
    }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - 调用是否成功
- **message** (string) - 成功或失败信息

#### Response Example
```json
{
  "success": true,
  "message": "订单推送成功"
}
```
```

```APIDOC
## trade_send_msg

### Description
ERP发货通知消息接口

### Method
POST

### Endpoint
/trade_send_msg

### Parameters
#### Request Body
- **data** (string) - Optional - 订单 json 串
- **trade_id** (string) - Optional - 订单ID
- **delivery_code** (string) - Optional - 万里牛ERP承运商编码
- **delivery_name** (string) - Optional - 物流公司名称
- **waybill** (string) - Optional - 物流单号
- **shop_nick** (string) - Optional - 店铺昵称

### Request Example
```json
{
  "trade_id": "TRADE789",
  "delivery_code": "EMS",
  "delivery_name": "EMS快递",
  "waybill": "1234567890",
  "shop_nick": "示例店铺"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - 调用是否成功
- **error_msg** (string) - 错误信息，成功则为 null

#### Response Example
```json
{"success":true}
```

### Error Example
```json
{"code":408,"message":"无效的应用Key"}
```
```

```APIDOC
## erp/b2c/trades/erp/status

### Description
查询ERP订单发货状态

### Method
GET

### Endpoint
/erp/b2c/trades/erp/status

### Parameters
#### Query Parameters
- **trade_id** (string) - Required - 订单ID

### Response
#### Success Response (200)
- **status** (string) - 订单发货状态 (e.g., "pending", "shipped", "delivered")
- **tracking_number** (string) - 物流单号
- **carrier** (string) - 快递公司

#### Response Example
```json
{
  "status": "shipped",
  "tracking_number": "1234567890",
  "carrier": "EMS"
}
```
```

--------------------------------

### 接受ERP推送的库存变更消息

Source: https://open.hupun.com/guide/erp-djcj

万里牛ERP会主动推送实时的库存变更信息（实际库存、可用库存）至此自定义接口。

```APIDOC
## POST 用户自定义接口 (item_quantity_upload_msg)

### Description
接收万里牛ERP推送的库存变更消息。

### Method
POST

### Endpoint
用户自定义接口地址 (需配置给ERP)

### Parameters
#### Request Body
- **data** (string) - Optional - 商品 JSON 串
- **item_id** (string) - Optional - 商品 ID
- **sku_id** (string) - Optional - 商品规格 ID
- **shop_nick** (string) - Optional - 店铺昵称
- **quantity** (int) - Optional - 库存数

### Request Example
```json
{
  "item_id": "ITEM001",
  "sku_id": "SKU123-RED",
  "quantity": 100
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```

**Notes:**
- API must return `{"success":true}` on successful data processing.
- Return error reasons on failure.
- Interface response time should be within 3 seconds, otherwise it's considered a failure.
- Information is pushed in plain text.
- Only HTTP interfaces are supported.
```

--------------------------------

### 商品同步接口

Source: https://open.hupun.com/guide/erp-zysc

通过此接口实现商城的单品、套装商品与万里牛的单品、组合商品的对应，以实现单品与仓库物料对应，套装商品与多个单品的对应。

```APIDOC
## erp/b2c/items/open

### Description
商品资料推送接口

### Method
POST

### Endpoint
/erp/b2c/items/open

### Parameters
#### Request Body
- **item_id** (string) - Required - 商品ID
- **item_name** (string) - Required - 商品名称
- **category_id** (string) - Required - 商品分类ID
- **price** (number) - Required - 商品价格
- **stock** (integer) - Required - 库存数量

### Request Example
```json
{
  "item_id": "SKU123",
  "item_name": "示例商品",
  "category_id": "CAT456",
  "price": 99.99,
  "stock": 100
}
```

### Response
#### Success Response (200)
- **success** (boolean) - 调用是否成功
- **message** (string) - 成功或失败信息

#### Response Example
```json
{
  "success": true,
  "message": "商品资料推送成功"
}
```
```

```APIDOC
## erp/b2c/categories/open

### Description
商品分类推送接口

### Method
POST

### Endpoint
/erp/b2c/categories/open

### Parameters
#### Request Body
- **category_id** (string) - Required - 分类ID
- **category_name** (string) - Required - 分类名称

### Request Example
```json
{
  "category_id": "CAT456",
  "category_name": "示例分类"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - 调用是否成功
- **message** (string) - 成功或失败信息

#### Response Example
```json
{
  "success": true,
  "message": "商品分类推送成功"
}
```
```

--------------------------------

### 退货入库单查询

Source: https://open.hupun.com/guide/erp-djcj

用于查询退货入库单的相关信息。

```APIDOC
## GET /erp/sale/stock/in/query

### Description
查询万里牛ERP中的退货入库单信息。

### Method
GET

### Endpoint
/erp/sale/stock/in/query

### Parameters
#### Query Parameters
- **return_id** (string) - Required - 退货单ID

### Response
#### Success Response (200)
- **stock_in_id** (string) - 入库单ID
- **status** (string) - 入库单状态

#### Response Example
```json
{
  "stock_in_id": "SI1001",
  "status": "completed"
}
```
```

--------------------------------

### 库存同步接口

Source: https://open.hupun.com/guide/erp-zysc

商城库存与仓库库存保持实时变动一致，通过此接口订阅仓库库存变动消息。万里牛ERP主动推送当前实时库存【实际库存数量/可用库存数量】至B2C商城，便于商城调整可销售库存数量。

```APIDOC
## item_quantity_upload_msg

### Description
接受ERP推送的库存变更消息

### Method
POST

### Endpoint
/item_quantity_upload_msg

### Parameters
#### Request Body
- **data** (string) - Optional - 商品 json 串
- **item_id** (string) - Optional - 商品ID
- **sku_id** (string) - Optional - 商品规格ID
- **shop_nick** (string) - Optional - 店铺昵称
- **quantity** (integer) - Optional - 库存数

### Request Example
```json
{
  "item_id": "SKU123",
  "sku_id": "SKU123-RED",
  "quantity": 95
}
```

### Response
#### Success Response (200)
- **success** (boolean) - 调用是否成功
- **error_msg** (string) - 错误信息，成功则为 null

#### Response Example
```json
{"success":true}
```

### Error Example
```json
{"code":408,"message":"无效的应用Key"}
```
```

--------------------------------

### 接受ERP推送的订单发货消息

Source: https://open.hupun.com/guide/erp-djcj

ERP在发货操作后，会主动推送发货信息（包括快递公司和单号）至此自定义接口。

```APIDOC
## POST 用户自定义接口 (trade_send_msg)

### Description
接收万里牛ERP推送的订单发货消息，包含物流信息。

### Method
POST

### Endpoint
用户自定义接口地址 (需配置给ERP)

### Parameters
#### Request Body
- **data** (string) - Optional - 订单 JSON 串
- **trade_id** (string) - Optional - 订单 ID
- **delivery_code** (string) - Optional - 万里牛ERP承运商编码
- **delivery_name** (string) - Optional - 物流公司名称
- **waybill** (string) - Optional - 物流单号
- **shop_nick** (string) - Optional - 店铺昵称

### Request Example
```json
{
  "trade_id": "T12345",
  "delivery_code": "EMS",
  "delivery_name": "EMS快递",
  "waybill": "1234567890",
  "shop_nick": "我的店铺"
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - 调用是否成功
- **error_msg** (String) - 错误信息，成功则为 null

#### Response Example
```json
{
  "success": true
}
```

**Notes:**
- API must return `{"success":true}` on successful data processing.
- Return error reasons on failure.
- Interface response time should be within 3 seconds, otherwise it's considered a failure.
- Information is pushed in plain text.
- Only HTTP interfaces are supported.
```

--------------------------------

### ERP发货通知消息接口示例

Source: https://open.hupun.com/guide/erp-zysc

此接口用于ERP发货后主动推送发货状态变更，回传快递公司和单号信息。确保接口在3秒内返回成功或失败原因，否则视为失败。

```json
{"success":true}
```

```json
{"code":408,"message":"无效的应用Key"}
```

--------------------------------

### Request Specification

Source: https://open.hupun.com/guide/api-spec

All API requests to the Wanli Niu Open Platform must use HTTPS and POST method. The Content-Type header should be set to application/x-www-form-urlencoded, indicating that all requests should send FormData data.

```APIDOC
## Request Specification

All API requests to the Wanli Niu Open Platform use HTTPS and POST method. The `Content-Type` header must be `application/x-www-form-urlencoded`.

### Parameters

Parameters described in the API documentation are FormData items. All parameter values must be converted to `String` type. Collection or object type parameters should be transmitted in JSON string format.

Parameters in FormData include `business parameters` and `system parameters`.

#### System Parameters

All API requests require the following system parameters for developer authentication and data security validation:

| Parameter | Type | Description | Required |
|---|---|---|---|
| `_app` | string | AppKey obtained from the developer console. | Yes |
| `_t` | number | Current timestamp in seconds. Allows a 5-minute deviation between system and server time. | Yes |
| `_s` | string | Authorization code. Pass an empty string if not specifically required. | No |
| `_sign` | string | Signature calculated using AppKey, Secret, Timestamp, and all business parameters. See Signature Algorithm for details. | Yes |
```
Tokens:
Raw