makemd/docs/api/Shopee_API_Documentation.md

# Shopee Open Platform API 文档

## 1. 概述

Shopee Open Platform 是Shopee为开发者提供的开放API平台，旨在帮助开发者为Shopee卖家提供各种电子商务解决方案。通过Shopee Open API，开发者可以创建定制化的软件服务，满足卖家在订单处理、产品优化、店铺推广等方面的需求。

## 2. API分类

### 2.1 商品管理API

| 接口名称 | 功能描述 | 适用场景 |
|---------|---------|----------|
| 商品详情API | 获取商品的详细信息，包括标题、价格、库存、描述、图片、规格参数等 | 电商导购、价格监控、库存同步 |
| 商品列表API | 获取店铺内的商品列表 | 商品管理、库存管理 |
| 商品上传API | 上传新商品到店铺 | 批量上架、商品管理 |
| 商品更新API | 更新现有商品信息 | 商品信息维护 |
| 商品删除API | 删除店铺内的商品 | 商品管理 |

### 2.2 订单管理API

| 接口名称 | 功能描述 | 适用场景 |
|---------|---------|----------|
| 订单列表API | 获取店铺的订单列表 | 订单管理、订单同步 |
| 订单详情API | 获取订单的详细信息 | 订单处理、物流安排 |
| 订单状态更新API | 更新订单状态 | 订单处理、发货管理 |
| 订单取消API | 取消订单 | 订单管理、客户服务 |

### 2.3 物流管理API

| 接口名称 | 功能描述 | 适用场景 |
|---------|---------|----------|
| 物流信息查询API | 查询物流状态和轨迹 | 物流跟踪、客户服务 |
| 发货API | 标记订单为已发货 | 订单处理、物流管理 |
| 物流渠道API | 获取可用的物流渠道 | 物流选择、成本计算 |

### 2.4 营销API

| 接口名称 | 功能描述 | 适用场景 |
|---------|---------|----------|
| 促销活动API | 创建和管理促销活动 | 店铺推广、销售提升 |
| 优惠券API | 创建和管理优惠券 | 客户吸引、转化率提升 |
| 广告API | 管理店铺广告 | 流量提升、品牌曝光 |

### 2.5 店铺管理API

| 接口名称 | 功能描述 | 适用场景 |
|---------|---------|----------|
| 店铺信息API | 获取店铺基本信息 | 店铺管理、数据分析 |
| 店铺设置API | 更新店铺设置 | 店铺管理、品牌建设 |
| 销售数据API | 获取店铺销售数据 | 数据分析、决策支持 |

## 3. API认证与授权

### 3.1 开发者注册流程

**注册地址**：[Shopee Open Platform](https://open.shopee.com/)

**注册资格**：
- 企业开发者：需要提供企业营业执照、税务登记证等
- 个人开发者：需要提供个人身份证明
- 必须具备电子商务相关业务经验

**所需材料**：
1. 企业营业执照（企业开发者）
2. 税务登记证（企业开发者）
3. 法人身份证明
4. 联系方式（邮箱、电话）
5. 公司银行账户信息
6. 业务计划书（描述应用程序的功能和用途）

**注册步骤**：
1. 访问Shopee Open Platform注册地址
2. 点击"Sign Up"按钮，创建开发者账号
3. 填写注册信息，上传所需材料
4. 等待平台审核（通常1-3个工作日）
5. 审核通过后，登录开发者控制台
6. 创建应用，获取Partner ID和Partner Key
7. 设置应用回调地址
8. 配置应用权限范围
9. 获取测试环境访问权限

**注意事项**：
- 确保提供真实有效的信息
- 保护好Partner ID和Partner Key，避免泄露
- 遵守Shopee的使用条款和限制
- 定期更新API密钥以保证安全
- 如遇到注册问题，可联系Shopee开放平台客服

### 3.2 认证流程

1. 注册并登录Shopee Open Platform
2. 创建应用并获取API密钥（Partner ID和Partner Key）
3. 实现OAuth授权流程获取访问令牌
4. 使用访问令牌调用API接口

### 3.3 授权方式

- **v1版本授权**：基于OAuth 2.0的授权流程
- **v2版本授权**：更安全的授权机制，支持刷新令牌

## 4. API调用示例

### 4.1 商品详情API调用示例

```java
// Java示例代码
public class ShopeeApiClient {
    private String apiKey;
    private String apiSecret;
    private String shopId;
    private String accessToken;
    
    public ShopeeApiClient(String apiKey, String apiSecret, String shopId, String accessToken) {
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
        this.shopId = shopId;
        this.accessToken = accessToken;
    }
    
    public JSONObject getProductDetail(long productId) throws Exception {
        // 构建请求参数
        JSONObject params = new JSONObject();
        params.put("product_id", productId);
        
        // 生成签名
        String signature = generateSignature("product/get", params);
        
        // 发送请求
        String url = "https://partner.shopeemobile.com/api/v2/product/get";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + accessToken)
                .header("shopid", shopId)
                .header("partner_id", apiKey)
                .header("timestamp", String.valueOf(System.currentTimeMillis() / 1000))
                .header("sign", signature)
                .POST(HttpRequest.BodyPublishers.ofString(params.toString()))
                .build();
        
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        return new JSONObject(response.body());
    }
    
    private String generateSignature(String path, JSONObject params) throws Exception {
        // 生成签名的逻辑
        // ...
        return signature;
    }
}
```

### 4.2 订单列表API调用示例

```python
# Python示例代码
import hashlib
import time
import requests
import json

def get_shopee_orders(partner_id, api_key, shop_id, access_token, timestamp=None):
    if timestamp is None:
        timestamp = int(time.time())
    
    # 构建请求参数
    params = {
        "time_range": 30,
        "page_size": 100,
        "page_no": 1
    }
    
    # 生成签名
    sign_string = f"partner_id={partner_id}&shopid={shop_id}&timestamp={timestamp}"
    for key, value in sorted(params.items()):
        sign_string += f"&{key}={value}"
    sign_string += api_key
    signature = hashlib.sha256(sign_string.encode()).hexdigest()
    
    # 发送请求
    url = "https://partner.shopeemobile.com/api/v2/order/list"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "shopid": shop_id,
        "partner_id": str(partner_id),
        "timestamp": str(timestamp),
        "sign": signature
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(params))
    return response.json()
```

## 5. API返回值解析

### 5.1 商品详情API返回值

| 字段名 | 类型 | 描述 |
|-------|------|------|
| item_id | Long | 商品ID |
| name | String | 商品标题 |
| description | String | 商品描述 |
| price | Number | 商品价格 |
| stock | Number | 商品库存 |
| images | Array | 商品图片URL列表 |
| variations | Array | 商品规格信息 |
| category_id | Long | 商品分类ID |
| brand | String | 商品品牌 |
| attributes | Object | 商品属性 |

### 5.2 订单详情API返回值

| 字段名 | 类型 | 描述 |
|-------|------|------|
| order_id | String | 订单ID |
| buyer_user_id | String | 买家ID |
| create_time | Number | 订单创建时间 |
| pay_time | Number | 订单支付时间 |
| order_status | String | 订单状态 |
| total_amount | Number | 订单总金额 |
| currency | String | 货币类型 |
| shipping_fee | Number | 运费 |
| items | Array | 订单商品列表 |
| recipient_address | Object | 收货地址信息 |
| logistics_info | Object | 物流信息 |

### 5.3 错误码定义

| 错误码 | 错误消息 | 可能原因 | 解决方法 |
|-------|---------|---------|----------|
| 0 | Success | 请求成功 | - |
| 400 | Bad Request | 请求参数错误 | 检查请求参数是否符合要求 |
| 401 | Unauthorized | 认证失败 | 检查API密钥和访问令牌是否正确 |
| 403 | Forbidden | 权限不足 | 检查应用是否有相应的权限 |
| 404 | Not Found | 资源不存在 | 检查请求的资源ID是否正确 |
| 429 | Too Many Requests | 请求频率过高 | 减少API调用频率，实现限流机制 |
| 500 | Internal Server Error | 服务器内部错误 | 稍后重试，如持续失败联系平台支持 |
| 1001 | Invalid Partner ID | Partner ID无效 | 检查Partner ID是否正确 |
| 1002 | Invalid Signature | 签名错误 | 检查签名生成方法是否正确 |
| 1003 | Token Expired | 令牌过期 | 重新获取访问令牌 |
| 1004 | Invalid Shop ID | 店铺ID无效 | 检查Shop ID是否正确 |
| 1005 | Resource Not Available | 资源不可用 | 检查资源状态或权限 |

## 6. 最佳实践

### 6.1 API调用频率限制

- 遵守Shopee Open Platform的API调用频率限制
- 合理使用缓存减少API调用次数
- 批量操作减少API请求数量

### 6.2 错误处理

- 正确处理API返回的错误码
- 实现重试机制处理临时错误
- 记录详细的错误日志便于调试

### 6.3 安全措施

- 保护API密钥和访问令牌
- 使用HTTPS协议进行API调用
- 定期更新访问令牌

### 6.4 安全最佳实践

- **API密钥保护**：
  - 不要在代码中硬编码Partner ID和Partner Key
  - 使用环境变量或安全的配置管理系统存储API密钥
  - 定期更换API密钥
  - 限制API密钥的使用范围

- **访问令牌管理**：
  - 妥善存储访问令牌和刷新令牌
  - 设置合理的令牌过期时间
  - 实现令牌自动刷新机制
  - 避免在客户端存储敏感令牌

- **请求安全**：
  - 始终使用HTTPS协议进行API调用
  - 正确生成和验证请求签名
  - 避免在URL中传递敏感信息
  - 实现请求超时和重试机制

- **权限控制**：
  - 仅申请必要的API权限
  - 定期审查应用的权限设置
  - 对不同环境使用不同的API密钥

- **数据安全**：
  - 加密存储用户数据
  - 避免传输敏感信息
  - 实现数据访问控制
  - 定期备份重要数据

## 7. 接口使用场景分析

### 7.1 电商ERP系统集成

- **商品管理**：批量上传、更新商品信息
- **订单处理**：自动同步订单、批量发货
- **库存管理**：实时同步库存信息
- **数据分析**：获取销售数据进行分析

### 7.2 价格监控工具

- **商品详情**：获取商品价格和库存信息
- **价格历史**：跟踪商品价格变化
- **竞品分析**：比较不同店铺的商品价格

### 7.3 营销工具

- **促销管理**：创建和管理促销活动
- **优惠券管理**：生成和分发优惠券
- **广告管理**：优化店铺广告投放

## 8. 总结

Shopee Open Platform API为开发者提供了丰富的接口，涵盖了商品、订单、物流、营销和店铺管理等各个方面。通过合理使用这些API，开发者可以创建各种工具和服务，帮助Shopee卖家提高运营效率、提升销售业绩。

在使用Shopee API时，开发者需要注意遵守平台的使用规则，合理控制API调用频率，确保数据安全，并不断优化API调用策略，以获得最佳的使用效果。

## 9. 参考资源

- [Shopee Open Platform官方网站](https://open.shopee.com/)
- [Shopee Open Platform开发者指南](https://open.shopee.com/developer-guide)
- [Shopee API授权流程](https://blog.csdn.net/weixin_42351510/article/details/129432348)
- [Shopee商品详情API解析](https://blog.csdn.net/sa10027/article/details/138483014)