1688包装信息API接口完全指南

{
  "productinfo": {
    "shippingInfo": {
      "freightTemplateID": 11754104,    // 运费模板ID
      "unitWeight": 1.5,                 // 单位重量（千克）
      "packageSize": "10x20x50",          // 包装尺寸（长x宽x高，厘米）
      "volume": 10000,                     // 体积（立方厘米）
      "sendGoodsAddress": {              // 发货地址
        "province": "浙江",
        "city": "杭州"
      }
    },
    "saleInfo": {
      "amountOnSale": 200.0,             // 可售数量
      "minOrderQuantity": 3,             // 最小起订量
      "unit": "件",                       // 计量单位
      "priceRanges": [                   // 阶梯价格
        {"startQuantity": 3, "price": 8.0}
      ]
    }
  }}

import requests

url = "https://www.aliprice.com/items/itemDetail"headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"}data = {
    "offerId": "1234567890",  # 1688商品ID
    "includePackaging": True   # 显式请求包装信息}response = requests.post(url, headers=headers, json=data)result = response.json()# 包装信息结构packaging = result.get("packaging", {})print(f"净重: {packaging.get('weight')}kg")print(f"毛重: {packaging.get('grossWeight')}kg")print(f"包装方式: {packaging.get('packing')}")  # 如"独立包装"、"彩盒"print(f"包装尺寸: {packaging.get('packingSize')}")  # 如"10*20*5cm"print(f"装箱规格: {packaging.get('cartonQty')}件/箱")print(f"外箱尺寸: {packaging.get('cartonSize')}")  # 如"50*40*30cm"

import requestsimport timeimport jsonimport hashlibimport urllib.parsefrom typing import Dict, Optional, Listimport logging

logging.basicConfig(level=logging.INFO)logger = logging.getLogger(__name__)class Alibaba1688API:
    """
    1688商品包装信息获取客户端
    支持官方API和第三方聚合API
    """
    
    def __init__(self, 
                 app_key: Optional[str] = None,
                 app_secret: Optional[str] = None,
                 third_party_key: Optional[str] = None,
                 use_official: bool = False):
        """
        初始化
        :param app_key: 1688开放平台App Key（官方API）
        :param app_secret: 1688开放平台App Secret（官方API）
        :param third_party_key: 第三方API密钥（推荐）
        :param use_official: 是否使用官方API（默认False，使用第三方）
        """
        self.app_key = app_key
        self.app_secret = app_secret
        self.third_party_key = third_party_key
        self.use_official = use_official        
        # API端点配置
        if use_official:
            self.api_url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get"
        else:
            # 默认使用第三方聚合API（示例：AliPrice）
            self.api_url = "https://www.aliprice.com/items/itemDetail"
            # 备选：其他第三方API
            self.backup_urls = {
                "vv_tool": "http://api.vv-tool.com/tool/erps/product1688get",
                "o0b_cn": "https://o0b.cn/ibrad/1688/item_get/"
            }
    
    def _generate_official_sign(self, params: dict) -> str:
        """生成1688官方API签名（MD5）"""
        sorted_params = sorted(
            [(k, v) for k, v in params.items() if v is not None],
            key=lambda x: x[0]
        )
        
        sign_str = self.app_secret        for key, value in sorted_params:
            encoded_value = urllib.parse.quote(str(value), safe='')
            sign_str += f"{key}{encoded_value}"
        sign_str += self.app_secret        
        return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
    
    def get_packaging_info_official(self, product_id: str) -> Dict:
        """
        通过官方API获取包装信息（字段较分散）
        """
        timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
        
        params = {
            "app_key": self.app_key,
            "method": "com.alibaba.product.alibaba.product.get",
            "timestamp": timestamp,
            "v": "2.0",
            "format": "json",
            "sign_method": "md5",
            "productId": product_id,
            "fields": "productID,subject,shippingInfo,saleInfo,attributes"
        }
        
        params["sign"] = self._generate_official_sign(params)
        
        try:
            response = requests.post(self.api_url, data=params, timeout=30)
            response.raise_for_status()
            data = response.json()
            
            # 解析包装信息（官方API字段分散）
            product_info = data.get("productinfo", {})
            shipping = product_info.get("shippingInfo", {})
            attributes = product_info.get("attributes", [])
            
            # 从attributes中查找包装相关属性
            packaging_attr = {}
            for attr in attributes:
                attr_name = attr.get("attributeName", "")
                if any(keyword in attr_name for keyword in ["包装", "重量", "体积", "尺寸"]):
                    packaging_attr[attr_name] = attr.get("value")
            
            return {
                "success": True,
                "source": "official",
                "product_id": product_id,
                "basic_weight": shipping.get("unitWeight"),  # 单位重量
                "package_size": shipping.get("packageSize"),  # 尺寸（长x宽x高）
                "volume": shipping.get("volume"),  # 体积（立方厘米）
                "freight_template_id": shipping.get("freightTemplateID"),
                "packaging_attributes": packaging_attr,  # 其他包装属性
                "raw_data": data  # 原始完整数据
            }
            
        except Exception as e:
            logger.error(f"官方API调用失败: {e}")
            return {"success": False, "error": str(e)}
    
    def get_packaging_info_third_party(self, product_id: str, provider: str = "aliprice") -> Dict:
        """
        通过第三方API获取完整包装信息（推荐）
        """
        try:
            if provider == "aliprice":
                # AliPrice API
                headers = {
                    "Authorization": f"Bearer {self.third_party_key}",
                    "Content-Type": "application/json"
                }
                payload = {
                    "offerId": product_id,
                    "includePackaging": True,
                    "includeSku": True
                }
                response = requests.post(self.api_url, headers=headers, json=payload, timeout=30)
                
            elif provider == "vv_tool":
                # VV-Tool API
                headers = {"Authorization": f"Bearer {self.third_party_key}"}
                params = {"productId": product_id}
                response = requests.get(self.backup_urls["vv_tool"], headers=headers, params=params, timeout=30)
                
            else:
                # 通用第三方API（o0b.cn等）
                url = f"{self.backup_urls['o0b_cn']}?key={self.third_party_key}&num_iid={product_id}"
                response = requests.get(url, timeout=30)
            
            response.raise_for_status()
            data = response.json()
            
            # 标准化包装信息字段（不同第三方API结构略有差异）
            item = data.get("item", data)  # 适配不同响应结构
            
            packaging = {
                "success": True,
                "source": f"third_party_{provider}",
                "product_id": product_id,
                "title": item.get("title"),
                
                # 核心包装字段（第三方API通常更完整）
                "net_weight": self._extract_weight(item.get("weight") or item.get("unitWeight")),
                "gross_weight": self._extract_weight(item.get("grossWeight")),
                "weight_unit": "kg",  # 通常为千克
                
                "packing_type": item.get("packing") or item.get("packagingType"),  # 独立包装/彩盒/纸箱
                "unit_package_size": item.get("packingSize") or item.get("packageSize"),  # 单品包装尺寸
                
                "carton_dimensions": item.get("cartonSize"),  # 外箱尺寸
                "quantity_per_carton": item.get("cartonQty"),  # 装箱数量
                
                "volume": item.get("volume"),  # 体积（立方厘米）
                "shipping_weight": item.get("shippingWeight"),  # 发货重量
                
                # 扩展属性
                "material": item.get("material"),  # 材质
                "spec_params": item.get("specParams", []),  # 规格参数列表
                
                "raw_data": data            }
            
            # 计算物流常用指标
            if packaging["carton_dimensions"] and packaging["quantity_per_carton"]:
                packaging["logistics_recommendation"] = self._analyze_logistics(packaging)
            
            return packaging            
        except Exception as e:
            logger.error(f"第三方API调用失败: {e}")
            return {"success": False, "error": str(e)}
    
    def _extract_weight(self, weight_val) -> Optional[float]:
        """提取数值型重量"""
        if not weight_val:
            return None
        if isinstance(weight_val, (int, float)):
            return float(weight_val)
        # 处理字符串如 "0.8kg"、"1.2KG"
        import re        match = re.search(r'(\d+\.?\d*)', str(weight_val))
        return float(match.group(1)) if match else None
    
    def _analyze_logistics(self, packaging: Dict) -> Dict:
        """基于包装信息分析物流建议"""
        try:
            # 解析外箱尺寸（格式：50*40*30cm）
            carton_size = packaging["carton_dimensions"]
            if not carton_size:
                return {}
            
            dims = [float(x) for x in carton_size.replace('cm', '').split('*')]
            if len(dims) != 3:
                return {}
            
            length, width, height = dims
            volume_weight = (length * width * height) / 5000  # 体积重（快递标准）
            actual_weight = packaging.get("gross_weight", 0)
            
            # 判断计费重量
            chargeable_weight = max(volume_weight, actual_weight)
            
            return {
                "volume_weight_kg": round(volume_weight, 2),
                "actual_weight_kg": actual_weight,
                "chargeable_weight_kg": round(chargeable_weight, 2),
                "dimensional_factor": "1:5000",  # 体积重系数
                "suitable_for": "express" if chargeable_weight < 20 else "freight",
                "stackable": height < 60  # 是否适合堆叠
            }
        except:
            return {}
    
    def get_packaging(self, product_id: str, prefer_third_party: bool = True) -> Dict:
        """
        统一入口：获取包装信息
        """
        if prefer_third_party and self.third_party_key:
            # 优先使用第三方API（数据更完整）
            result = self.get_packaging_info_third_party(product_id)
            if result.get("success"):
                return result        
        # 回退到官方API
        if self.app_key and self.app_secret:
            return self.get_packaging_info_official(product_id)
        
        return {"success": False, "error": "无可用API配置"}# ==================== 使用示例 ====================if __name__ == "__main__":
    # 方式1：使用第三方API（推荐，数据完整）
    api = Alibaba1688API(third_party_key="your_third_party_key")
    
    # 方式2：使用官方API（需企业资质）
    # api = Alibaba1688API(
    #     app_key="your_app_key",
    #     app_secret="your_app_secret",
    #     use_official=True
    # )
    
    # 获取商品包装信息
    result = api.get_packaging("1234567890")
    
    if result["success"]:
        print("✅ 包装信息获取成功")
        print(f"商品标题: {result.get('title')}")
        print(f"净重: {result.get('net_weight')}kg")
        print(f"毛重: {result.get('gross_weight')}kg")
        print(f"包装方式: {result.get('packing_type')}")
        print(f"单品尺寸: {result.get('unit_package_size')}")
        print(f"外箱尺寸: {result.get('carton_dimensions')}")
        print(f"装箱数: {result.get('quantity_per_carton')}件/箱")
        
        # 物流分析
        logistics = result.get('logistics_recommendation', {})
        if logistics:
            print(f"\n📦 物流建议:")
            print(f"  计费重量: {logistics.get('chargeable_weight_kg')}kg")
            print(f"  适合运输方式: {'快递' if logistics.get('suitable_for') == 'express' else '货运'}")
    else:
        print(f"❌ 获取失败: {result.get('error')}")

# 物流计费重量计算（快递行业标准：体积重 = 长*宽*高 / 5000）def calculate_chargeable_weight(length, width, height, actual_weight):
    """
    计算计费重量（实际重量 vs 体积重，取较大者）
    :param length: 长（cm）
    :param width: 宽（cm）  
    :param height: 高（cm）
    :param actual_weight: 实际重量（kg）
    """
    volume_weight = (length * width * height) / 5000
    return max(volume_weight, actual_weight)# 集装箱装载估算def estimate_container_load(carton_length, carton_width, carton_height, carton_qty):
    """
    估算20GP集装箱可装载数量（标准20GP内径：589cm x 235cm x 239cm）
    """
    container_dims = (589, 235, 239)
    carton_dims = (carton_length, carton_width, carton_height)
    
    # 简单估算（不考虑实际堆叠间隙）
    max_qty = 1
    for c_dim, box_dim in zip(container_dims, sorted(carton_dims)):
        max_qty *= int(c_dim // box_dim)
    
    return max_qty * carton_qty  # 总件数