Metadata-Version: 2.4
Name: qdata-adapter-jky
Version: 0.1.1
Summary: QDataV2 adapter for jky
Author-email: 广东轻亿云软件科技有限公司 <opensource@qeasy.cloud>
Maintainer-email: QData Team <opensource@qeasy.cloud>
License: MIT
Project-URL: Homepage, https://www.qeasy.cloud
Project-URL: Documentation, https://github.com/qeasy/qdata-adapter-jky#readme
Project-URL: Repository, https://github.com/qeasy/qdata-adapter-jky
Project-URL: Bug Tracker, https://github.com/qeasy/qdata-adapter-jky/issues
Project-URL: Changelog, https://github.com/qeasy/qdata-adapter-jky/blob/main/CHANGELOG.md
Keywords: qdata,adapter,jky,integration,qeasy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qdata-adapter-base>=1.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.28.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Provides-Extra: all
Requires-Dist: qdata-adapter-jky[dev,docs]; extra == "all"
Dynamic: license-file

# JkyAdapter

<p align="center">
  <strong>QDataV2 吉客云（Jky）数据集成适配器</strong>
</p>

<p align="center">
  由 <a href="https://www.qeasy.cloud">广东轻亿云软件科技有限公司</a> 开发<br>
  「轻易云数据集成平台」官方适配器
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="License: AGPL v3"></a>
  <a href="https://pypi.org/project/qdata-adapter-jky/"><img src="https://img.shields.io/pypi/v/qdata-adapter-jky.svg" alt="PyPI version"></a>
  <a href="https://github.com/qeasy/qdata-adapter-jky/actions/workflows/ci.yml"><img src="https://github.com/qeasy/qdata-adapter-jky/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
</p>

---

## 功能作用

本适配器用于集成 **吉客云开放平台**（https://open.jackyun.com/），通过 `invoke()` 方法可调用吉客云提供的全部 API 接口，包括但不限于：

- 供应商管理（查询、创建、更新、停用）
- 订单数据同步
- 商品信息管理
- 库存数据查询
- 客户管理
- 财务对账
- 更多 API...

## 多接口支持

本适配器支持多种接口模式，通过 `settings.interface` 参数切换：

| 接口 | 说明 | 适用场景 |
|------|------|---------|
| `standard`（默认） | 主接口 | 标准业务集成 |
| `qimen` | 奇门网关接口 | 淘系订单对接 |

## 统一调用方式

使用 `invoke()` 方法可调用吉客云平台的任意 API：

```python
# 查询列表
result = await adapter.invoke(
    method="query",
    object_type="oms.trade.fullinfoget",
    params={"pageNo": 1, "pageSize": 100}
)

# 获取单个对象
result = await adapter.invoke(
    method="get",
    object_type="erp.vend.get",
    params={"code": "VENDOR_001"}
)

# 创建对象
result = await adapter.invoke(
    method="create",
    object_type="erp.vend.create.v2",
    data={"code": "NEW_VENDOR", "name": "新供应商", ...}
)

# 更新对象
result = await adapter.invoke(
    method="update",
    object_type="erp.vend.update",
    data={"vendId": "123", "name": "更新后的名称", ...}
)
```

## 快速开始

查看 [QUICKSTART.md](QUICKSTART.md) 获取 5 分钟上手指南。

```bash
# 安装
pip install qdata-adapter-jky

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的 API 凭据

# 运行示例
python examples/quickstart.py
```

## API 文档

- 吉客云开放平台：https://open.jackyun.com/
- 轻易云官网：https://www.qeasy.cloud

## 认证配置

### Standard 接口

| 环境变量 | 说明 |
|----------|------|
| `JKY_APP_KEY` | 应用密钥 |
| `JKY_APP_SECRET` | 应用密码 |
| `JKY_TOKEN` | 访问令牌 |
| `JKY_VERSION` | API 版本（默认 1.0） |

### Qimen 接口

| 环境变量 | 说明 |
|----------|------|
| `JKY_QIMEN_HOST` | 奇门网关地址（默认：https://zci2vl4joy.api.taobao.com/router/qm） |
| `JKY_QIMEN_APP_KEY` | 奇门 AppKey |
| `JKY_QIMEN_APP_SECRET` | 奇门 AppSecret |
| `JKY_QIMEN_TARGET_APP_KEY` | 奇门网关 ERP 应用标识 |
| `JKY_QIMEN_JKY_APP_KEY` | 吉客云开放平台 AppKey |
| `JKY_QIMEN_JKY_APP_SECRET` | 吉客云开放平台 AppSecret |
| `JKY_QIMEN_CUSTOMER_ID` | 吉客云客户 ID |

### Qimen 接口使用示例

```python
import asyncio

from qdata_adapter_jky import JkyAdapter
from qdata_adapter import ConnectorContext


async def main():
    # 配置 Qimen 接口
    context = ConnectorContext(
        connector_id="my-qimen-connector",
        app_software_code="jky",
        base_url="https://zci2vl4joy.api.taobao.com/router/qm",
        auth_config={
            "app_key": "your-qimen-app-key",
            "app_secret": "your-qimen-app-secret",
            "target_app_key": "your-target-app-key",
            "jkyappkey": "your-jky-app-key",
            "jkyappsecret": "your-jky-app-secret",
            "jkycustomerid": "your-customer-id",
        },
        settings={"interface": "qimen"},
    )

    adapter = JkyAdapter(context)

    # 查询订单
    result = await adapter.invoke(
        method="query",
        object_type="jackyun.tradenotsensitiveinfos.list.get",
        params={
            "pageSize": "200",
            "pageIndex": 1,
            "startConsignTime": "2024-01-01 00:00:00",
            "endConsignTime": "2024-01-31 23:59:59",
            "tradeType": "1",
            "fields": "tradeNo,postFee,tradeStatus,goodsDetail"
        }
    )


asyncio.run(main())
```

## 接口对比

| 特性 | Standard | Qimen |
|------|----------|-------|
| 认证方式 | Token + Sign | 双签名（jkysign + taobao sign） |
| 适用场景 | 标准业务接口 | 淘系订单、奇门网关 |
| 签名算法 | MD5 | MD5（双层） |
| JSON 格式 | 紧凑 | PHP 风格（带空格） |

## License

AGPL-3.0 © 广东轻亿云软件科技有限公司
