# yp-openapi-sdk

**Repository Path**: lmz/yp-openapi-sdk

## Basic Information

- **Project Name**: yp-openapi-sdk
- **Description**: sdk
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-01-19
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 亚平科技开放平台 SDK

这是亚平科技开放平台的Python SDK，提供了简单易用的接口来访问亚平科技的API服务。

## 安装

### 1. 创建虚拟环境

```bash
# 创建虚拟环境
python3.9 -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate && python test_api.py
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

## 快速开始

### 初始化客户端

```python
from yp_sdk import YaPingClient

# 创建客户端实例
client = YaPingClient(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET",
    base_url="https://mp-api.66-six.com"  # 可选，默认为测试环境
)
```

### 商品选号接口

获取可用的手机号码列表：

```python
# 基础调用
response = client.get_card(goods_id=64)

# 带城市和号码匹配规则的调用
response = client.get_card(
    goods_id=64,
    city="深圳",  # 可选，号码归属地
    pattern="1234"  # 可选，号码匹配规则，最长4位数字
)

# 响应示例
{
    "items": [
        {
            "phone": "13812345678",
            "check_code": ""
        }
    ]
}
```

### 订单查询接口

查询订单信息：

```python
# 查询所有订单（分页）
response = client.list_order(
    order_sn="Y01191632510649215",  # 可选，订单号
    page=1,                         # 可选，默认1
    page_size=20                    # 可选，默认20
)

# 响应示例
{
  "items": [
    {
      "order_sn": "TEST250119163250180983",
      "out_order_sn": "Y01191632510649215",
      "number": "138****5678",
      "status": 1,
      "status_text": "开卡中",
      "product_name": "中国联通-亲民卡",
      "create_time": "2025-01-19 16:32:51"
    }
  ],
  "pageInfo": {
    "total": 18602,
    "currentPage": 1,
    "totalPage": 931
  }
}
```

### 提单订单接口

提交新的订单：

```python
response = client.push_order(
    goods_id=64,               # 产品ID
    select_mobile="13812345678",    # 选择的号码
    name="张三",              # 姓名(必须是中文)
    card="110101199001011234",      # 身份证号码
    mobile="13812345678",           # 联系手机号
    province_code="310000",   # 省份码
    province="上海",          # 省份名
    city_code="310100",       # 城市码
    city="上海市",            # 城市名
    district_code="310104",   # 区/县码
    district="徐汇区",        # 区/县名
    address="某某路123号",     # 详细地址
    # 以下参数为可选
    timestamp="1642571420000",     # 时间戳(毫秒)
    check_code="1234",             # 选号验证码
    select_city="上海",            # 号码归属地
    front_image="http://...",      # 身份证正面照片URL
    back_image="http://...",       # 身份证反面照片URL
    head_image="http://...",       # 手持身份证照片URL
    order_sn="YP202401190001"      # 订单号
)

# 响应示例
{
  "status": true,
  "out_order_sn": "Y01191640220646162"
}
```

**注意事项：**
1. 姓名必须是中文
2. 身份证号码需要是有效的18位号码
3. 地址相关的编码和名称必须对应
4. 照片URL需要是可以公网访问的地址

## 错误处理

SDK会抛出以下异常：

- `APIError`: API调用失败时抛出，包含错误码和错误信息
- `ValidationError`: 参数验证失败时抛出
- `ConfigError`: 配置错误时抛出

```python
try:
    response = client.get_card(goods_id=64)
except APIError as e:
    print(f"API错误: {e.code} - {e.message}")
except ValidationError as e:
    print(f"参数错误: {str(e)}")
except ConfigError as e:
    print(f"配置错误: {str(e)}")
```

## 异常处理

SDK 定义了以下异常类型：

- `ConfigError`: 配置错误，如 APP_ID 或 APP_SECRET 无效
- `APIError`: API 调用错误，包含错误码和错误信息
- `ValidationError`: 参数验证错误

使用示例：

```python
try:
    response = client.push_order(...)
except APIError as e:
    print(f"API错误: {e.code}: {e.message}")
except ConfigError as e:
    print(f"配置错误: {e}")
except ValidationError as e:
    print(f"验证错误: {e}")
```

## 环境配置

SDK 支持配置不同的环境：

```python
# 测试环境
test_client = YaPingClient(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET",
    base_url="https://test-api.66-six.com"
)

# 正式环境（默认）
prod_client = YaPingClient(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET"
)
```

## 依赖说明

- Python >= 3.7
- requests
- pycryptodome

## 注意事项

1. 请妥善保管 APP_ID 和 APP_SECRET，不要泄露给他人
2. 正式环境和测试环境的 APP_ID 和 APP_SECRET 是不同的，请注意区分
3. 所有接口都使用 POST 方法，请求数据会自动加密
4. 接口返回的数据会自动解密并解析为 Python 字典

## 许可证

MIT License