### Order and Item Data Structure Example Source: https://github.com/cunsheng/wangdiantong-api-qjb/blob/main/Firecrawl/sales.RawTrade.pushSelf2.md This snippet shows a typical data structure for representing orders and their associated items. It includes details such as order status, payment information, buyer and receiver details, and item-specific information like product ID, quantity, and price. This structure is commonly used in e-commerce APIs. ```json [ "test", [ { "is_auto_wms": false, "post_amount": 2, "other_amount": 5.2, "discount": 1, "platform_cost": 0, "cod_amount": "", "received": "", "tid": "tid-aqyYHjEldp", "process_status": 10, "trade_status": 30, "refund_status": 0, "pay_status": 2, "order_count": 2, "pay_method": 2, "trade_time": "2020-03-20 18:24:37", "pay_time": "2020-03-20 18:24:37", "end_time": "2020-03-20 18:24:37", "buyer_nick": "test_openapi", "buyer_message": "test_openapi", "buyer_email": "test_openapi@gmail.com", "buyer_area": "test_area", "receiver_name": "receiver_name", "receiver_area": "北京 北京市 朝阳区", "receiver_address": "春天街道春天花园小区1号楼1单元101", "receiver_zip": "014500", "receiver_mobile": "15612340987", "receiver_telno": "02288888888", "invoice_type": 0, "invoice_title": "", "invoice_content": "", "logistics_type": -1, "consign_interval": 0, "delivery_term": 1, "to_deliver_time": "", "pay_id": "", "pay_account": "", "remark": "", "remark_flag": 0, "goods_count": 6, "receivable": 17.6 }, { "tid": "tid-aqyYHjEldp", "oid": "tid-aqyYHjEldp-0", "order_type": 0, "status": 30, "refund_status": 0, "goods_id": "openapi_gid-0", "spec_id": "openapi_sid-0", "goods_no": "api_gno-0", "spec_no": "api_sno-0", "goods_name": "api_gname-0", "spec_name": "api_sname-0", "num": 3, "price": 2.5, "adjust_amount": 2, "refund_amount": "", "discount": 0.5, "share_discount": 0.2, "total_amount": 9, "cid": "", "remark": "", "json": "" }, { "tid": "tid-aqyYHjEldp", "oid": "tid-aqyYHjEldp-1", "order_type": 0, "status": 30, "refund_status": 0, "goods_id": "openapi_gid-1", "spec_id": "openapi_sid-1", "goods_no": "api_gno-1", "spec_no": "api_sno-1", "goods_name": "api_gname-1", "spec_name": "api_sname-1", "num": 3, "price": 2.5, "adjust_amount": 2, "refund_amount": "", "discount": 0.5, "share_discount": 0.2, "total_amount": 9, "share_amount": 8.8, "cid": "", "remark": "", "json": "" } ] ] ``` -------------------------------- ### API Error Response Example Source: https://github.com/cunsheng/wangdiantong-api-qjb/blob/main/Firecrawl/aftersales.refund.RawRefund.upload2.md This JSON structure illustrates an error response from the API. It includes a status code, and the 'error_list' contains details about specific errors encountered during the operation, such as insufficient shop permissions. ```json { "status": 0, "data": { "chg_count": 0, "error_list": [ { "error": "店铺权限不足", "no": "lztest" } ], "new_count": 0 } } ``` -------------------------------- ### API Success Response Example Source: https://github.com/cunsheng/wangdiantong-api-qjb/blob/main/Firecrawl/aftersales.refund.RawRefund.upload2.md This JSON structure represents a successful response from the API call, indicating the status and counts of updated and new refund records. An empty error list signifies that all operations were processed without errors. ```json { "status": 0, "data": { "chg_count": 1, "error_list": [], "new_count": 2 } } ``` -------------------------------- ### Search Products with Pagination using Python Source: https://context7.com/cunsheng/wangdiantong-api-qjb/llms.txt This snippet demonstrates how to search for products using the 'goods.ApiGoods.search' method. It includes setting pagination parameters like page size and page number, sending the request, and processing the response to display product details and total count. It handles successful responses and errors. ```python import requests # Assuming api_url and common_params are defined elsewhere # api_url = "your_api_endpoint" # common_params = {"app_key": "your_app_key", "timestamp": "...", ...} pager = { "page_size": 100, "page_no": 0 # Starts from 0 } # Assuming params is defined elsewhere # params = {"keyword": "example", ...} request_data = { **common_params, "method": "goods.ApiGoods.search", "params": params, "pager": pager, "calc_total": 1 # Calculate total count } try: response = requests.post(api_url, json=request_data, timeout=30) result = response.json() if result.get("status") == 0: goods_list = result["data"]["goods_list"] total_count = result["data"]["total_count"] print(f"Found {total_count} products") for goods in goods_list: print(f"\nProduct: {goods['goods_name']}") print(f" Shop: {goods['shop_name']} ({goods['shop_no']})") print(f" Merchant Code: {goods['merchant_no']}") print(f" Platform ID: {goods['goods_id']}") print(f" Spec ID: {goods['spec_id']}") print(f" Price: {goods['price']}") print(f" Stock: {goods['stock_num']}") print(f" Status: {'On shelf' if goods['status'] == 1 else 'Off shelf'}") print(f" Auto Match: {'Yes' if goods['is_auto_match'] == 1 else 'No'}") print(f" Modified: {goods['modified']}") else: print(f"Error: {result.get('message')}") except Exception as e: print(f"Request failed: {str(e)}") ``` -------------------------------- ### Upload Raw Refund Data using PHP SDK Source: https://github.com/cunsheng/wangdiantong-api-qjb/blob/main/Firecrawl/aftersales.refund.RawRefund.upload2.md This PHP code snippet demonstrates how to upload raw refund data to the WDT ERP system using the provided SDK. It initializes the client, prepares refund order details, and calls the 'aftersales.refund.RawRefund.upload2' method. Ensure the 'wdtsdk.php' is included and client credentials are set correctly. ```php refund_no = 'lztest'; $orderList1->num = 1; $orderList1->tid = 'TID6NAFAmwYMM'; $orderList1->oid = 'deb718e2afe5'; $orderList1->type = 1; $orderList1->status = 2; $orderList1->refund_version = '1'; $orderList1->refund_amount = 1; $orderList1->actual_refund_amount = 1; $orderList1->title = 'test'; $orderList1->logistics_name = ''; $orderList1->logistics_no = ''; $orderList1->buyer_nick = '可用库存'; $orderList1->is_aftersale = 0; $orderList1->reason = ''; array_push($orderList, $orderList1); $data = $client->call("aftersales.refund.RawRefund.upload2", $shopNo, $orderList); ?> ``` -------------------------------- ### Query Platform Goods using Python Requests Source: https://context7.com/cunsheng/wangdiantong-api-qjb/llms.txt Retrieves product information from the ERP system based on time ranges and optional filters like shop number, platform goods ID, or platform specification ID. This function supports incremental updates by specifying `start_time` and `end_time`. ```python import requests # Assume common_params are defined from the signature generation step # The actual API endpoint for querying might differ, refer to specific API docs # This example demonstrates the query parameters structure. params = { "start_time": "2025-01-01 00:00:00", "end_time": "2025-01-31 23:59:59", "shop_no": "SHOP001" # Optional: filter by shop # "goods_id": "63832855", # Optional: filter by platform goods ID # "spec_id": "123949335" # Optional: filter by platform spec ID } # To make a real request, you would combine common_params with these query parameters # and send a GET or POST request to the appropriate API endpoint. # Example (assuming GET request): # api_url = "https://api.wangdian.cn/openapi/query" # request_data = {**common_params, **params} # response = requests.get(api_url, params=request_data, timeout=30) # result = response.json() ``` -------------------------------- ### wms.StockSpec.search Source: https://github.com/cunsheng/wangdiantong-api-qjb/blob/main/Firecrawl/wms.StockSpec.search.md Retrieves ERP item (SKU) inventory quantities. This endpoint is deprecated and users are advised to use wms.StockSpec.search2. ```APIDOC ## GET /qjb/open/apidoc/doc?path=wms.StockSpec.search ### Description This endpoint retrieves the inventory quantity for ERP items (SKUs). It supports filtering by time, item codes, and warehouses. Please note that this API is deprecated and wms.StockSpec.search2 should be used instead. ### Method GET ### Endpoint /qjb/open/apidoc/doc?path=wms.StockSpec.search ### Parameters #### Query Parameters - **sid** (String) - Required - Seller account, assigned by Wangdian Tong. - **key** (String) - Required - API account key assigned by Wangdian Tong. - **salt** (String) - Required - Salt assigned by Wangdian Tong, used in conjunction with the secret for signing. - **method** (String) - Required - The name of the API being called (wms.StockSpec.search). - **v** (String) - Required - API version number (defaults to 1.0). - **timestamp** (Integer) - Required - Seconds-level timestamp. Current timestamp minus 1325347200 (2012-01-01 00:00:00). Must be within 120 seconds of the server time. - **sign** (String) - Required - Signature generated using provided parameters and app secret. - **page_size** (Integer) - Optional - Number of items per page for pagination. Required for paginated queries. - **page_no** (Integer) - Optional - Page number for pagination. Standard interfaces start from 0. Required for paginated queries. - **calc_total** (Integer) - Optional - Whether to calculate the total number of query results. Set to 1 to calculate, 0 otherwise. Not required. #### Request Body - **params** (Map) - Required - Query parameters. - **start_time** (String) - Optional - Start time for last modified time. Can be empty if a seller code is provided. - **end_time** (String) - Optional - End time for last modified time. Can be empty if a seller code is provided. - **spec_nos** (List) - Optional - List of seller codes (SKU codes). - **warehouse_no** (String) - Optional - Warehouse code. - **mask** (Integer) - Optional - Controls returned data: 1 for sales statistics, 2 for cost price data, 3 for both. Defaults to 0 (no extra data). - **need_alarm_info** (Integer) - Optional - Whether to include alarm-related information: 0 for no, 1 for yes. Use with caution as it can impact performance. Defaults to 0. - **pager** (Pager) - Required - Pagination object. - **page_size** (Integer) - Optional - Page size (maximum 1000). - **page_no** (Integer) - Optional - Page number (starts from 0). ### Request Example ```json { "sid": "your_seller_id", "key": "your_app_key", "salt": "your_app_secret_salt", "method": "wms.StockSpec.search", "v": "1.0", "timestamp": 1678886400, "sign": "generated_signature", "params": { "spec_nos": ["SKU001", "SKU002"], "warehouse_no": "WH001", "mask": 1 }, "pager": { "page_size": 100, "page_no": 0 } } ``` ### Response #### Success Response (200) - **status** (Integer) - Return code: 0 for success. - **total** (Integer) - Total number of records found (optional, depends on `calc_total`). - **message** (String) - Error message if any (optional). - **data** (List>) - List of inventory data objects. - **rec_id** (Integer) - Unique key for the detail. - **defect** (Integer) - 0 for normal goods, 1 for defective goods. - **stock_num** (Decimal) - Inventory quantity. - **wms_sync_stock** (Decimal) - Inventory quantity synced from external WMS. - **wms_stock_diff** (Decimal) - Difference between external WMS inventory and system inventory. - **spec_no** (String) - Seller code (SKU code). - **spec_id** (Integer) - Unique key for the item. - **goods_no** (String) - Item code. - **goods_name** (String) - Item name. - **spec_code** (String) - Specification code. - **brand_name** (String) - Brand name. - **spec_name** (String) - Specification name. - **barcode** (String) - Barcode. - **unpay_num** (Decimal) - Unpaid quantity. - **subscribe_num** (Decimal) - Pre-order quantity. - **order_num** (Decimal) - Quantity pending approval. - **sending_num** (Decimal) - Quantity ready for shipment. - **purchase_num** (Decimal) - Quantity in transit for purchase. - **transfer_num** (Decimal) - Quantity in transit for transfer. - **to_purchase_num** (Decimal) - Quantity needed for purchase. - **purchase_arrive_num** (Decimal) - Quantity arrived from purchase. - **wms_preempty_stock** (Decimal) - Occupied inventory quantity synced from external WMS. - **weight** (Decimal) - Weight. - **img_url** (String) - Image URL. - **warehouse_no** (String) - Warehouse code. - **warehouse_id** (Integer) - Warehouse ID, unique key for the warehouse. - **warehouse_name** (String) - Warehouse name. - **warehouse_type** (Integer) - Warehouse type: 0 for normal, non-zero for external WMS. - **available_send_stock** (Decimal) - Available quantity for shipment. - **created** (String) - Creation time. - **modified** (String) - Modification time. - **part_paid_num** (Decimal) - Partially paid quantity. - **refund_exch_num** (Decimal) - Quantity in transit for sales exchange (seller to buyer). - **refund_num** (Decimal) - Returned quantity from sales. - **refund_onway_num** (Decimal) - Quantity in transit for sales returns (buyer to seller). - **return_exch_num** (Decimal) - Quantity for purchase exchange. - **return_num** (Decimal) - Returned quantity from purchase. - **return_onway_num** (Decimal) - Quantity in transit for purchase returns. - **to_transfer_num** (Decimal) - Quantity needed for transfer. #### Response Example ```json { "status": 0, "total": 2, "data": [ { "rec_id": 12345, "defect": 0, "stock_num": 100.5000, "wms_sync_stock": 100.0000, "wms_stock_diff": 0.5000, "spec_no": "SKU001", "spec_id": 54321, "goods_no": "ITEM001", "goods_name": "Example Product 1", "spec_code": "SPEC001", "brand_name": "Brand A", "spec_name": "Large", "barcode": "123456789012", "unpay_num": 10.0000, "subscribe_num": 5.0000, "order_num": 0.0000, "sending_num": 20.0000, "purchase_num": 0.0000, "transfer_num": 0.0000, "to_purchase_num": 0.0000, "purchase_arrive_num": 0.0000, "wms_preempty_stock": 0.0000, "weight": 0.5000, "img_url": "http://example.com/img/sku001.jpg", "warehouse_no": "WH001", "warehouse_id": 101, "warehouse_name": "Main Warehouse", "warehouse_type": 0, "available_send_stock": 70.5000, "created": "2023-03-15 10:00:00", "modified": "2023-03-15 12:30:00", "part_paid_num": 0.0000, "refund_exch_num": 0.0000, "refund_num": 0.0000, "refund_onway_num": 0.0000, "return_exch_num": 0.0000, "return_num": 0.0000, "return_onway_num": 0.0000, "to_transfer_num": 0.0000 } ] } ``` ``` -------------------------------- ### Push Goods to ERP using Python Requests Source: https://context7.com/cunsheng/wangdiantong-api-qjb/llms.txt Pushes or updates product information to the ERP system using the `requests` library. It requires common authentication parameters and detailed goods and specification information. The API endpoint is `https://api.wangdian.cn/openapi`. This function handles both creating new products and updating existing ones based on `goods_no` and `spec_no`. ```python import requests import json # Assume common_params are defined from the signature generation step api_url = "https://api.wangdian.cn/openapi" goods_info = { "goods_no": "PROD-2025-001", "goods_name": "Premium Wireless Headphones", "short_name": "WL Headphones", "class_name": "Electronics", "brand_name": "TechBrand", "unit_name": "piece", "aux_unit_name": "box", "goods_type": 1, # 1: Sales product "auto_create_bc": True, # Auto-create brand and category "alias": "WL-HP-001", "origin": "Shenzhen, China", "remark": "High-quality wireless headphones with noise cancellation", "prop1": "Consumer Electronics", "prop2": "Audio", "flag_name": "Hot Sale" } spec_info_list = [ { "spec_no": "PROD-2025-001-BLK", "spec_name": "Black Color", "spec_code": "BLK-001", "barcode": "6901234567890", "retail_price": 299.00, "market_price": 399.00, "wholesale_price": 250.00, "lowest_price": 200.00, "weight": 0.35, "goods_label": "Premium,Bestseller", "sn_type": 0, # 0: No serial number, 1: Strong SN, 2: Weak SN "img_url": "https://example.com/images/headphones-black.jpg", "remark": "Black color variant", "unit_name": "piece", "large_type": 0 # 0: Regular item }, { "spec_no": "PROD-2025-001-WHT", "spec_name": "White Color", "spec_code": "WHT-001", "barcode": "6901234567891", "retail_price": 299.00, "market_price": 399.00, "wholesale_price": 250.00, "lowest_price": 200.00, "weight": 0.35, "goods_label": "Premium", "sn_type": 0, "img_url": "https://example.com/images/headphones-white.jpg", "remark": "White color variant", "unit_name": "piece", "large_type": 0 } ] request_data = { **common_params, # includes sid, key, salt, method, v, timestamp, sign "goodsInfo": goods_info, "specInfoList": spec_info_list } try: response = requests.post(api_url, json=request_data, timeout=30) result = response.json() if result.get("status") == 0: print(f"Success! Goods ID: {result.get('data')}") # Expected output: {"status": 0, "data": 54645} else: print(f"Error: {result.get('message')}") # Error example: {"status": 100, "message": "商家编码已存在"} except Exception as e: print(f"Request failed: {str(e)}") ``` -------------------------------- ### Generate MD5 Signature for API Authentication Source: https://context7.com/cunsheng/wangdiantong-api-qjb/llms.txt Generates an MD5 signature for API authentication by concatenating secret, sid, key, timestamp, and salt. This signature is a required part of the common request parameters for most API calls. ```python import hashlib # Assume sid, key, timestamp, salt, and secret are defined elsewhere sign_string = f"{secret}{sid}{key}{timestamp}{salt}" sign = hashlib.md5(sign_string.encode()).hexdigest() ``` -------------------------------- ### Goods Management API Source: https://context7.com/cunsheng/wangdiantong-api-qjb/llms.txt APIs for managing product information within the ERP system. ```APIDOC ## POST /openapi ### Description This endpoint is used to push product information to the ERP system. It can create new products or update existing ones based on `goods_no` and `spec_no`. ### Method POST ### Endpoint https://api.wangdian.cn/openapi ### Parameters #### Query Parameters (Authentication parameters are required for all requests and should be included in the request body as JSON) - **sid** (string) - Required - The user's store ID. - **key** (string) - Required - The API key. - **salt** (string) - Required - A salt value for signature generation. - **method** (string) - Required - The API method to call, e.g., "goods.Goods.push". - **v** (string) - Required - The API version, e.g., "1.0". - **timestamp** (string) - Required - The Unix timestamp of the request. - **sign** (string) - Required - The MD5 hash signature of the request. #### Request Body - **goodsInfo** (object) - Required - Information about the product. - **goods_no** (string) - Required - Unique identifier for the goods. - **goods_name** (string) - Required - The name of the goods. - **short_name** (string) - Optional - A shorter name for the goods. - **class_name** (string) - Optional - The category name of the goods. - **brand_name** (string) - Optional - The brand name of the goods. - **unit_name** (string) - Optional - The unit of measurement for the goods. - **aux_unit_name** (string) - Optional - An auxiliary unit of measurement. - **goods_type** (integer) - Optional - The type of goods (e.g., 1 for Sales product). - **auto_create_bc** (boolean) - Optional - Whether to auto-create brand and category. - **alias** (string) - Optional - An alias for the goods. - **origin** (string) - Optional - The origin of the goods. - **remark** (string) - Optional - Remarks about the goods. - **prop1** (string) - Optional - Custom property 1. - **prop2** (string) - Optional - Custom property 2. - **flag_name** (string) - Optional - A flag name for the goods. - **specInfoList** (array) - Required - A list of specification information for the product. - Each item in the array is an object with the following fields: - **spec_no** (string) - Required - Unique identifier for the specification. - **spec_name** (string) - Required - The name of the specification. - **spec_code** (string) - Optional - A code for the specification. - **barcode** (string) - Optional - The barcode of the specification. - **retail_price** (float) - Optional - The retail price. - **market_price** (float) - Optional - The market price. - **wholesale_price** (float) - Optional - The wholesale price. - **lowest_price** (float) - Optional - The lowest allowed price. - **weight** (float) - Optional - The weight of the specification. - **goods_label** (string) - Optional - Labels for the goods specification. - **sn_type** (integer) - Optional - Serial number type (0: No SN, 1: Strong SN, 2: Weak SN). - **img_url** (string) - Optional - URL of the image for the specification. - **remark** (string) - Optional - Remarks about the specification. - **unit_name** (string) - Optional - The unit of measurement for the specification. - **large_type** (integer) - Optional - Type of item (e.g., 0 for Regular item). ### Request Example ```json { "sid": "YOUR_SID", "key": "YOUR_KEY", "salt": "YOUR_SALT", "method": "goods.Goods.push", "v": "1.0", "timestamp": "1678886400", "sign": "generated_md5_hash", "goodsInfo": { "goods_no": "PROD-2025-001", "goods_name": "Premium Wireless Headphones", "short_name": "WL Headphones", "class_name": "Electronics", "brand_name": "TechBrand", "unit_name": "piece", "aux_unit_name": "box", "goods_type": 1, "auto_create_bc": true, "alias": "WL-HP-001", "origin": "Shenzhen, China", "remark": "High-quality wireless headphones with noise cancellation", "prop1": "Consumer Electronics", "prop2": "Audio", "flag_name": "Hot Sale" }, "specInfoList": [ { "spec_no": "PROD-2025-001-BLK", "spec_name": "Black Color", "spec_code": "BLK-001", "barcode": "6901234567890", "retail_price": 299.00, "market_price": 399.00, "wholesale_price": 250.00, "lowest_price": 200.00, "weight": 0.35, "goods_label": "Premium,Bestseller", "sn_type": 0, "img_url": "https://example.com/images/headphones-black.jpg", "remark": "Black color variant", "unit_name": "piece", "large_type": 0 }, { "spec_no": "PROD-2025-001-WHT", "spec_name": "White Color", "spec_code": "WHT-001", "barcode": "6901234567891", "retail_price": 299.00, "market_price": 399.00, "wholesale_price": 250.00, "lowest_price": 200.00, "weight": 0.35, "goods_label": "Premium", "sn_type": 0, "img_url": "https://example.com/images/headphones-white.jpg", "remark": "White color variant", "unit_name": "piece", "large_type": 0 } ] } ``` ### Response #### Success Response (200) - **status** (integer) - 0 indicates success. - **data** (integer) - The ID of the created or updated goods. #### Response Example ```json { "status": 0, "data": 54645 } ``` #### Error Response - **status** (integer) - Non-zero indicates an error. - **message** (string) - Error message describing the issue. #### Error Example ```json { "status": 100, "message": "商家编码已存在" } ``` --- ## GET /openapi ### Description Retrieves platform product information from the ERP system. It supports filtering by time range and optional filtering by shop, goods ID, or spec ID for incremental updates. ### Method GET ### Endpoint https://api.wangdian.cn/openapi ### Parameters #### Query Parameters (Authentication parameters are required for all requests and should be included in the request body as JSON) - **sid** (string) - Required - The user's store ID. - **key** (string) - Required - The API key. - **salt** (string) - Required - A salt value for signature generation. - **method** (string) - Required - The API method to call, e.g., "goods.Goods.query". - **v** (string) - Required - The API version, e.g., "1.0". - **timestamp** (string) - Required - The Unix timestamp of the request. - **sign** (string) - Required - The MD5 hash signature of the request. - **start_time** (string) - Required - The start of the time range for querying (YYYY-MM-DD HH:MM:SS). - **end_time** (string) - Required - The end of the time range for querying (YYYY-MM-DD HH:MM:SS). - **shop_no** (string) - Optional - Filter results by shop number. - **goods_id** (string) - Optional - Filter results by platform goods ID. - **spec_id** (string) - Optional - Filter results by platform specification ID. ### Request Example ```http GET https://api.wangdian.cn/openapi?sid=YOUR_SID&key=YOUR_KEY&salt=YOUR_SALT&method=goods.Goods.query&v=1.0×tamp=1678886400&sign=generated_md5_hash&start_time=2025-01-01%2000:00:00&end_time=2025-01-31%2023:59:59&shop_no=SHOP001 ``` ### Response (The exact structure of the response for query operations depends on the specific method. Please refer to the detailed API documentation for the `goods.Goods.query` method for the precise response schema.) #### Success Response (200) - **status** (integer) - 0 indicates success. - **data** (object/array) - Contains the requested goods information. #### Response Example ```json { "status": 0, "data": [ { "goods_id": "63832855", "goods_no": "PROD-2025-001", "spec_id": "123949335", "spec_no": "PROD-2025-001-BLK", "update_time": "2025-01-15 10:30:00", "goods_name": "Premium Wireless Headphones", "spec_name": "Black Color", "price": 299.00 // ... other fields } // ... more items ] } ``` #### Error Response - **status** (integer) - Non-zero indicates an error. - **message** (string) - Error message describing the issue. #### Error Example ```json { "status": 101, "message": "Invalid time range" } ``` ``` -------------------------------- ### Wangdiantong API Client Class Source: https://context7.com/cunsheng/wangdiantong-api-qjb/llms.txt This section details the WangdiantongAPIClient class, which provides methods for interacting with the Wangdiantong API, including authentication and request handling. ```APIDOC ## Wangdiantong API Client ### Description The `WangdiantongAPIClient` class facilitates communication with the Wangdiantong API. It handles authentication, request construction, and response processing, incorporating automatic retries and detailed error handling for various failure scenarios. ### Initialization ```python WangdiantantAPIClient(api_url, sid, key, secret, salt) ``` - **api_url** (string) - The base URL of the Wangdiantong API. - **sid** (string) - Your account's Service ID. - **key** (string) - Your API Key. - **secret** (string) - Your API Secret. - **salt** (string) - Your API Salt. ### Methods #### `_generate_auth_params(self, method)` - **Description**: Generates the necessary authentication parameters for an API request, including timestamp and signature. - **Method**: Internal helper method. - **Parameters**: - **method** (string) - The API method being called (e.g., "goods.Goods.push"). #### `call_api(self, method, params, max_retries=3)` - **Description**: Makes a POST request to the Wangdiantong API with the specified method and parameters. It includes automatic retry logic for server errors and connection issues, along with specific handling for business logic, authentication, and permission errors. - **Method**: `POST` - **Endpoint**: The `api_url` provided during initialization. #### Parameters ##### Request Body (for `call_api`) - **sid** (string) - Required - Your account's Service ID. - **key** (string) - Required - Your API Key. - **salt** (string) - Required - Your API Salt. - **method** (string) - Required - The API method to call. - **v** (string) - Required - API version, defaults to "1.0". - **timestamp** (integer) - Required - Unix timestamp adjusted by a base value. - **sign** (string) - Required - The generated MD5 signature for authentication. - **[Business Parameters]** - Required - The specific parameters for the API method being called (e.g., `goodsInfo`, `specInfoList` for `goods.Goods.push`). ### Request Example (for `call_api`) ```json { "sid": "your_sid", "key": "your_key", "salt": "your_salt", "method": "goods.Goods.push", "v": "1.0", "timestamp": 1678886400, "sign": "generated_signature", "goodsInfo": { ... }, "specInfoList": [ ... ] } ``` ### Response #### Success Response (200) - **status** (integer) - 0 if successful. - **message** (string) - "Success" or a relevant message. - **data** (object/array) - The actual data returned by the API call. #### Error Responses - **status** (integer) - Non-zero indicates an error. - `100`: Business logic error. - `401`: Authentication failed. - `403`: Permission denied. - `500`: Server error. - **message** (string) - A description of the error. ### Response Example (Success) ```json { "status": 0, "message": "Success", "data": { "goodsId": "123456789" } } ``` ### Response Example (Business Error) ```json { "status": 100, "message": "Invalid goods information provided." } ``` ### Common Error Scenarios and Handling - **Authentication Errors (status 401)**: Ensure your `sid`, `key`, `secret`, and `salt` are correctly configured. - **Permission Errors (status 403)**: Verify that your API key has the necessary permissions to perform the requested operation. - **Business Logic Errors (status 100)**: Check the `message` field for details on what specific business rule was violated and adjust your request parameters accordingly. - **Server Errors (status 500)**: The client will automatically retry these requests with exponential backoff. If persistent, contact API support. - **Timeouts and Connection Errors**: The client will retry these requests. Ensure your network connection is stable. - **Invalid JSON Response**: Indicates a problem with the API's response format. Log the raw response if possible and report to API support. ```