vservicesharesdk

module
v0.0.0-...-1038186 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 16, 2026 License: Apache-2.0

README

ServiceShare SDK for Go

Go SDK for ServiceShare (佣金保) API integration.

Features

  • Secure DES-ECB encryption for request/response data
  • RSA-SHA1 signing for request authentication
  • Complete API coverage:
    • Account balance query (6003)
    • Freelancer silent contract signing (6010)
    • Freelancer contract status query (6011)
    • Freelancer face authentication (6009)
    • Sync face authentication record (6008)
    • Merchant batch payment (6001)
    • Batch payment status query (6002)
  • Flexible key formats: PEM or raw base64
  • Clean architecture following Go best practices
  • Type-safe API with comprehensive error handling

Installation

go get github.com/vogo/vservicesharesdk

Quick Start

// Create configuration
config := cores.NewConfig(
    "http://testgateway.serviceshare.com/testapi/clientapi/clientBusiness/common",
    "YOUR_MERCHANT_ID",
    "12345678901234567890123456789012", // DES key (uses first 8 bytes)
    "YOUR_RSA_PRIVATE_KEY",              // PEM format or raw base64
    "YOUR_PLATFORM_PUBLIC_KEY",          // PEM format or raw base64
	"YOUR_TASK_ID",                      // Task ID
)

// Create client
client, err := cores.NewClient(config)
if err != nil {
	log.Fatal(err)
}

// Create service and query balance
accountService := accounts.NewService(client)
resp, err := accountService.QueryBalance(&accounts.BalanceQueryRequest{
	ProviderID: 123456789, // int64
})
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Balance: %d fen\n", resp.Balance)

Configuration

Config Parameters
Parameter Type Required Description
BaseURL string Yes API endpoint URL
MerchantID string Yes Merchant ID from platform
DesKey string Yes DES encryption key (uses first 8 bytes)
PrivateKey string Yes Merchant RSA private key (PEM or raw base64)
PlatformPublicKey string Yes Platform RSA public key (PEM or raw base64)
TaskID string Yes Task ID for the request
Version string No API version (default: "V1.0")
Timeout time.Duration No HTTP timeout (default: 60s)
Key Formats

RSA Keys support two formats:

  • PEM format: Standard format with -----BEGIN/END----- headers
  • Raw base64: Base64-encoded DER format without headers
Environment URLs

Test Environment:

http://testgateway.serviceshare.com/testapi/clientapi/clientBusiness/common

Production Environment: Contact ServiceShare operations team for production URL.

API Reference

Accounts Service

Balance Query (FunCode: 6003)

accountService := accounts.NewService(client)
resp, err := accountService.BalanceQuery(&accounts.BalanceQueryRequest{
    ProviderID:  123456789, // int64
    PaymentType: cores.PaymentTypeBankCard, // Optional
})
// resp.Balance in fen (1 yuan = 100 fen)
Freelancers Service

Silent Contract Signing (FunCode: 6010)

freelancerService := freelancers.NewService(client)
resp, err := freelancerService.SignContract(&freelancers.SignContractRequest{
    Name:        "张三",
    CardNo:      "6222021234567890123",
    IdCard:      "110101199001011234",
    Mobile:      "13800138000",
    PaymentType: cores.PaymentTypeBankCard,
    ProviderId:  123456789, // int64
    IdCardPic1:  "HEX_ENCODED_FRONT_PHOTO",
    IdCardPic2:  "HEX_ENCODED_BACK_PHOTO",
})
// Asynchronous operation - check callback or use contract query

Contract Status Query (FunCode: 6011)

resp, err := freelancerService.SignContractQuery(&freelancers.SignQueryRequest{
    Name:       "张三",
    IdCard:     "110101199001011234",
    Mobile:     "13800138000",
    ProviderId: 123456789, // int64
})
// resp.State: 0=unsigned, 1=signed, 2=not found, 3=pending, 4=failed, 5=cancelled

Face Authentication (FunCode: 6009)

resp, err := freelancerService.FaceAuth(&freelancers.FaceAuthRequest{
    Name:            "张三",
    IdCard:          "110101199001011234",
    Mobile:          "13800138000",
    RedirectUrl:     "https://example.com/callback", // Optional
    RedirectBtnName: "返回",                          // Optional
})
// resp.Url: H5 page URL for face recognition (valid for one day)
// Requires the user to have a successfully signed contract

Sync Face Authentication Record (FunCode: 6008)

resp, err := freelancerService.SyncFaceAuth(&freelancers.SyncFaceAuthRequest{
    Name:        "张三",
    IdCard:      "110101199001011234",
    Mobile:      "13800138000",
    ThirdId:     "UNIQUE_TRACE_CODE_001",
    AuthTime:    "2024-01-15 10:30:00",
    Urls:        []string{"https://example.com/face_photo.jpg"},
    AuthChannel: cores.AuthChannelAlipay, // See AuthChannel constants
})
// resp.FaceAuthEndTime: Face authentication expiration date (format: YYYY-MM-DD)
// Error code 6323 means face auth record already exists

AuthChannel Constants:

Constant Value Description
AuthChannelBaidu "01" 百度云
AuthChannelAliyun "02" 阿里云
AuthChannelTencent "03" 腾讯云
AuthChannelFadada "04" 法大大
AuthChannelAlipay "05" 支付宝
AuthChannelVolcano "06" 火山引擎
AuthChannelHuawei "07" 华为云
AuthChannelSensetime "08" 商汤科技
AuthChannelMegvii "09" 旷世Face++
AuthChannelJDCloud "10" 京东智联云
AuthChannelWechatPay "11" 微信支付
AuthChannelOther "12" 其他活体通道
Payments Service

Batch Payment (FunCode: 6001)

paymentService := payments.NewService(client)
resp, err := paymentService.Payment(&payments.PaymentRequest{
    MerBatchId: "BATCH_001",
    PayItems: []payments.PaymentItem{
        {
            MerOrderId:  "ORDER_001",
            Amt:         10000, // 100 CNY in fen
            PayeeName:   "张三",
            PayeeAcc:    "6222021234567890123",
            IdCard:      "110101199001011234",
            Mobile:      "13800138000",
            PaymentType: cores.PaymentTypeBankCard,
        },
    },
    TaskId:     1001,    // int64
    ProviderId: 123456789, // int64
})
// resp.SuccessNum, resp.FailureNum, resp.PayResultList
// Note: Synchronous response only confirms receipt

Batch Payment Query (FunCode: 6002)

resp, err := paymentService.PaymentQuery(&payments.PaymentQueryRequest{
    MerBatchId: "BATCH_001",
    // Omit QueryItems to get all orders
})
// resp.QueryItems[].State: 1=processing, 3=success, 4=failed, 6=pending, 7=cancelled

Handling Notifications

The SDK provides helpers to handle asynchronous callbacks from the platform.

Contract Signing Notification (FunCode: 6010/5.1.4)
// In your HTTP handler
body, _ := io.ReadAll(r.Body)
callback, err := freelancerService.ParseSignContractCallback(body)
if err != nil {
    // Handle error
    return
}
fmt.Printf("Sign Result: Name=%s State=%d\n", callback.Name, callback.State)
Batch Payment Notification (FunCode: 6001/5.3.4)
// In your HTTP handler
body, _ := io.ReadAll(r.Body)
callback, err := paymentService.ParsePaymentCallback(body)
if err != nil {
    // Handle error
    return
}
fmt.Printf("Batch Payment: BatchID=%s Items=%d\n", callback.MerBatchId, len(callback.QueryItems))

Error Handling

resp, err := accountService.BalanceQuery(req)
if err != nil {
    if apiErr, ok := err.(*cores.APIError); ok {
        // API error with Code and Message
        log.Printf("API Error [%s]: %s", apiErr.Code, apiErr.Message)
    }
    return err
}

Common Error Codes: 0000 (Success), 6001 (Parameter error), 6003 (Not found), 6006 (Signature failed), 6007 (Decryption failed), 6019 (Insufficient balance)

Security Best Practices

  • Never hardcode keys - Use environment variables or secret management services
  • Use HTTPS in production - Test environment uses HTTP, production must use HTTPS
  • Separate credentials - Keep test and production keys separate
  • Secure key storage - Use proper file permissions (0600) for key files
// Load from environment variables
config := cores.NewConfig(
    vos.EnvString("SS_API_URL"),            // BaseURL
    vos.EnvString("SS_MERCHANT_ID"),         // MerchantID
    vos.EnvString("SS_DES_KEY"),             // DesKey
    vos.EnvString("SS_PRIVATE_KEY"),         // PrivateKey
    vos.EnvString("SS_PLATFORM_PUBLIC_KEY"), // PlatformPublicKey
    vos.EnvInt64("SS_TASK_ID"),              // TaskID
)

Architecture

vservicesharesdk/
├── cores/          # Core SDK functionality
│   ├── client.go   # HTTP client with encryption/signing
│   ├── crypto.go   # DES encryption/decryption
│   ├── sign.go     # RSA signing/verification
│   ├── consts.go   # Constants (PaymentType, etc.)
│   └── errors.go   # Error types
├── accounts/       # Account service APIs (balance query)
├── freelancers/    # Freelancer APIs (signing, contract query, face auth)
├── payments/       # Payment APIs (batch payment, query)
└── examples/       # Usage examples with common helper
Request Flow
  1. Marshal request data to JSON
  2. Encrypt JSON with DES
  3. Sign encrypted data with RSA private key
  4. Send HTTP POST with encrypted + signed payload
  5. Verify response signature with platform public key
  6. Decrypt response data with DES
  7. Return typed response

Testing

For testing, you can use the demo credentials from: https://gitee.com/bubibi1/bosskg-demo

Contributing

Contributions are welcome! Please ensure:

  • Code follows Go conventions and best practices
  • All tests pass
  • Documentation is updated
  • Commits are clear and descriptive

License

Apache License 2.0

Support

For API documentation and support:

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.