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

一、接口体系概览1688阿里巴巴中国站的包装信息主要通过商品详情类API获取而非独立接口。包装数据分散在以下字段中接口类型核心接口包装相关字段数据覆盖度官方开放平台alibaba.product.getshippingInfo、saleInfo中的物流信息基础重量、尺寸第三方聚合API1688.item_getweight、packing、packingSize、grossWeight等完整包装规格ERP工具类product1688editunitWeight、packageSize、volume编辑/读取双向关键发现官方API对包装信息的返回较为分散而第三方API如AliPrice、VV-Tool等通常已整合完整的包装字段更适合直接获取结构化包装数据。二、官方开放平台alibaba.product.get1. 接入准备2. 核心请求参数参数名类型必选说明示例值app_keyString是应用唯一标识12345678methodString是接口方法名com.alibaba.product.alibaba.product.gettimestampString是时间戳yyyy-MM-dd HH:mm:ss2026-04-07 16:42:00vString是API版本2.0formatString是响应格式jsonsignString是MD5签名E4F2G3H4...productIdLong是1688商品ID619899292404fieldsString否指定返回字段shippingInfo,saleInfo3. 包装信息相关返回字段根据官方文档包装信息主要分布在以下结构中{ 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} ] } } }注意官方API的包装字段较为基础详细的包装方式如独立包装、彩盒、纸箱等通常需要在attributes或description中解析。三、第三方聚合API推荐方案由于官方API对包装信息的限制实际开发中更推荐使用第三方聚合API它们整合了完整的包装规格数据。1. AliPrice API方案AliPrice提供专门的1688商品详情接口包含结构化包装信息接口地址包装字段商品详情https://www.aliprice.com/items/itemDetailweight、packing、packingSize、grossWeight请求示例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, headersheaders, jsondata) 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*30cm2. 通用第三方API字段映射不同第三方API的包装字段命名可能不同以下是常见映射关系通用含义AliPriceVV-Tool其他常见命名商品净重weightunitWeightitem_weight、netWeight商品毛重grossWeight-gross_weight、totalWeight包装方式packing-packagingType、packageStyle单品包装尺寸packingSizepackageSizeitem_size、unitSize体积-volumecubicVolume、item_volume外箱尺寸cartonSize-outerCartonSize、boxSize装箱数量cartonQty-quantityPerCarton、packingQuantity跨境包裹重量-offerSuttleWeightcrossBorderWeight跨境包裹尺寸-offerLength/Width/HeightcbmDimensions四、完整实战代码Python以下是一个生产级的1688包装信息获取类支持官方API和第三方API双通道import requests import time import json import hashlib import urllib.parse from typing import Dict, Optional, List import logging logging.basicConfig(levellogging.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], keylambda 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, dataparams, timeout30) 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: fBearer {self.third_party_key}, Content-Type: application/json } payload { offerId: product_id, includePackaging: True, includeSku: True } response requests.post(self.api_url, headersheaders, jsonpayload, timeout30) elif provider vv_tool: # VV-Tool API headers {Authorization: fBearer {self.third_party_key}} params {productId: product_id} response requests.get(self.backup_urls[vv_tool], headersheaders, paramsparams, timeout30) else: # 通用第三方APIo0b.cn等 url f{self.backup_urls[o0b_cn]}?key{self.third_party_key}num_iid{product_id} response requests.get(url, timeout30) response.raise_for_status() data response.json() # 标准化包装信息字段不同第三方API结构略有差异 item data.get(item, data) # 适配不同响应结构 packaging { success: True, source: fthird_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_keyyour_third_party_key) # 方式2使用官方API需企业资质 # api Alibaba1688API( # app_keyyour_app_key, # app_secretyour_app_secret, # use_officialTrue # ) # 获取商品包装信息 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)})五、包装信息字段详解核心包装字段说明字段名含义示例值应用场景weight/unitWeight商品净重单件0.8kg计算单品运费、仓储规划grossWeight商品毛重含包装1.2kg物流计费、报关申报packing包装方式描述独立包装、彩盒、OPP袋上架描述、客户预期管理packingSize单品包装尺寸10*20*5cm仓储货架规划、包装采购cartonSize外箱/ carton尺寸50*40*30cm集装箱装载计算、货运报价cartonQty每箱装箱数量50件批量采购、库存管理volume体积立方厘米10000仓储计费、运输方式选择offerSuttleWeight跨境包裹重量2.0kg跨境物流、平台发货offerLength/Width/Height跨境包裹尺寸20.0cm国际运费计算包装信息计算逻辑# 物流计费重量计算快递行业标准体积重 长*宽*高 / 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 # 总件数六、常见问题与解决方案问题现象可能原因解决方案官方API返回包装信息为空商家未填写或字段权限不足使用第三方API或联系商家补充重量单位不一致kg/g不同接口标准不同统一转换为千克kg存储尺寸格式不统一cm/mm/英寸商家录入习惯差异正则解析并标准化为厘米包装方式描述混乱商家自定义描述建立映射字典标准化如独立包装→individual跨境包裹重量与实际不符1688字段为预估重量实际发货前称重校准API调用频率受限官方API限流默认1000次/天使用第三方API或申请提升额度七、最佳实践建议数据标准化建立包装信息标准库将彩盒、color box、纸盒等映射为统一编码多源校验官方API 第三方API 页面抓取爬虫三重校验确保数据准确性缓存策略包装信息变更频率低建议缓存6-24小时减少API调用成本异常处理商家未填写包装信息时设置默认值或标记为需人工确认合规注意通过官方API或授权第三方获取数据避免未经授权的爬虫导致法律风险八、扩展应用场景基于包装信息API可构建以下应用智能运费计算根据重量、尺寸、目的地自动选择最优物流方案仓储优化基于包装尺寸计算货架空间需求优化仓库布局采购决策对比不同供应商的包装规格选择物流成本最低的方案报关自动化自动生成报关所需的重量、尺寸、包装类型数据碳足迹计算基于重量和运输距离计算碳排放量