shopee-sdk 0.1.1
Shopee API SDK for Python
License: MIT
Requires Python: >=3.8
Keywords: shopee, api, sdk, ecommerce

# Shopee SDK for Python

A Python SDK for the Shopee API, inspired by boto3's architecture with both low-level service clients and high-level resource abstractions.

## Features

- Complete coverage of Shopee API endpoints (28 service categories)
- Boto3-inspired dual-layer architecture (Service Clients + Resources)
- Built-in authentication with automatic token management
- Request signing and error handling
- Type hints for better IDE support
- Comprehensive test coverage

## Installation

```bash
pip install shopee-sdk
```

For development:

```bash
pip install shopee-sdk[dev]
```

## Authentication Flow

The Shopee API requires authentication before accessing any endpoints:

1. Use the Public service to obtain an access token
2. The SDK automatically includes the access token in subsequent requests
3. Tokens are auto-managed and can be refreshed when expired

## Quick Start

### Using Service Clients (Low-level)

```python
import shopee

session = shopee.Session(
    partner_id='your_partner_id',
    partner_key='your_partner_key',
    shop_id='your_shop_id',
    region='sg'
)

public_client = session.client('public')
token_response = public_client.get_access_token(
    code='your_authorization_code',
    shop_id='your_shop_id'
)

product_client = session.client('product')
items = product_client.get_item_list(offset=0, page_size=20)
```

### Using Resources (High-level)

```python
import shopee

session = shopee.Session(
    partner_id='your_partner_id',
    partner_key='your_partner_key',
    shop_id='your_shop_id'
)

product = session.resource('product')

all_items = product.all(offset=0, page_size=20)
item = product.get(item_id=12345)
new_item = product.create(name="Product", price=1000, stock=50)
```

## Available Services

The SDK supports 28 service categories:

- **Public** - Authentication and public endpoints
- **AMS** - Affiliate Marketing Service
- **Video** - Video management
- **Product** - Product management
- **GlobalProduct** - Cross-border product management
- **MediaSpace** - Media upload (Shopee Video)
- **Media** - Media upload (Shopee Feed)
- **Shop** - Shop management
- **Merchant** - Merchant operations
- **Order** - Order management
- **Logistics** - Shipping and logistics
- **FirstMile** - First-mile shipping
- **Payment** - Payment and financial operations
- **Discount** - Discount management
- **Bundle Deal** - Bundle deals
- **Add-On Deal** - Add-on deals
- **Voucher** - Voucher management
- **ShopFlashSale** - Flash sale management
- **Follow Prize** - Follow prize campaigns
- **TopPicks** - Top picks management
- **ShopCategory** - Shop categories
- **Returns** - Return and refund management
- **AccountHealth** - Account health metrics
- **Ads** - Advertising
- **Push** - Push notifications
- **SBS** - Seller B2B Stock
- **FBS** - Fulfillment by Shopee
- **Livestream** - Live streaming

## Service Client Usage

```python
session = shopee.Session(partner_id='...', partner_key='...', shop_id='...')

product_client = session.client('product')
order_client = session.client('order')
shop_client = session.client('shop')

product_client.get_item_list(offset=0, page_size=20)
order_client.get_order_list(time_range_field='create_time')
shop_client.get_shop_info()
```

## Resource Usage

Currently available resources:

```python
product = session.resource('product')
order = session.resource('order')
shop = session.resource('shop')

product.all()
product.get(item_id=12345)
product.create(name='Product', price=1000)
product.update(item_id=12345, price=1500)
product.delete(item_id=12345)
```

## Configuration

```python
from shopee import Session, Config

config = Config(
    base_url='https://partner.shopeemobile.com',
    timeout=30,
    max_retries=3,
    user_agent='my-app/1.0'
)

session = Session(
    partner_id='...',
    partner_key='...',
    shop_id='...',
    config=config
)
```

## Error Handling

```python
from shopee import Session, AuthenticationError, APIError

try:
    session = Session(...)
    product_client = session.client('product')
    items = product_client.get_item_list()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except APIError as e:
    print(f"API error: {e}")
```

## Testing

```bash
pytest
```

## Examples

See the [examples/](examples/) directory for more usage examples:
- [basic_usage.py](examples/basic_usage.py) - Basic authentication and API calls
- [product_management.py](examples/product_management.py) - Product CRUD operations
- [order_processing.py](examples/order_processing.py) - Order management

## Project Structure

```
shopee-sdk/
├── shopee/
│   ├── __init__.py          # Main SDK entry point
│   ├── client.py            # Client factory
│   ├── session.py           # Session management
│   ├── credentials.py        # Credential management
│   ├── auth.py              # Authentication handler
│   ├── config.py            # Configuration
│   ├── exceptions.py        # Custom exceptions
│   ├── utils/               # Utility functions
│   │   ├── sign.py         # Signature calculation
│   │   ├── request.py      # HTTP requests
│   │   └── parsers.py      # Response parsing
│   ├── services/            # 28 service clients
│   │   ├── base.py         # Base service class
│   │   ├── public.py       # Authentication service
│   │   ├── product.py      # Product service
│   │   └── ...            # Other services
│   └── resources/          # High-level resources
│       ├── base.py         # Base resource class
│       ├── product.py      # Product resource
│       ├── order.py        # Order resource
│       └── shop.py        # Shop resource
├── tests/                  # Test suite
├── examples/               # Usage examples
├── docs/                   # Documentation
└── shopee_api.md          # API reference
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License

## Support

For issues and questions, please open an issue on GitHub.