5.5 GO SDK

# 一码付SDK (AllinpayShopointOCPaySDK)

一码付SDK是用于集成一码付支付功能的Go语言SDK。

## 功能特性

- 支持灵活的API请求（支付、查询、退款等）
- RSA签名验签
- HTTP POST请求处理
- 完整的错误处理
- 支持配置文件和环境变量配置
- 自动配置检测和验证
- 响应数据便捷处理

## 快速开始

### 下载SDK

[点击下载](https://dms.shopoint.cn/openapis/sdk/go.zip)

### 方式1: 使用配置文件

1. 复制配置模板文件：
```bash
cp config.template.json config.json
```

2. 编辑 `config.json` 文件，填入实际配置：
```json
{
  "appid": "your_app_id",
  "sign_type": "RSA",
  "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_CONTENT_HERE\n-----END PRIVATE KEY-----",
  "public_key": "-----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY_CONTENT_HERE\n-----END PUBLIC KEY-----",
  "debug_enabled": true
}
```

3. 使用SDK：

```go
package main

import (
    "log"
    "allinpay-shopoint-sdk-go/ocpay-sdk"
)

func main() {
    // 从配置文件加载配置
    config, err := ocpaysdk.LoadConfigFromFile("config.json")
    if err != nil {
        log.Fatalf("加载配置失败: %v", err)
    }
    
    // 创建SDK实例
    sdk := ocpaysdk.NewAllinpayShopointOCPaySDK()
    if err := sdk.SetConfig(*config); err != nil {
        log.Fatalf("配置SDK失败: %v", err)
    }
    
    // 发起支付请求
    paymentParams := map[string]interface{}{
        "reqsn":     ocpaysdk.GenerateReqSN(),
        "trxamt":    28940, // 289.40元 = 28940分
        "goodsdesc": "测试商品",
        "notifyurl": "https://your-domain.com/notify",
        "returnurl": "https://your-domain.com/return",
    }
    
    paymentEndpoint := "https://api.example.com/pay"
    resp, err := sdk.Request(paymentEndpoint, paymentParams)
    if err != nil {
        log.Fatalf("支付请求失败: %v", err)
    }
    
    if resp.IsSuccess() {
        log.Println("请求成功!")
        log.Printf("交易ID: %s", resp.GetTrxID())
    } else {
        log.Printf("请求失败: %s", resp.GetErrorMessage())
    }
}
```

### 方式2: 使用环境变量

1. 设置环境变量：

```bash
export OCPAY_APP_ID="your_app_id"
export OCPAY_SIGN_TYPE="RSA"
export OCPAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT_HERE
-----END PRIVATE KEY-----"
export OCPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
YOUR_PUBLIC_KEY_CONTENT_HERE
-----END PUBLIC KEY-----"
export OCPAY_DEBUG="true"
```

2. 使用SDK：

```go
package main

import (
    "log"
    "allinpay-shopoint-sdk-go/ocpay-sdk"
)

func main() {
    // 从环境变量加载配置
    config := ocpaysdk.LoadConfigFromEnv()
    
    // 验证配置
    if err := config.Validate(); err != nil {
        log.Fatalf("配置验证失败: %v", err)
    }
    
    // 创建SDK实例
    sdk := ocpaysdk.NewAllinpayShopointOCPaySDK()
    if err := sdk.SetConfig(*config); err != nil {
        log.Fatalf("配置SDK失败: %v", err)
    }
    
    // 后续使用与方式1相同...
}
```

## 运行示例

### 基础示例

```bash
cd ocpay-sdk
go run example.go
```

### 交易查询示例

```bash
cd ocpay-sdk/examples
go run demo.go
```

## API文档

### 配置结构

```go
type Config struct {
    AppID        string `json:"appid"`         // 应用ID
    SignType     string `json:"sign_type"`     // 签名类型 (RSA)
    PrivateKey   string `json:"private_key"`   // RSA私钥(用于签名)
    PublicKey    string `json:"public_key"`    // RSA公钥(用于验签)
    DebugEnabled bool   `json:"debug_enabled"` // 是否启用调试模式
}
```

### 核心方法

```go
// 创建SDK实例
func NewAllinpayShopointOCPaySDK() *AllinpayShopointOCPaySDK

// 设置配置
func (sdk *AllinpayShopointOCPaySDK) SetConfig(config Config) error

// 发起灵活的请求 - 核心方法
func (sdk *AllinpayShopointOCPaySDK) Request(endpoint string, params map[string]interface{}) (*ResponseHelper, error)
```

### 配置加载函数

```go
// 从JSON文件加载配置
func LoadConfigFromFile(filename string) (*Config, error)

// 从环境变量加载配置
func LoadConfigFromEnv() *Config

// 验证配置
func (c *Config) Validate() error
```

### 使用示例

```go
// 支付请求
paymentParams := map[string]interface{}{
    "reqsn":     ocpaysdk.GenerateReqSN(),
    "trxamt":    28940,
    "goodsdesc": "测试商品",
    "notifyurl": "https://your-domain.com/notify",
    "returnurl": "https://your-domain.com/return",
}

paymentEndpoint := "https://api.example.com/pay"
resp, err := sdk.Request(paymentEndpoint, paymentParams)

// 查询请求
queryParams := map[string]interface{}{
    "cusid":     "266649",
    "version":   "11",
    "reqsn":     "202509108000002",
    "randomstr": ocpaysdk.GenerateRandomString(16),
}

queryEndpoint := "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/tranx/query"
resp, err := sdk.Request(queryEndpoint, queryParams)

// 退款请求
refundParams := map[string]interface{}{
    "reqsn":        ocpaysdk.GenerateReqSN(),
    "orig_trxid":   "original_transaction_id",
    "refund_amt":   10000,
    "refund_reason": "用户申请退款",
}

refundEndpoint := "https://api.example.com/refund"
resp, err := sdk.Request(refundEndpoint, refundParams)
```

### 响应处理

SDK返回 `ResponseHelper` 对象，提供便捷的响应处理方法：

```go
// 获取基本信息
retCode := resp.GetRetCode()        // 返回码
trxID := resp.GetTrxID()           // 交易ID
trxStatus := resp.GetTrxStatus()   // 交易状态
reqSN := resp.GetReqSN()           // 请求序列号
trxAmt := resp.GetTrxAmt()         // 交易金额

// 获取自定义字段
userID := resp.GetString("userid")
orderID := resp.GetString("orderid")
extData := resp.GetString("extdata")

// 类型转换
amount := resp.GetInt("trxamt")     // 转换为整数
discount := resp.GetFloat("discount") // 转换为浮点数
isVip := resp.GetBool("is_vip")     // 转换为布尔值

// 检查字段是否存在
if resp.Has("custom_field") {
    value := resp.GetString("custom_field")
}

// 获取原始数据
rawData := resp.GetData()  // map[string]interface{}
rawJSON := resp.GetRaw()   // 原始JSON字符串

// 状态检查
if resp.IsSuccess() {
    // 请求成功
}
```

## 配置说明

### 必需配置项

- `AppID`: 应用ID，由一码付平台分配
- `SignType`: 签名类型，支持 RSA
- `PrivateKey`: RSA私钥，用于请求签名，需要妥善保管，由对接方生成
- `PublicKey`: RSA公钥，用于响应验签，由一码付平台提供

### 可选配置项

- `DebugEnabled`: 是否启用调试模式，开启后会打印详细日志

### 环境变量对应关系

| 配置项 | 环境变量 | 默认值 |
|--------|----------|--------|
| AppID | OCPAY_APP_ID | - |
| SignType | OCPAY_SIGN_TYPE | RSA |
| PrivateKey | OCPAY_PRIVATE_KEY | - |
| PublicKey | OCPAY_PUBLIC_KEY | - |
| DebugEnabled | OCPAY_DEBUG | false |

## 错误处理

SDK提供详细的错误信息，包括：
- 配置错误 (ErrInvalidAppID, ErrInvalidPrivateKey 等)
- 签名验签错误 (ErrSignFailed, ErrVerifyFailed)
- 网络请求错误 (ErrNetworkFailed)
- 响应解析错误 (ErrInvalidResponse)

## 注意事项

1. **安全性**
   - 请妥善保管RSA私钥，不要泄露到代码仓库
   - 建议将敏感配置放在环境变量中
   - 生产环境建议关闭调试模式

2. **配置管理**
   - 配置文件不要提交到版本控制系统
   - 可以提交 `config.template.json` 作为配置模板
   - 使用 `.gitignore` 忽略 `config.json` 文件

3. **开发建议**
   - 确保时间同步，避免签名验证失败
   - 建议在生产环境中启用HTTPS
   - 请求序列号需要保证唯一性

4. **测试**
   - 可以运行 `example.go` 进行基础功能测试
   - 可以运行 `examples/demo.go` 进行交易查询测试
   - 生产环境请使用真实的配置信息