5.6 C SDK

# allinpay-shopoint-sdk-c

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![C Standard](https://img.shields.io/badge/C-C99-blue.svg)](https://en.wikipedia.org/wiki/C99)

C 语言版本的一码付 SDK，用于集成一码付支付功能。

## 项目简介

本 SDK 提供了一套完整的 C 语言接口，用于与一码付支付平台进行交互。SDK 采用模块化设计，支持配置管理、RSA 签名验签、HTTP 请求处理、响应解析等核心功能。

**设计特点：**
- 遵循 C99 标准，确保跨平台兼容性
- 模块化架构，易于维护和扩展
- 完善的错误处理机制
- 详细的 API 文档和使用示例
- 内存安全，无内存泄漏

## 主要特性

- **配置管理**：支持从 JSON 文件和环境变量加载配置
- **多种签名算法**：支持 RSA、SM2、MD5 三种签名类型
  - RSA: SHA1WithRSA 签名（推荐）
  - SM2: 国密 SM3WithSM2 签名
  - MD5: MD5 哈希签名（不推荐，安全性较低）
- **HTTP 请求**：使用 libcurl 处理 HTTP POST 请求
- **响应解析**：使用 cJSON 解析 JSON 响应数据
- **错误处理**：完善的错误码和错误信息管理
- **跨平台**：支持 Linux、macOS、Windows（MinGW/MSVC）

## 依赖库

- **OpenSSL** (>= 1.1.1) - RSA/SM2 签名验签、SHA1/SM3 哈希、MD5 哈希
- **libcurl** (>= 7.50.0) - HTTP 请求
- **cJSON** (>= 1.7.0) - JSON 解析

**注意：** 如需使用 SM2 国密算法，请确保 OpenSSL 版本 >= 1.1.1 且编译时启用了 SM2 支持。

### 安装依赖

**Ubuntu/Debian:**
```bash
sudo apt-get install libssl-dev libcurl4-openssl-dev libcjson-dev
```

**CentOS/RHEL:**
```bash
sudo yum install openssl-devel libcurl-devel
# cJSON 需要从源码编译安装
```

**macOS:**
```bash
brew install openssl curl cjson
```

## 快速开始

[**点击下载项目源码**](https://dms.shopoint.cn/openapis/sdk/allinpay-shopoint-ocpay-sdk-c-v1.0.0.tar.gz)

### 1. 安装依赖库

详细的依赖安装说明请参考 [安装指南](https://prodoc.allinpay.com/doc/2667/)。

### 2. 编译 SDK

**使用 Makefile:**
```bash
make
```

**使用 CMake:**
```bash
mkdir build && cd build
cmake ..
make
```

编译成功后会生成：
- `libocpay.so` - 动态库
- `libocpay.a` - 静态库
- `examples/basic_usage` - 基本使用示例
- `examples/query_transaction` - 交易查询示例

### 3. 安装 SDK

```bash
sudo make install
sudo ldconfig
```

### 4. 配置 SDK

SDK 支持三种签名类型：RSA、SM2、MD5。根据您的需求选择合适的签名类型。

#### RSA 签名配置（推荐）

创建配置文件 `config.json`：

```json
{
  "app_id": "your_app_id",
  "sign_type": "RSA",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "debug_enabled": 1
}
```

#### SM2 签名配置（国密）

```json
{
  "app_id": "your_app_id",
  "sign_type": "SM2",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "debug_enabled": 1
}
```

**注意事项：**
- SM2 需要 OpenSSL 1.1.1+ 且编译时启用 SM2 支持
- 签名格式为 RS 格式（64字节），而非 ASN.1 DER 格式
- 签名时自动使用 app_id 作为用户 ID（certid）

#### MD5 签名配置（不推荐）

```json
{
  "app_id": "your_app_id",
  "sign_type": "MD5",
  "private_key": "your_md5_secret_key",
  "public_key": "your_md5_secret_key",
  "debug_enabled": 1
}
```

**注意事项：**
- MD5 不是真正的签名算法，安全性较低，仅用于测试环境
- private_key 和 public_key 填写相同的秘钥字符串即可

或使用环境变量：

```bash
export OCPAY_APP_ID="your_app_id"
export OCPAY_SIGN_TYPE="RSA"  # 或 "SM2" 或 "MD5"
export OCPAY_PRIVATE_KEY="$(cat private_key.pem)"
export OCPAY_PUBLIC_KEY="$(cat public_key.pem)"
export OCPAY_DEBUG=1
```

### 5. 使用示例

```c
#include "ocpay_sdk.h"
#include <stdio.h>
#include <stdlib.h>

int main() {
    // 1. 加载配置
    ocpay_config_t *config = ocpay_config_create();
    if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) {
        fprintf(stderr, "加载配置失败\n");
        ocpay_config_free(config);
        return -1;
    }
    
    // 2. 创建 SDK 实例
    ocpay_sdk_t *sdk = ocpay_sdk_create();
    ocpay_sdk_set_config(sdk, config);
    
    // 3. 生成请求序列号
    char *reqsn = ocpay_generate_reqsn();
    
    // 4. 构建请求参数
    const char *params[] = {
        "reqsn", reqsn,
        "trxamt", "28940",
        "goodsdesc", "测试商品",
        "notifyurl", "https://example.com/notify",
        NULL
    };
    
    // 5. 发起请求
    const char *endpoint = 
        "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/pay/unifiedorder";
    ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);
    
    free(reqsn);
    
    if (!resp) {
        fprintf(stderr, "请求失败: %s\n", 
                ocpay_get_error_message(ocpay_get_last_error()));
        ocpay_sdk_free(sdk);
        ocpay_config_free(config);
        return -1;
    }
    
    // 6. 处理响应
    if (ocpay_response_is_success(resp)) {
        printf("支付请求成功\n");
        printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid"));
        printf("交易状态: %s\n", ocpay_response_get_string(resp, "trxstatus"));
    } else {
        printf("支付请求失败: %s\n", ocpay_response_get_error_message(resp));
    }
    
    // 7. 清理资源
    ocpay_response_free(resp);
    ocpay_sdk_free(sdk);
    ocpay_config_free(config);
    
    return 0;
}
```

**编译并运行：**

```bash
# 编译
gcc -o my_app my_app.c -locpay -lssl -lcrypto -lcurl -lcjson

# 运行
./my_app
```

## 项目结构

```
allinpay-shopoint-sdk-c/
├── include/          # 公共头文件
├── src/              # 源代码实现
├── examples/         # 示例代码
├── tests/            # 测试代码
├── docs/             # 文档
├── Makefile          # 构建文件
├── CMakeLists.txt    # CMake 配置
└── README.md         # 项目说明
```

## 文档

- 🔧 [安装指南](https://prodoc.allinpay.com/doc/2667/) - 依赖安装和 SDK 编译指南
- 💡 [使用示例](https://prodoc.allinpay.com/doc/2668/) - 常见使用场景和代码示例

## 核心功能

### 配置管理

支持多种配置方式：

```c
// 从 JSON 文件加载
ocpay_config_load_from_file(config, "config.json");

// 从环境变量加载
ocpay_config_load_from_env(config);

// 验证配置
ocpay_config_validate(config);
```

### 支付请求

```c
const char *params[] = {
    "reqsn", reqsn,
    "trxamt", "28940",
    "goodsdesc", "测试商品",
    "notifyurl", "https://example.com/notify",
    NULL
};

ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);
```

### 交易查询

```c
const char *params[] = {
    "cusid", "266649",
    "version", "11",
    "reqsn", "PN20240101120000abcdef",
    "randomstr", randomstr,
    NULL
};

ocpay_response_t *resp = ocpay_sdk_request(sdk, query_endpoint, params);
```

### 响应处理

```c
if (ocpay_response_is_success(resp)) {
    const char *trxid = ocpay_response_get_string(resp, "trxid");
    const char *status = ocpay_response_get_string(resp, "trxstatus");
    printf("交易ID: %s, 状态: %s\n", trxid, status);
} else {
    printf("错误: %s\n", ocpay_response_get_error_message(resp));
}
```

## 示例程序

SDK 提供了多个完整的示例程序：

### 基本使用示例

演示完整的支付流程：

```bash
cd examples
./basic_usage
```

### 交易查询示例

演示如何查询交易状态：

```bash
cd examples
./query_transaction PN20240101120000abcdef
```

### 签名类型演示

演示如何使用不同的签名类型（RSA、SM2、MD5）：

```bash
cd examples
./sign_types_demo
```

该示例会输出三种签名类型的配置说明和使用方法。

## 开发

### 运行测试

```bash
# 编译测试
make test

# 运行所有测试
cd tests
./run_tests.sh
```

### 内存检查

使用 Valgrind 检查内存泄漏：

```bash
valgrind --leak-check=full --show-leak-kinds=all ./examples/basic_usage
```

### 代码风格

本项目遵循以下编码规范：
- 遵循 C99 标准
- 使用 4 空格缩进
- 函数名使用 `ocpay_` 前缀
- 结构体类型使用 `_t` 后缀
- 详细的函数注释和文档

### 调试模式

启用调试模式可以输出详细的日志信息：

```json
{
  "debug_enabled": 1
}
```

或设置环境变量：

```bash
export OCPAY_DEBUG=1
```

## 常见问题

### 1. 找不到头文件

```bash
# 指定头文件路径
gcc -I/usr/local/include/ocpay -o app app.c -locpay
```

### 2. 找不到库文件

```bash
# 指定库文件路径
gcc -o app app.c -L/usr/local/lib -locpay
```

### 3. 运行时找不到动态库

```bash
# 更新动态库缓存
sudo ldconfig

# 或设置 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
```

### 4. 签名失败

**RSA 签名：**
- 检查私钥格式是否正确（PEM 格式）
- 确认私钥和公钥是否匹配
- 验证 OpenSSL 版本 >= 1.1.0

**SM2 签名：**
- 确认 OpenSSL 版本 >= 1.1.1
- 检查 OpenSSL 是否启用了 SM2 支持
- 验证 SM2 密钥格式是否正确（EC 密钥）

**MD5 签名：**
- 确认秘钥字符串是否正确
- 检查参数排序是否正确（SDK 会自动处理）

### 5. 验签失败

- 检查公钥是否正确
- 确认响应数据未被篡改
- 联系服务提供方确认公钥

更多问题请参考 [安装指南](https://prodoc.allinpay.com/doc/2667/) 的故障排除部分。

## 性能特点

- **内存占用**：单个 SDK 实例 < 10MB
- **签名性能**：RSA 签名 < 5ms（2048 位密钥）
- **验签性能**：RSA 验签 < 2ms（2048 位密钥）
- **请求延迟**：< 100ms（不含网络时间）

## 安全建议

1. **密钥管理**
   - 不要在代码中硬编码密钥
   - 使用环境变量或加密配置文件
   - 定期轮换密钥
   - 建议使用 HSM（硬件安全模块）

2. **传输安全**
   - 强制使用 HTTPS 协议
   - 验证服务器证书
   - 使用 TLS 1.2 或更高版本

3. **配置安全**
   - 设置配置文件权限为 600
   - 不要将配置文件提交到版本控制系统
   - 生产环境关闭调试模式

## 兼容性

### 操作系统
- ✅ Linux (Ubuntu 18.04+, CentOS 7+, Debian 9+)
- ✅ macOS (10.14+)
- ✅ Windows (MinGW/MSVC)

### 编译器
- ✅ GCC 4.8+
- ✅ Clang 3.5+
- ✅ MSVC 2015+

### 依赖库版本
- OpenSSL >= 1.1.0
- libcurl >= 7.50.0
- cJSON >= 1.7.0

## 许可证

本项目采用 MIT 许可证。

## 致谢

感谢以下开源项目：
- [OpenSSL](https://www.openssl.org/) - 加密库
- [libcurl](https://curl.se/libcurl/) - HTTP 客户端库
- [cJSON](https://github.com/DaveGamble/cJSON) - JSON 解析库

---

**注意**：本 SDK 仅供学习和开发使用，生产环境使用前请进行充分测试。