https://github.com/hsojo/shopline-sdk-python
Shopline OpenAPI on python implement. (From https://open-api.docs.shoplineapp.com)
https://github.com/hsojo/shopline-sdk-python
openapi python sdk shopline shoplineapp
Last synced: 2 months ago
JSON representation
Shopline OpenAPI on python implement. (From https://open-api.docs.shoplineapp.com)
- Host: GitHub
- URL: https://github.com/hsojo/shopline-sdk-python
- Owner: HsOjo
- License: gpl-3.0
- Created: 2025-10-29T15:44:22.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-10-29T17:37:21.000Z (5 months ago)
- Last Synced: 2025-10-29T19:38:33.806Z (5 months ago)
- Topics: openapi, python, sdk, shopline, shoplineapp
- Language: Python
- Homepage:
- Size: 272 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Shopline SDK for Python
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://pypi.org/project/shopline-sdk-python/)
一个用于与 Shopline OpenAPI 交互的 Python SDK。基于 [Shopline OpenAPI 文档](https://open-api.docs.shoplineapp.com) 实现。
## 特性
- 🚀 **异步支持**: 基于 `aiohttp` 的异步 HTTP 客户端
- 📝 **类型安全**: 使用 `pydantic` 进行数据验证和类型提示
- 🛡️ **错误处理**: 完善的异常处理机制
- 📚 **完整覆盖**: 支持 Shopline OpenAPI 的所有端点
- 🔧 **易于使用**: 简洁的 API 设计，易于集成
## 安装
```bash
pip install shopline-sdk-python
```
或者使用 uv：
```bash
uv add shopline-sdk-python
```
## 快速开始
### 基本用法
```python
import asyncio
import os
from shopline_sdk.client import ShoplineAPIClient
from shopline_sdk.apis.customers import get_customers
async def main():
# 创建客户端
client = ShoplineAPIClient(os.getenv('SHOPLINE_ACCESS_TOKEN'))
# 使用客户端会话
async with client.new_session() as session:
# 调用 API
response = await get_customers.call(session)
print(f"获取到 {len(response.items)} 个客户")
# 运行异步函数
asyncio.run(main())
```
### 带参数的 API 调用
```python
import os
import asyncio
from shopline_sdk.client import ShoplineAPIClient
from shopline_sdk.apis.customers import get_customers
async def get_recent_customers():
client = ShoplineAPIClient(os.getenv('SHOPLINE_ACCESS_TOKEN'))
async with client.new_session() as session:
# 创建查询参数
params = get_customers.Params(
page=1,
per_page=10,
sort_by='desc',
include_fields=['metafields']
)
# 调用 API
response = await get_customers.call(session, params=params)
for customer in response.items:
print(f"客户: {customer.email}")
asyncio.run(get_recent_customers())
```
### 创建资源示例
```python
import os
import asyncio
from shopline_sdk.client import ShoplineAPIClient
from shopline_sdk.apis.addon_products import create_addon_product
from shopline_sdk.models.money import Money
from shopline_sdk.models.translatable import Translatable
async def create_addon():
client = ShoplineAPIClient(os.getenv('SHOPLINE_ACCESS_TOKEN'))
async with client.new_session() as session:
# 创建加购品请求体
body = create_addon_product.Body(
title_translations=Translatable(
zh_tw="加購商品",
en="Addon Product"
),
sku="ADDON-001",
unlimited_quantity=True,
cost=Money(amount="10.00", currency="USD")
)
# 调用 API
addon_product = await create_addon_product.call(session, body=body)
print(f"创建的加购品 ID: {addon_product.id}")
asyncio.run(create_addon())
```
### 更新资源示例
```python
import os
import asyncio
from shopline_sdk.client import ShoplineAPIClient
from shopline_sdk.apis.customers import update_customer
async def update_customer_info():
client = ShoplineAPIClient(os.getenv('SHOPLINE_ACCESS_TOKEN'))
async with client.new_session() as session:
customer_id = "5a55b3c973746f507e120000"
# 创建查询参数（可选字段）
params = update_customer.Params(
fields=["id", "email", "name"] # 只返回指定字段
)
# 创建请求体（要更新的数据）
body = update_customer.Body(
name="张三",
email="zhangsan@example.com",
is_accept_marketing=True
)
# 调用 API
updated_customer = await update_customer.call(
session,
id=customer_id,
params=params,
body=body
)
print(f"更新的客户: {updated_customer.name} ({updated_customer.email})")
asyncio.run(update_customer_info())
```
## API 覆盖
SDK 支持 Shopline OpenAPI 的所有主要功能模块：
### 客户管理
- 获取客户列表
- 创建、更新、删除客户
- 客户标签管理
- 会员积分管理
- 客户元数据管理
### 产品管理
- 产品 CRUD 操作
- 产品变体管理
- 库存管理
- 加购品管理
- 产品元数据管理
### 订单管理
- 订单查询和管理
- 订单配送管理
- 订单元数据管理
### 营销工具
- 促销活动管理
- 联盟营销
- 优惠券管理
- 会员等级管理
### 其他功能
- 分类管理
- 媒体文件管理
- 主题设置
- 批量操作
## 错误处理
SDK 提供了完善的错误处理机制：
```python
from shopline_sdk.client import ShoplineAPIClient
from shopline_sdk.exceptions import ShoplineAPIError
from shopline_sdk.apis.customers import get_customers
async def handle_errors():
client = ShoplineAPIClient("invalid_token")
try:
async with client.new_session() as session:
response = await get_customers.call(session)
except ShoplineAPIError as e:
print(f"API 错误: {e.status_code} - {e.message}")
print(f"错误代码: {e.code}")
if e.error:
print(f"详细错误: {e.error}")
```
## 配置
### 环境变量
建议使用环境变量来管理敏感信息：
```bash
export SHOPLINE_ACCESS_TOKEN="your_access_token_here"
```
### 自定义基础 URL
```python
from shopline_sdk.client import ShoplineAPIClient
client = ShoplineAPIClient(
access_token="your_token",
base_url="https://custom-api.shopline.io/v1"
)
```
## 许可证
本项目采用 GPL-3.0 许可证。详见 [LICENSE](LICENSE) 文件。
## 贡献
欢迎提交 Issue 和 Pull Request！
## 链接
- [Shopline OpenAPI 文档](https://open-api.docs.shoplineapp.com)
- [GitHub 仓库](https://github.com/hsojo/shopline-sdk-python)
- [PyPI 包](https://pypi.org/project/shopline-sdk-python/)
## 更新日志
### v0.1.0
- 初始版本发布
- 支持所有 Shopline OpenAPI 端点
- 异步客户端实现