Metadata-Version: 2.4
Name: amazon-sp-api-clients
Version: 2.0.1
Summary: Amazon selling partner api clients.
License: MIT
Author: Haoyu Pan
Author-email: panhaoyu.china@outlook.com
Requires-Python: >=3.14,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: boto3 (>=1.43.67,<2.0.0)
Requires-Dist: cachetools (>=7.1.7,<8.0.0)
Requires-Dist: chardet (>=7.5.1,<8.0.0)
Requires-Dist: demjson3 (>=3.0.6,<4.0.0)
Requires-Dist: peewee (>=4.3.0,<5.0.0)
Requires-Dist: pycryptodome (>=3.23.0,<4.0.0)
Requires-Dist: requests (>=2.34.2,<3.0.0)
Project-URL: repository, https://github.com/panhaoyu/sp-api-clients
Description-Content-Type: text/markdown

# amazon-sp-api-clients

Python clients for the Amazon Selling Partner API, generated from the official open api models. Fully type hinted and battle-tested. Enjoy it!

![typehint 1](./docs/source/typehint1.png)

![typehint 2](./docs/source/typehint2.png)

![typehint 3](./docs/source/typehint3.png)

## Attention

V1.0.0 changes many apis, compared with v0.x.x!

注意！V1.0.0 相较于 v0.x.x 更改了大量的 API！

## Features

- Ready to use
- Fully type hinted
- Orders, feeds, reports and all other Selling Partner APIs
- Automatically manage LWA access tokens and STS role assumption
- Ships with a code generator, in case Amazon updates the models
- 700+ mocked tests, runnable without any credentials

## Installation

```shell
pip install amazon-sp-api-clients
```

## Quick Start

All credential fields below follow the real layout of actual credentials, with the sensitive parts replaced by `...`.

```python
from datetime import datetime
import amazon_sp_api_clients

endpoint = "https://sellingpartnerapi-eu.amazon.com"
marketplace_id = "A1F83G8C2ARO7P"
refresh_token = "Atzr|...xxxx"
role_arn = "arn:aws:iam::123456789012:role/xxxxxx"
aws_access_key = "...xxxx"
aws_secret_key = "...xxxx"
client_id = "amzn1.application-oa2-client....xxxx"
client_secret = "...xxxx"

client_config = dict(
    role_arn=role_arn,
    endpoint=endpoint,
    marketplace_id=marketplace_id,
    refresh_token=refresh_token,
    aws_access_key=aws_access_key,
    aws_secret_key=aws_secret_key,
    lwa_client_key=client_id,
    lwa_client_secret=client_secret,
)

clients = amazon_sp_api_clients.AmazonSpApiClients(**client_config)
orders = clients.orders_v0.getOrders(
    MarketplaceIds=[marketplace_id],
    CreatedAfter=datetime(2000, 1, 1).isoformat(),
).payload.Orders

for order in orders:
    print(order.AmazonOrderId, order.LastUpdateDate)
```

## Configuration

Configuration can be passed to the constructor, or read from environment variables.

#### Constructor parameters

- `role_arn` — IAM role to assume, e.g. `arn:aws:iam::xxxxxxxxxxxx:role/sp_api_role`
- `endpoint` — Selling Partner API endpoint, e.g. `https://sellingpartnerapi-eu.amazon.com`
- `region` — AWS region for the STS role, default `us-east-1`
- `marketplace_id` — e.g. `A1F83G8C2ARO7P` (EU marketplace)
- `refresh_token` — LWA refresh token
- `aws_access_key` — IAM user access key
- `aws_secret_key` — IAM user secret key
- `lwa_client_key` — LWA application client id
- `lwa_client_secret` — LWA application client secret
- `raise_exceptions` — if `True` raise `SellingApiException` on error, if `False` return the response json as-is (default `True`)

#### Environment variables

- `SP_API_ROLE_ARN`
- `SP_API_ENDPOINT`
- `SP_API_REGION`
- `SP_API_MARKETPLACE_ID`
- `SP_API_REFRESH_TOKEN`
- `SP_API_AWS_ACCESS_KEY`
- `SP_API_AWS_SECRET_KEY`
- `SP_API_LWA_CLIENT_KEY`
- `SP_API_LWA_CLIENT_SECRET`

## Documentation

Detailed Chinese documentation lives under `docs/`, with `docs/README.md` as the index.

中文详细文档见 docs/ 目录，docs/README.md 为索引。

- [docs/README.md](./docs/README.md) — 文档索引
- [01_项目概览](./docs/01_项目概览.md)
- [02_快速开始](./docs/02_快速开始.md)
- [03_核心机制](./docs/03_核心机制.md)
- [04_API客户端参考](./docs/04_API客户端参考.md)
- [05_市场与端点](./docs/05_市场与端点.md)
- [06_报表与Feed类型](./docs/06_报表与Feed类型.md)
- [07_代码生成器](./docs/07_代码生成器.md)
- [08_测试指南](./docs/08_测试指南.md)
- [09_常见问题与调试](./docs/09_常见问题与调试.md)
- [10_版本历史与兼容性](./docs/10_版本历史与兼容性.md)

## Tests

700+ mocked tests runnable without any credentials. 无需任何凭证即可运行全部测试：

```shell
py -m pytest tests -q
```

## Build

Clients are generated from the Amazon open api models:

1. download the amazon selling-partner-api-models repository
1. copy open api 2 json files from the amazon repository to a single directory
1. convert open api 2 json files to open api 3 json files
1. convert open api 3 json files to py clients

The main generation script is `test_main`, and the conversion is split into 6 steps defined in the `swager_client_generator.stages` module.

If the build does not fit your demand, or Amazon updates the models but this repo has not followed yet, clone the repo, modify the `api.pyt` template and build it by yourself — and please push a PR, thanks!

See [docs/07_代码生成器.md](./docs/07_代码生成器.md) for details.

## Acknowledgement

The auth method is partially from [python-amazon-sp-api](https://github.com/saleweaver/python-amazon-sp-api).

## Note

For technical support, please contact [panhaoyu.china@outlook.com](mailto:panhaoyu.china@outlook.com).

Previously this lib was only open access but not open source, and now it's time to make it public to serve more developers.

If there's any bug, please feel free to open an issue or send a PR.

If this library helps you, please give me a star, thanks!

如果这个库对您有用，请为我点亮 Star，谢谢！

