# jlpay-sdk-python

**Repository Path**: jlpaydemo/jlpay-sdk-python

## Basic Information

- **Project Name**: jlpay-sdk-python
- **Description**: 咕朵云sdk的python版本
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-20
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 嘉联支付开放平台 Python SDK

这是嘉联支付开放平台的Python SDK，为第三方应用提供与嘉联支付系统集成的接口能力。SDK封装了HTTP请求、签名验证、数据加解密等底层功能，简化开发者的接入流程。

## 1. 项目安装说明

### 环境要求

- Python 3.7+
- 以下依赖包：
  - requests>=2.28.1
  - gmssl>=3.2.2
  - asn1crypto>=1.5.1
  - sm-crypto>=0.1.1
  - pyasn1>=0.5.1

### 安装方法

#### 方法一：pip安装

```bash
pip install jlpay-sdk
```

#### 方法二：从源码安装

```bash
git clone https://github.com/jlpay/jlpay-sdk-python.git
cd jlpay-sdk-python
pip install -e .
```

## 2. 示例使用说明

SDK提供了丰富的示例代码，位于`examples`目录下：

### 基础数据查询示例

查看 `examples/base_data_example.py` 了解如何使用SDK查询银行信息、MCC码等基础数据。

```python
# 基础数据查询示例代码
from jlpay.base.config import OrgConfig
from jlpay.services.base_data_service import BaseDataService
from jlpay.services.org_service import JlpayOrgService

# 创建配置
config = OrgConfig.builder() \
    .app_id("YOUR_APP_ID") \
    .url("https://api.jlpay.com") \
    .org_pri_key("YOUR_PRIVATE_KEY") \
    .jlpay_pub_key("JLPAY_PUBLIC_KEY") \
    .build()

# 创建基础服务
org_service = JlpayOrgService.builder() \
    .config(config) \
    .build()

# 创建基础数据服务
base_data_service = BaseDataService(org_service)

# 查询银行总行列表
response = base_data_service.query_bank_list(
    org_no="YOUR_ORG_NO",
    limit=10,
    offset=0
)
```

### 账单查询示例

查看 `examples/bill_example.py` 了解如何查询和下载账单。

### 商户进件示例

- 通用进件：`examples/openmerch/register/incoming_add_example.py`、`examples/merchant_incoming_demo.py`
- **商户进件 5 种场景**（企业+对公/法人/授权对私/授权对公+电子签约，小微+电子签约）：`examples/openmerch/register/incoming_add_scenarios_example.py`，可调用 `demo_scenario(1)`～`demo_scenario(5)` 分别演示

### 接口分账（入账方）示例

- 入账方注册：`examples/ledger/merchconf/merch_rev_open_example.py`（含出账方商户号 `ledger_mch_id`、电子协议链接 `sign_link`）
- 入账方信息查询：`examples/ledger/merchconf/merch_rev_query_example.py`（返回含电子协议链接）
- 入账方签约信息修改（获取新签约链接）：`examples/ledger/merchconf/merch_rev_modify_sign_url_example.py`

### 支付产品示例

- **银联行业码支付-获取 user_id**：`examples/trans/union/get_union_pay_user_id_example.py`（接口 path：`/open/trans/getopenid`，pay_type=unionpay）
- **异步退款**（支持退款结果通知地址 `notify_url`）：`examples/trans/refunds/refunds_example.py`

### 日志配置示例

查看 `examples/log_config_demo.py` 了解如何配置SDK的日志。

### 文件上传示例

查看 [README_文件上传.md](readme/README_文件上传.md) 了解如何使用SDK进行文件上传操作。


## 3. 测试说明

SDK 提供了完整的单元测试用例，位于 `tests` 目录下。

### 运行需求相关功能验证（不请求真实 API）

```bash
python tests/test_requirements_modified.py
```

用于校验商户进件 5 场景、入账方、银联 user_id、异步退款 notify_url 等模型与服务可用。

### 运行所有测试

```bash
python -m unittest discover -s tests
```

### 运行单个测试文件

```bash
python -m unittest tests/utils/test_sm_utils.py
```

### 测试覆盖率

要生成测试覆盖率报告，请安装`pytest`和`pytest-cov`：

```bash
pip install pytest pytest-cov
pytest --cov=jlpay tests/
```

生成HTML报告：

```bash
pytest --cov=jlpay --cov-report=html tests/
```

报告将生成在`htmlcov`目录中，您可以打开`htmlcov/index.html`查看详细报告。

## 4. 常见问题

### 密钥格式问题

SDK使用PEM格式的密钥，如果您的密钥不是PEM格式，需要先进行转换。

### 签名验证失败

- 请检查密钥是否正确
- 请检查请求参数是否正确
- 请检查服务器时间是否同步

## 5. 版本说明

- v1.0.3：商户进件 5 种场景示例；接口分账入账方（注册/查询/签约信息修改）及电子协议链接；银联行业码获取 user_id；异步退款 notify_url；需求相关功能验证测试 `tests/test_requirements_modified.py`
- v1.0.2：补充收银台、清结算、资金管控、分账、商户管理、交易模块 demo
- v1.0.1：包含 examples 和 tests 目录，方便用户参考和测试
- v1.0.0：初始版本

## 6. 联系方式

如果您有任何问题或建议，请通过以下方式与我们联系：

- 邮箱：support@jlpay.com

## 7. 项目功能说明

| 版本     | 日期        | 版本说明                                                                                                                                 |
|--------|-----------|----------------------------------------------------------------------------------------------------------------------------------------|
| v1.0.3 | 2026/2/3  | 商户进件 5 种场景示例；接口分账入账方（注册含出账方商户号/电子协议链接、查询含电子协议链接、签约信息修改）；银联行业码支付-获取 user_id；异步退款请求参数 notify_url；需求相关验证测试 |
| v1.0.2 | 2025/7/30 | 补充收银台（收银托管预下单、订单状态查询、撤单、退款）、清结算、资金管控、分账、商户管理、交易模块 demo                                                                                 |
| v1.0.1 | 2025/5/20 | 自动签名验签、HTTP 请求封装、异常处理、日志配置、SM2/SM4、敏感数据加密、公共基础数据查询、账单、商户服务（进件、查询）、文件上传等                                                       |