### 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 parameters = new HashMap<>(); parameters.put("param1", "value1"); parameters.put("param2", "value2"); // AppKey 和 Secret String appKey = "yourAppKey"; String secret = "yourSecret"; // 获取签名后的参数集合 Map signedParameters = signParameters(parameters, appKey, secret); // 打印签名后的参数集合 for (Entry 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 signParameters(Map parameters, String appKey, String secret) throws UnsupportedEncodingException { // 利用TreeMap对参数按key进行排序 Map 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 tree) throws UnsupportedEncodingException { StringBuilder buf = new StringBuilder(); for (Entry 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 | ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.