## 平台简介与对接说明

### 平台定位与能力

易宝开放平台（YOP，Yeepay Open Platform）是易宝支付精心打造的一站式金融科技能力开放平台。平台秉承"合作、互利、共赢"的服务理念，基于易宝在支付领域数十余年的深厚技术积累，将支付处理、账户管理、资金清算等核心金融能力以标准化接口形式开放给合作伙伴，助力开发者高效构建安全可靠的金融级应用。

**技术特性**
- 严格采用 RESTful 架构风格设计，遵循业界最佳实践和规范
- 全面支持 JSON 数据交换格式，便于跨平台、跨语言集成和数据处理
- 提供详尽的接口文档和错误码说明，大幅简化问题定位和排查流程
- 实施接口版本化管理机制，确保系统平滑升级和向下兼容

### 平台对接流程

易宝开放平台的完整接入流程包含以下关键步骤：

**1. 商户入网并签约产品**
- 未入网商户：联系易宝销售团队签约，完成商户注册和资质审核
- 已入网商户：登录商户后台申请开通开发者权限
- 查看产品开通情况：确认已开通的产品和权限，核对产品功能与业务需求匹配
- 检查应用配置：确认应用标识（AppKey）和应用名称，验证应用是否具备所需产品的访问权限

**2. 密钥配置**
- 密钥制备：下载并安装密钥工具，根据安全需求选择密钥类型
  - 商密密钥(SM)：符合国家密码局安全标准，推荐 Java 语言开发者使用
  - 国际密钥(RSA)：国际通用加密算法，适用于更多开发语言，兼容性更好
- 密钥配置：登录开发者中心完成配置，上传公钥并下载平台公钥
- 安全提示：妥善保管私钥，避免泄露，将私钥存储在安全的环境中，并限制访问权限

**3. SDK 集成**
- 选择合适的 SDK：根据开发语言选择对应 SDK，确认版本兼容性，检查环境依赖
- 引入 SDK：使用包管理器安装或手动下载集成，配置依赖关系
- 配置客户端参数：设置应用参数，配置密钥信息，设置环境参数

**4. 开发与接口调用**
- 了解业务场景和模型：明确业务需求与平台能力的匹配点，设计合理的业务流程
- 实现接口调用逻辑：按照示例代码实现核心功能，处理请求响应
- 实现异步通知接收接口：开发稳定可靠的回调接口，确保能够接收并处理平台的异步通知

**5. 测试验证**
- 使用沙箱环境：在测试环境下进行功能验证和压力测试
- 全流程测试：对主要业务流程进行端到端测试，验证功能正确性和系统稳定性
- 处理异常情况：测试各类异常场景和边界条件，确保系统健壮性

**6. 正式上线**
- 验证系统稳定性和业务连续性
- 切换至生产环境配置，准备正式运营和业务开展
- 持续监控系统性能，优化用户体验

### 平台对接SDK工具

易宝开放平台 SDK 是官方提供的开发工具包，封装了请求处理、签名加密、响应解析等核心功能，显著降低开发成本，提高开发效率。

支持的语言版本：
- Java SDK (yop-java-sdk)：支持 JDK 1.8 及以上版本，[GitHub](https://github.com/yop-platform/yop-java-sdk)，可能需要安装JCE包，支持多域名路由功能版本：`3.3.10`、`4.1.13`、`4.2.4`、`4.2.5`、`4.4.1`及以上
- PHP SDK (yop-php-sdk)：需要 PHP 5.5 及以上版本，[GitHub](https://github.com/yop-platform/yop-php-sdk)
- .NET SDK (yop-dotnet-sdk)：需要 .NET Framework 2.0 及以上版本，[GitHub](https://github.com/yop-platform/yop-dotnet-sdk)，不支持Windows Phone平台
- TypeScript SDK (yop-typescript-sdk)：需要 Node.js 18.0.0 及以上版本，[GitHub](https://github.com/yop-platform/yop-typescript-sdk)，[NPM](https://www.npmjs.com/package/yop-typescript-sdk)，安装方法：`npm i yop-typescript-sdk`
- Node.js SDK (yop-nodejs-sdk)：需要 Node.js 18.0.0 及以上版本，[GitHub](https://github.com/yop-platform/yop-nodejs-sdk)，[NPM](https://www.npmjs.com/package/yop-nodejs-sdk)，安装方法：`npm i yop-nodejs-sdk`
- Python SDK (yop-python-sdk)：需要 Python 2.7 及以上版本，[GitHub](https://github.com/yop-platform/yop-python-sdk)
- Go SDK (yop-go-sdk)：建议使用 Go 1.18 及以上版本，[GitHub](https://github.com/yop-platform/yop-go-sdk)

### 平台错误码说明

易宝开放平台提供了详细的错误码体系，帮助开发者准确定位和解决问题：

**1. 主要错误码类型**

| 错误码 | 错误描述 | 典型子错误码 | 解决方案 |
|-------|---------|------------|---------|
| 40020 | 服务不可用 | sys.service.retryable | 联系技术支持，核实失败原因，稍后再试 |
| 40021 | 授权权限不足 | sys.authorization.unauthorized | 找服务提供方授权开通相关产品 |
| 40029 | 访问受限 | sys.limit.rate-limit | 适当降低请求频率或联系服务提供者放宽配额 |
| 40042 | 非法的参数 | isv.check.request-param.miss | 查询API文档，检查必填参数是否缺失 |
| 40044 | 业务处理失败 | isp.code.xxx | 查询API文档，如有疑问请联系技术支持 |
| 40047 | 鉴权认证失败 | isv.authentication.digest.verify-failure | 检查密钥是否正确，检查公私钥是否匹配 |
| 40048 | 加解密异常 | isv.encrypt.param.decrypt-failure | 确认当前调用环境与平台公钥配置是否一致 |

**2. 错误处理建议**
- 根据错误码判断错误类型，采取相应措施
- 临时性错误可以重试，永久性错误需要修正请求内容
- 对于授权或配置类错误，及时联系技术支持
- 参数错误应查阅API文档进行修正
- 频率限制需优化调用策略，必要时申请更高配额 


## 平台网站地图

- 产品中心：[产品中心](https://open.yeepay.com/docs-v3/product/llms.txt)
- 接入指引：[接入指引](https://open.yeepay.com/docs-v3/platform/llms.txt)