YOP Open Platform Java SDK

https://github.com/yop-platform/yop-java-sdk
Admin
YOP Open Platform Java SDK is a convenient, secure, and reliable toolkit designed to help Java...
Tokens:39,375
Snippets:455
Trust Score:7.2
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### YopCallbackResponse Usage Examples

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Callbacks.md

Examples demonstrating how to create success and failure responses for callback processing.

```java
// Success response
YopCallbackResponse success = YopCallbackResponse.success();
// Returns HTTP 200 with code=0, message="OK"

// Failure response
YopCallbackResponse failure = YopCallbackResponse.fail("Business rule violation");
// Returns HTTP 200 with code=1, message="Business rule violation"
```

--------------------------------

### Example MissingConfigException Output

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/errors.md

Sample error message format for a missing configuration file.

```text
MissingConfigException: 
  config file [file:///config/yop_sdk_config_default.json] not found
```

--------------------------------

### Minimal Development Configuration

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/configuration.md

A basic configuration example using a string-based private key for development.

```json
{
  "app_key": "app_10085525305",
  "isv_private_key": {
    "value": "-----BEGIN PRIVATE KEY-----\n...-----END PRIVATE KEY-----",
    "store_type": "STRING"
  }
}
```

--------------------------------

### Execute GET Standard Request with YOP SDK

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/llms.txt

Demonstrates a GET request implementation wrapped in a method with exception handling. Includes commented-out sections for manual credential configuration.

```java
private static void getCommonExample() {
        try {
            // Create request object
            YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
            request.addParameter("string0", "dsbzb");

            // Set application information
            String appKey = "app_10085525305"; // Replace with your application AppKey
            request.getRequestConfig().setAppKey(appKey);
            request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

            // Set authentication information
//            request.getRequestConfig().setCredentials(new YopPKICredentials(
//                    appKey, new PKICredentialsItem(getPrivateKey(
//                    "YOUR_PRIVATE_KEY_STRING", // Replace with your private key
//                    CertTypeEnum.RSA2048),
//                    CertTypeEnum.RSA2048)));

            // Send request
            YopClient yopClient = YopClientBuilder.builder().build();
            YopResponse response = yopClient.request(request);

            // Process response
            if (response != null && response.getResult() != null) {
                LOGGER.info("API call successful: {}", response.getResult());
                // Parse response.getResult() according to API documentation
            } else {
                LOGGER.warn("API call failed: {}", response.getResult());
            }
        } catch (Exception e) {
            LOGGER.error("API call exception", e);
        }
    }
```

--------------------------------

### Initialize GET Request with YOP SDK

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/llms.txt

Standard implementation for a GET request using the YOP SDK. Configures the request with an endpoint, app key, and security requirements before execution.

```Java
YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
request.addParameter("string0", "dsbzb");

// 设置应用信息
String appKey = "app_10085525305"; // 替换为您的应用AppKey
request.getRequestConfig().setAppKey(appKey);
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

// 发送请求
YopClient yopClient = YopClientBuilder.builder().build();
YopResponse response = yopClient.request(request);

// 处理响应
if (response != null && response.getResult() != null) {
    LOGGER.info("API调用成功: {}", response.getResult());
    // 根据API文档解析 response.getResult()
} else {
    LOGGER.warn("API调用失败: {}", response.getResult());
}
```

--------------------------------

### Configure YOP SDK

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/llms.txt

Example configuration file for the YOP SDK, typically placed at config/yop_sdk_config_default.json.

```json
{
  "app_key": "YOUR_APP_KEY", // Replace with your application AppKey
  "isv_private_key": { // Application private key configuration
    "value": "YOUR_PRIVATE_KEY_STRING" // Replace with your application private key string
  },
  "yos_server_root": "https://yos.yeepay.com/yop-center", // YOP service address
  "preferred_server_roots": [
    "https://openapi.yeepay.com/yop-center"
  ],
  "yop_cert_store": {
    "enable": false,
    "valid_after_expire_period": 1674727773000
  },
  "yop_report": {
    "enable": true,
    "enable_success_report": true,
    "send_interval_ms": 3000,
    "stat_interval_ms": 5000,
    "max_queue_size": 500,
    "max_fail_count": 10,
    "max_fail_count_per_exception": 5,
    "max_elapsed_ms": 15000,
    "max_packet_size": 50
  },
  "http_client": {
    "connect_timeout": 10000, // Connection timeout (milliseconds)
    "connect_request_timeout": 5000,
    "read_timeout": 30000 // Read timeout (milliseconds)
  }
}
```

--------------------------------

### Complete SDK Configuration JSON Structure

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/configuration.md

A full example of the JSON configuration file including credentials, server roots, reporting, and HTTP client settings.

```json
{
  "app_key": "app_10085525305",
  "isv_private_key": {
    "value": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBA...[base64 encoded key]...\n-----END PRIVATE KEY-----",
    "store_type": "STRING"
  },
  "isv_public_key": {
    "value": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG...[base64 encoded key]...\n-----END PUBLIC KEY-----",
    "store_type": "STRING"
  },
  "yos_server_root": "https://yos.yeepay.com/yop-center",
  "preferred_server_roots": [
    "https://openapi.yeepay.com/yop-center,100",
    "https://openapi-a.yeepay.com/yop-center,50",
    "https://openapi-h.yeepay.com/yop-center,50"
  ],
  "yop_cert_store": {
    "enable": true,
    "valid_after_expire_period": 86400000
  },
  "yop_report": {
    "enable": true,
    "enable_success_report": false,
    "send_interval_ms": 3000,
    "stat_interval_ms": 5000,
    "max_queue_size": 500,
    "max_fail_count": 10,
    "max_fail_count_per_exception": 5,
    "max_elapsed_ms": 15000,
    "max_packet_size": 50
  },
  "http_client": {
    "connect_timeout": 10000,
    "connect_request_timeout": 5000,
    "read_timeout": 30000,
    "max_idle_time": 60000,
    "max_conn_per_route": 20,
    "max_conn_total": 100
  }
}
```

--------------------------------

### Download File with YosDownloadResponse

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/FileOperations.md

Initializes a YopClient and executes a GET request to download a file from YOS.

```java
YopClient yopClient = YopClientBuilder.builder().build();

YopRequest request = new YopRequest("/yos/v1.0/test/test/ceph-download", "GET");
request.addParameter("fileName", "example.txt");
request.getRequestConfig().setAppKey("app_10085525305");
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

YosDownloadResponse response = yopClient.download(request);
```

--------------------------------

### Configure serverRoot for YopRequestConfig

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequestConfig.md

Methods for getting and setting the service root URL, with an example of overriding the global configuration.

```java
public String getServerRoot()
public YopRequestConfig setServerRoot(String serverRoot)
```

```java
request.getRequestConfig().setServerRoot("https://sandbox.yeepay.com/yop-center");
```

--------------------------------

### Execute API Request with YopClient

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/README.md

Initialize the YopClient and perform a GET request to the YOP platform.

```java
import com.yeepay.yop.sdk.service.common.YopClient;
import com.yeepay.yop.sdk.service.common.YopClientBuilder;
import com.yeepay.yop.sdk.service.common.request.YopRequest;
import com.yeepay.yop.sdk.service.common.response.YopResponse;

// Create client (loads config from classpath)
YopClient yopClient = YopClientBuilder.builder().build();

// Build request
YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
request.addParameter("string0", "value123");
request.getRequestConfig().setAppKey("app_10085525305");
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

// Execute request
try {
    YopResponse response = yopClient.request(request);
    Object result = response.getResult();
    String requestId = response.getMetadata().getRequestId();
    System.out.println("Request ID: " + requestId);
    System.out.println("Result: " + result);
} catch (YopServiceException e) {
    System.err.println("Error: " + e.getErrorCode() + " - " + e.getErrorMessage());
} catch (YopClientException e) {
    System.err.println("Client error: " + e.getMessage());
}
```

--------------------------------

### Production Configuration

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/configuration.md

A comprehensive configuration example for high-availability production environments, including server roots, certificate store, reporting, and HTTP client settings.

```json
{
  "app_key": "app_10085525305",
  "isv_private_key": {
    "value": "/etc/yop/private_key.pem",
    "store_type": "FILE"
  },
  "yos_server_root": "https://yos.yeepay.com/yop-center",
  "preferred_server_roots": [
    "https://openapi.yeepay.com/yop-center,100",
    "https://openapi-a.yeepay.com/yop-center,50",
    "https://openapi-h.yeepay.com/yop-center,50"
  ],
  "yop_cert_store": {
    "enable": true,
    "valid_after_expire_period": 86400000
  },
  "yop_report": {
    "enable": true,
    "enable_success_report": false,
    "send_interval_ms": 5000,
    "max_queue_size": 500
  },
  "http_client": {
    "connect_timeout": 15000,
    "connect_request_timeout": 10000,
    "read_timeout": 45000,
    "max_conn_per_route": 50,
    "max_conn_total": 200
  }
}
```

--------------------------------

### SM2 Credentials Configuration

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Example of how to configure SM2 credentials using a PEM private key string and apply them to a YopRequest.

```APIDOC
## SM2 Credentials

### Description
Configures credentials using an SM2 private key for secure request signing.

### Usage
```java
String appKey = "app_10085525305";
String pemPrivateKey = "-----BEGIN EC PRIVATE KEY-----\n...";

YopCertConfig certConfig = new YopCertConfig();
certConfig.setCertType(CertTypeEnum.SM2);
certConfig.setValue(pemPrivateKey);
certConfig.setStoreType(CertStoreType.STRING);

PrivateKey privateKey = (PrivateKey) YopCertParserFactory
    .getCertParser(YopCertCategory.PRIVATE, CertTypeEnum.SM2)
    .parse(certConfig);

YopPKICredentials credentials = new YopPKICredentials(
    appKey,
    new PKICredentialsItem(privateKey, CertTypeEnum.SM2)
);

YopRequest request = new YopRequest("/rest/v1.0/endpoint", "POST");
request.getRequestConfig().setCredentials(credentials);
request.getRequestConfig().setSecurityReq("YOP-SM2-SM3");
```
```

--------------------------------

### Access CertTypeEnum properties

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/types.md

Examples of retrieving metadata and parsing values from the CertTypeEnum.

```java
CertTypeEnum.RSA2048.getValue()           // "RSA2048"
CertTypeEnum.SM2.getDisplayName()         // "SM2算法，密钥长度256"
CertTypeEnum.SM4.isSymmetric()            // true
CertTypeEnum.parse("RSA2048")             // CertTypeEnum.RSA2048
```

--------------------------------

### Download a file using YOP Java SDK

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/README.md

Shows the process of creating a GET request for file retrieval and handling the resulting input stream.

```java
private static void fileDownloadExample() {
        YosDownloadInputStream downloadInputStream = null;
        try {
            // Create request object
            YopRequest request = new YopRequest("/yos/v1.0/test/test/ceph-download", "GET");
            request.addParameter("fileName", "example.txt");

            // Set application information
            String appKey = "app_10085525305"; // Replace with your application AppKey
            request.getRequestConfig().setAppKey(appKey);
            request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

            // Set authentication information
//            request.getRequestConfig().setCredentials(new YopPKICredentials(
//                    appKey, new PKICredentialsItem(getPrivateKey(
//                    "YOUR_PRIVATE_KEY_STRING", // Replace with your private key
//                    CertTypeEnum.RSA2048),
//                    CertTypeEnum.RSA2048)));

            // Send request
            YopClient yopClient = YopClientBuilder.builder().build();
            YosDownloadResponse response = yopClient.download(request);

            // Process response
            if (response != null && response.getResult() != null) {
                downloadInputStream = response.getResult();
                // Read downloaded file content
                String fileContent = IOUtils.toString(downloadInputStream, "UTF-8");
                LOGGER.info("File download successful, content length: {}", fileContent.length());

                // In actual use, you can save the file content to a local file
                // Files.write(Paths.get("downloaded-file.txt"), fileContent.getBytes());
            } else {
                LOGGER.warn("File download failed: {}", response.getResult());
            }
        } catch (Exception e) {
            LOGGER.error("File download exception", e);
        } finally {
            // Close stream
            StreamUtils.closeQuietly(downloadInputStream);
        }
    }
```

--------------------------------

### RSA-2048 Credentials Configuration

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Example of how to configure RSA-2048 credentials using a PEM private key string and apply them to a YopRequest.

```APIDOC
## RSA-2048 Credentials

### Description
Configures credentials using an RSA-2048 private key for secure request signing.

### Usage
```java
String appKey = "app_10085525305";
String pemPrivateKey = "-----BEGIN PRIVATE KEY-----\n...";

YopCertConfig certConfig = new YopCertConfig();
certConfig.setCertType(CertTypeEnum.RSA2048);
certConfig.setValue(pemPrivateKey);
certConfig.setStoreType(CertStoreType.STRING);

PrivateKey privateKey = (PrivateKey) YopCertParserFactory
    .getCertParser(YopCertCategory.PRIVATE, CertTypeEnum.RSA2048)
    .parse(certConfig);

YopPKICredentials credentials = new YopPKICredentials(
    appKey,
    new PKICredentialsItem(privateKey, CertTypeEnum.RSA2048)
);

YopRequest request = new YopRequest("/rest/v1.0/endpoint", "POST");
request.getRequestConfig().setCredentials(credentials);
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");
```
```

--------------------------------

### Execute API Requests

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/README.md

Demonstration of various API request types including GET, POST, and file operations using the YopClient.

```java
import com.yeepay.yop.sdk.auth.credentials.PKICredentialsItem;
import com.yeepay.yop.sdk.auth.credentials.YopPKICredentials;
import com.yeepay.yop.sdk.config.enums.CertStoreType;
import com.yeepay.yop.sdk.base.security.cert.parser.YopCertParserFactory;
import com.yeepay.yop.sdk.security.CertTypeEnum;
import com.yeepay.yop.sdk.security.cert.YopCertCategory;
import com.yeepay.yop.sdk.service.common.YopClient;
import com.yeepay.yop.sdk.service.common.YopClientBuilder;
import com.yeepay.yop.sdk.service.common.request.YopRequest;
import com.yeepay.yop.sdk.service.common.response.YopResponse;
import com.yeepay.yop.sdk.model.yos.YosDownloadResponse;
import com.yeepay.yop.sdk.model.yos.YosDownloadInputStream;
import com.yeepay.yop.sdk.service.common.response.YosUploadResponse;
import com.yeepay.yop.sdk.config.provider.file.YopCertConfig;
import com.yeepay.yop.sdk.utils.JsonUtils;
import com.yeepay.yop.sdk.utils.StreamUtils;
import org.apache.commons.io.IOUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.InputStream;
import java.security.PrivateKey;
import java.util.Map;
import java.util.HashMap;

public class YopApiDemo {
    private static final Logger LOGGER = LoggerFactory.getLogger(YopApiDemo.class);

    public static void main(String[] args) {
        // Example 1: GET Standard Request
        getCommonExample();

        // Example 2: POST Form Request
        postFormExample();

        // Example 3: POST JSON Format Request
        postJsonExample();

        // Example 4: File Upload
        fileUploadExample();

        // Example 5: File Download
        fileDownloadExample();
    }

    /**
     * GET Standard Request Example
     */
    private static void getCommonExample() {
        try {
            // Create request object
            YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
            request.addParameter("string0", "dsbzb");

            // Set application information
            String appKey = "app_10085525305"; // Replace with your application AppKey
            request.getRequestConfig().setAppKey(appKey);
            request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");
```

--------------------------------

### Basic YopClient instantiation

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Demonstrates creating a client with specific endpoint and environment settings followed by a request execution.

```java
YopClient client = YopClientBuilder.builder()
    .withEndpoint("https://openapi.yeepay.com/yop-center")
    .withEnv("prod")
    .build();

// Use client
YopRequest request = new YopRequest("/rest/v1.0/endpoint", "GET");
YopResponse response = client.request(request);
```

--------------------------------

### Initialize and execute a YOP request

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/DOCUMENTATION_INDEX.md

Illustrates the workflow for building a client, configuring a request, and executing it to receive a response.

```text
YopClientBuilder.builder()          ← Create and configure
    .build()                         ↓
YopClient                           ← Main interface
    .request(YopRequest)            ← Takes request
YopRequest                          ← Build with parameters
    + YopRequestConfig              ← Add configuration
    ↓
YopClient.request()                 ← Execute
    ↓
YopResponse                         ← Get results
```

--------------------------------

### Get HTTP Method

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Retrieves the HTTP method for the request.

```java
public String getHttpMethod()
```

--------------------------------

### Get API URI

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Retrieves the API endpoint path.

```java
public String getApiUri()
```

--------------------------------

### Configure sandbox client

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Sets up a client specifically for the sandbox environment.

```java
YopClient sandboxClient = YopClientBuilder.builder()
    .withEndpoint("https://sandbox.yeepay.com/yop-center")
    .withEnv("sandbox")
    .build();
```

--------------------------------

### GET /yos/v1.0/files/download

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/FileOperations.md

Downloads a file from the server using a file ID.

```APIDOC
## GET /yos/v1.0/files/download

### Description
Downloads a file from the YOS service using the specified file ID.

### Method
GET

### Endpoint
/yos/v1.0/files/download

### Parameters
#### Query Parameters
- **fileId** (string) - Required - The unique identifier of the file to download.
```

--------------------------------

### Get Content

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Retrieves the request body content, typically as a String or InputStream.

```java
public Object getContent()
```

--------------------------------

### Execute Basic Request-Response Pattern

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopResponse.md

Demonstrates initializing a YopClient, constructing a YopRequest, and handling the resulting YopResponse or exceptions.

```java
import com.yeepay.yop.sdk.service.common.YopClient;
import com.yeepay.yop.sdk.service.common.YopClientBuilder;
import com.yeepay.yop.sdk.service.common.request.YopRequest;
import com.yeepay.yop.sdk.service.common.response.YopResponse;

YopClient yopClient = YopClientBuilder.builder().build();

YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
request.addParameter("productId", "12345");
request.getRequestConfig().setAppKey("app_10085525305");
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

try {
    YopResponse response = yopClient.request(request);
    
    if (response != null) {
        Object result = response.getResult();
        String requestId = response.getMetadata().getRequestId();
        
        System.out.println("Request ID: " + requestId);
        System.out.println("Result: " + result);
    }
} catch (YopServiceException e) {
    // Handle service-level errors
    System.err.println("Error Code: " + e.getErrorCode());
    System.err.println("Error Message: " + e.getErrorMessage());
    System.err.println("Request ID: " + e.getRequestId());
} catch (YopClientException e) {
    // Handle client-side or network errors
    System.err.println("Client Error: " + e.getMessage());
}
```

--------------------------------

### Configure SDK via JVM System Properties

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/configuration.md

Pass configuration parameters to the application at runtime using the -D flag.

```bash
java -Dyop.sdk.config.file=file:///etc/yop/config.json \
     -Dyop.sdk.debug=true \
     -jar application.jar
```

--------------------------------

### Get Parameters

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Retrieves query or form-encoded body parameters as a Guava Multimap.

```java
public Multimap<String, String> getParameters()
```

--------------------------------

### Read Byte Array with Offset

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/FileOperations.md

Reads up to len bytes starting at offset off.

```java
public int read(byte[] b, int off, int len) throws IOException
```

--------------------------------

### build()

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Finalizes the configuration and returns a fully initialized YopClient instance.

```APIDOC
## public YopClient build()

### Description
Processes the current builder configuration, including credentials, endpoints, and HTTP settings, to return a ready-to-use YopClient.

### Signature
`public YopClient build()`

### Returns
- **YopClient** - An instance configured for API calls.
```

--------------------------------

### Initialize YopPKICredentials

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Instantiate credentials with an application key and a PKICredentialsItem, then assign them to the request configuration.

```java
PrivateKey privateKey = // ... load or parse private key
YopPKICredentials credentials = new YopPKICredentials(
    "app_10085525305",
    new PKICredentialsItem(privateKey, CertTypeEnum.RSA2048)
);
request.getRequestConfig().setCredentials(credentials);
```

--------------------------------

### Configure Multi-Environment Clients

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/README.md

Initialize separate YopClient instances for production and sandbox environments using the YopClientBuilder.

```java
YopClient prodClient = YopClientBuilder.builder()
    .withEnv("prod")
    .build();

YopClient sandboxClient = YopClientBuilder.builder()
    .withEnv("sandbox")
    .withEndpoint("https://sandbox.yeepay.com/yop-center")
    .build();
```

--------------------------------

### Get Multipart Files

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Retrieves files configured for multipart form data upload.

```java
public Multimap<String, Object> getMultipartFiles()
```

--------------------------------

### YopClient Instantiation

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClient.md

How to initialize a new YopClient instance using the builder pattern.

```APIDOC
## YopClient Instantiation

### Description
Creates a new instance of the YopClient for interacting with YOP services. The client automatically loads configuration from the default SDK path or a path specified by the JVM parameter -Dyop.sdk.config.file.

### Usage
```java
YopClient yopClient = YopClientBuilder.builder().build();
```
```

--------------------------------

### Initialize YopRequest with URI and Method

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Creates a basic request instance using the target API path and HTTP method.

```java
public YopRequest(String apiUri, String httpMethod)
```

```java
YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
```

--------------------------------

### Manual Key Loading from File

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Programmatically parse a private key from a file path using YopCertConfig.

```java
YopCertConfig certConfig = new YopCertConfig();
certConfig.setCertType(CertTypeEnum.RSA2048);
certConfig.setValue("/path/to/private_key.pem");
certConfig.setStoreType(CertStoreType.FILE);

PrivateKey privateKey = (PrivateKey) YopCertParserFactory
    .getCertParser(YopCertCategory.PRIVATE, CertTypeEnum.RSA2048)
    .parse(certConfig);
```

--------------------------------

### Initialize PKICredentialsItem with Private Key

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Create a credential item using a private key and the specified certificate algorithm type.

```java
PKICredentialsItem item = new PKICredentialsItem(privateKey, CertTypeEnum.RSA2048);
```

--------------------------------

### Process Upload Result

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/FileOperations.md

Example of casting the generic result object to a Map to extract specific upload information.

```java
YosUploadResponse response = yopClient.upload(request);
Object result = response.getResult();

if (result instanceof Map) {
    Map<String, Object> uploadInfo = (Map<String, Object>) result;
    String fileHandle = (String) uploadInfo.get("fileHandle");
    String storageUrl = (String) uploadInfo.get("storageUrl");
}
```

--------------------------------

### Initialize YopCallbackRequest

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Callbacks.md

Constructor for creating a new YopCallbackRequest instance with the specified HTTP path and method.

```java
public YopCallbackRequest(String httpPath, String httpMethod)
```

--------------------------------

### Initialize YopRequest with Configuration

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Creates a request instance that includes specific YopRequestConfig settings such as app keys and security requirements.

```java
public YopRequest(String apiUri, String httpMethod, YopRequestConfig requestConfig)
```

```java
YopRequestConfig config = new YopRequestConfig();
config.setAppKey("app_10085525305");
config.setSecurityReq("YOP-RSA2048-SHA256");

YopRequest request = new YopRequest("/rest/v1.0/endpoint", "POST", config);
```

--------------------------------

### YopClientBuilder.builder()

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Initializes a new builder instance to configure and create a YopClient.

```APIDOC
## YopClientBuilder.builder()

### Description
Creates a new instance of YopClientBuilder to begin the configuration process for a YopClient.

### Usage
```java
YopClient yopClient = YopClientBuilder.builder().build();
```

### Returns
- **YopClientBuilder** - A builder instance configured with default settings from the classpath.
```

--------------------------------

### YopCallbackRequest Constructor

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Callbacks.md

Initializes a new instance of the YopCallbackRequest with the specified HTTP path and method.

```APIDOC
## YopCallbackRequest(String httpPath, String httpMethod)

### Description
Creates a new YopCallbackRequest object to represent an incoming callback.

### Parameters
- **httpPath** (String) - Required - HTTP endpoint path (e.g., /callback).
- **httpMethod** (String) - Required - HTTP method (e.g., POST).
```

--------------------------------

### Initialize YopClientBuilder

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Shows the static factory method to obtain a new builder instance.

```java
public static YopClientBuilder builder()
```

```java
YopClient client = YopClientBuilder.builder().build();
```

--------------------------------

### Adding a Multipart File to a Request

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/FileOperations.md

Demonstrates how to initialize an InputStream from a file and attach it to a request using the SDK.

```java
InputStream stream = Files.newInputStream(Paths.get("document.pdf"));
request.addMultiPartFile("_file", stream, "pdf");
// Internally wrapped as FileParam(stream, "pdf")
```

--------------------------------

### Implement multi-environment client factory

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Encapsulates client creation for different environments within a static factory class.

```java
public class YopClientFactory {
    
    private static final YopClient PROD_CLIENT;
    private static final YopClient SANDBOX_CLIENT;
    
    static {
        PROD_CLIENT = YopClientBuilder.builder()
            .withEnv("prod")
            .build();
        
        SANDBOX_CLIENT = YopClientBuilder.builder()
            .withEndpoint("https://sandbox.yeepay.com/yop-center")
            .withEnv("sandbox")
            .build();
    }
    
    public static YopClient getClient(Environment env) {
        return Environment.PROD == env ? PROD_CLIENT : SANDBOX_CLIENT;
    }
}
```

--------------------------------

### withEnv(String env)

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Sets the service environment.

```APIDOC
## withEnv(String env)

### Description
Set the service environment.

### Parameters
- **env** (String) - Optional - Environment (e.g., "prod", "sandbox", "qa").
```

--------------------------------

### Configuration Inheritance and Overrides

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Shows different methods for setting the endpoint, illustrating builder parameters, config files, and request-level overrides.

```java
// These are equivalent:

// Option 1: Via builder
YopClient client1 = YopClientBuilder.builder()
    .withEndpoint("https://sandbox.yeepay.com/yop-center")
    .build();

// Option 2: Via config file (if yop_sdk_config.json contains "server_root")
YopClient client2 = YopClientBuilder.builder().build();

// Option 3: Via request-level override
YopRequest request = new YopRequest("/rest/v1.0/endpoint", "GET");
request.getRequestConfig().setServerRoot("https://sandbox.yeepay.com/yop-center");
```

--------------------------------

### Configuration File Key Format

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

JSON structure for defining private keys within the SDK configuration file.

```json
{
  "app_key": "app_10085525305",
  "isv_private_key": {
    "value": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBA...\n-----END PRIVATE KEY-----",
    "store_type": "STRING"
  }
}
```

--------------------------------

### Build a YopClient instance

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Defines the build method signature for creating a configured client.

```java
public YopClient build()
```

--------------------------------

### Instantiate YopClient

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClient.md

Creates a new YopClient instance using the default SDK configuration settings.

```java
YopClient yopClient = YopClientBuilder.builder().build();
```

--------------------------------

### Configure production client with custom credentials

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Configures a client using a custom YopCachedCredentialsProvider for production environments.

```java
import com.yeepay.yop.sdk.base.auth.credentials.provider.YopCachedCredentialsProvider;
import com.yeepay.yop.sdk.service.common.YopClientBuilder;
import com.yeepay.yop.sdk.service.common.YopClient;
import java.util.concurrent.TimeUnit;

// Custom credentials provider
YopCachedCredentialsProvider credentialsProvider = 
    new YopCachedCredentialsProvider(24, TimeUnit.HOURS) {
    
    @Override
    protected YopAppConfig loadAppConfig(String appKey) {
        // Load merchant credentials from database
        return DatabaseCredentialsRepository.getConfig(appKey);
    }
};

// Build client with custom configuration
YopClient client = YopClientBuilder.builder()
    .withCredentialsProvider(credentialsProvider)
    .withEndpoint("https://openapi.yeepay.com/yop-center")
    .withEnv("prod")
    .build();
```

--------------------------------

### Initialize YopRequestConfig using the Builder Pattern

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequestConfig.md

Constructs a fully configured YopRequestConfig instance using the fluent builder API.

```java
YopRequestConfig config = YopRequestConfig.Builder.builder()
    .withAppKey("app_10085525305")
    .withSecurityReq("YOP-RSA2048-SHA256")
    .withReadTimeout(30000)
    .withConnectTimeout(10000)
    .withNeedEncrypt(true)
    .withEncryptAlg("SM4/CBC/PKCS5Padding")
    .withSkipVerifySign(false)
    .withServerRoot("https://openapi.yeepay.com/yop-center")
    .withEnableCircuitBreaker(true)
    .build();

YopRequest request = new YopRequest("/rest/v1.0/endpoint", "POST", config);
```

--------------------------------

### Manual Key Loading from String

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Programmatically parse a private key from a PEM string and initialize YopPKICredentials.

```java
import com.yeepay.yop.sdk.base.security.cert.parser.YopCertParserFactory;
import com.yeepay.yop.sdk.config.provider.file.YopCertConfig;
import com.yeepay.yop.sdk.config.enums.CertStoreType;

String pemPrivateKey = "-----BEGIN PRIVATE KEY-----\n...";
YopCertConfig certConfig = new YopCertConfig();
certConfig.setCertType(CertTypeEnum.RSA2048);
certConfig.setValue(pemPrivateKey);
certConfig.setStoreType(CertStoreType.STRING);

PrivateKey privateKey = (PrivateKey) YopCertParserFactory
    .getCertParser(YopCertCategory.PRIVATE, CertTypeEnum.RSA2048)
    .parse(certConfig);

YopPKICredentials credentials = new YopPKICredentials(
    "app_10085525305",
    new PKICredentialsItem(privateKey, CertTypeEnum.RSA2048)
);
```

--------------------------------

### Implement and use YopFixedCredentialsProvider

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Demonstrates extending the fixed provider and registering it with the YopClientBuilder.

```java
YopFixedCredentialsProvider provider = new YopFixedCredentialsProvider() {
    @Override
    protected YopAppConfig loadAppConfig(String appKey) {
        // Custom logic to load and return credentials
        return null;
    }
};

YopClientBuilder builder = YopClientBuilder.builder()
    .withCredentialsProvider(provider);
```

--------------------------------

### Configure RSA-2048 Credentials

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Initializes credentials using an RSA-2048 private key string and configures the request security requirements.

```java
String appKey = "app_10085525305";
String pemPrivateKey = "-----BEGIN PRIVATE KEY-----\n...";

YopCertConfig certConfig = new YopCertConfig();
certConfig.setCertType(CertTypeEnum.RSA2048);
certConfig.setValue(pemPrivateKey);
certConfig.setStoreType(CertStoreType.STRING);

PrivateKey privateKey = (PrivateKey) YopCertParserFactory
    .getCertParser(YopCertCategory.PRIVATE, CertTypeEnum.RSA2048)
    .parse(certConfig);

YopPKICredentials credentials = new YopPKICredentials(
    appKey,
    new PKICredentialsItem(privateKey, CertTypeEnum.RSA2048)
);

YopRequest request = new YopRequest("/rest/v1.0/endpoint", "POST");
request.getRequestConfig().setCredentials(credentials);
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");
```

--------------------------------

### YopCallbackEngine.handle()

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Callbacks.md

Completes callback processing by decrypting, validating, invoking business logic, and signing the response.

```APIDOC
## YopCallbackEngine.handle(YopCallbackRequest request)

### Description
Complete callback processing: decrypt, validate, invoke business handler, and sign response.

### Parameters
- **request** (YopCallbackRequest) - Required - The incoming callback request.

### Returns
- **YopCallbackResponse** - The signed response object.

### Example
```java
YopCallbackRequest callbackRequest = convertServletRequest(httpRequest);
YopCallbackResponse response = YopCallbackEngine.handle(callbackRequest);
```
```

--------------------------------

### Configure Sandbox Environment

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/configuration.md

Set the sandbox endpoint via configuration file or override it per-request in Java.

```json
{
  "preferred_server_roots": ["https://sandbox.yeepay.com/yop-center"]
}
```

```java
request.getRequestConfig().setServerRoot("https://sandbox.yeepay.com/yop-center");
```

--------------------------------

### YopCallbackEngine.handle(YopCallbackRequest request)

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Callbacks.md

Processes an incoming callback request using the YopCallbackEngine.

```APIDOC
## public static YopCallbackResponse handle(YopCallbackRequest request)

### Description
Processes the provided callback request and returns a response.

### Parameters
- **request** (YopCallbackRequest) - Required - The callback request object containing headers, content, and metadata.

### Response
- **YopCallbackResponse** - The response object containing the processed content.
```

--------------------------------

### Execute Basic API Request

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/README.md

Demonstrates the standard flow for sending a request and processing the response using YopClient.

```java
//            request.getRequestConfig().setCredentials(new YopPKICredentials(
//                    appKey, new PKICredentialsItem(getPrivateKey(
//                    "YOUR_PRIVATE_KEY_STRING", // Replace with your private key
//                    CertTypeEnum.RSA2048),
//                    CertTypeEnum.RSA2048)));

            // Send request
            YopClient yopClient = YopClientBuilder.builder().build();
            YopResponse response = yopClient.request(request);

            // Process response
            if (response != null && response.getResult() != null) {
                LOGGER.info("API call successful: {}", response.getResult());
                // Parse response.getResult() according to API documentation
            } else {
                LOGGER.warn("API call failed: {}", response.getResult());
            }
        } catch (Exception e) {
            LOGGER.error("API call exception", e);
        }
    }
```

--------------------------------

### View Configuration Exception Hierarchy

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/errors.md

Visual representation of the inheritance structure for SDK configuration exceptions.

```text
java.lang.RuntimeException
└── AbstractSDKConfigException
    ├── AbstractIllegalConfigException
    │   ├── IllegalConfigFormatException
    │   ├── IllegalConfigLengthException
    │   └── IllegalConfigSizeException
    └── MissingConfigException
```

--------------------------------

### YopCallbackEngine.build()

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Callbacks.md

Constructs a YOP callback request from a YopRequest object, applying necessary signature and encryption.

```APIDOC
## YopCallbackEngine.build(YopRequest request)

### Description
Constructs a YOP callback request from a YopRequest, with signature and encryption applied.

### Parameters
- **request** (YopRequest) - Required - The YOP request object with populated parameters.
- **provider** (String) - Optional - Service provider.
- **env** (String) - Optional - Service environment.

### Returns
- **YopCallbackRequest** - The constructed callback request object.

### Example
```java
YopRequest request = new YopRequest("/rest/v1.0/callback/send", "POST");
request.addParameter("tradeNo", "123456789");
request.getRequestConfig().setAppKey("app_10085525305");
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

YopCallbackRequest callbackRequest = YopCallbackEngine.build(request);
```
```

--------------------------------

### Configure SM2 Credentials

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Initializes credentials using an SM2 private key string and configures the request security requirements.

```java
String appKey = "app_10085525305";
String pemPrivateKey = "-----BEGIN EC PRIVATE KEY-----\n...";

YopCertConfig certConfig = new YopCertConfig();
certConfig.setCertType(CertTypeEnum.SM2);
certConfig.setValue(pemPrivateKey);
certConfig.setStoreType(CertStoreType.STRING);

PrivateKey privateKey = (PrivateKey) YopCertParserFactory
    .getCertParser(YopCertCategory.PRIVATE, CertTypeEnum.SM2)
    .parse(certConfig);

YopPKICredentials credentials = new YopPKICredentials(
    appKey,
    new PKICredentialsItem(privateKey, CertTypeEnum.SM2)
);

YopRequest request = new YopRequest("/rest/v1.0/endpoint", "POST");
request.getRequestConfig().setCredentials(credentials);
request.getRequestConfig().setSecurityReq("YOP-SM2-SM3");
```

--------------------------------

### Initialize YopRequestConfig

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequestConfig.md

Constructor for creating a new configuration object with default values.

```java
public YopRequestConfig()
```

--------------------------------

### Client Caching Behavior

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Demonstrates that identical configurations return the same cached YopClient instance.

```java
// First call creates and caches client
YopClient client1 = YopClientBuilder.builder()
    .withEndpoint("https://openapi.yeepay.com/yop-center")
    .build();

// Same configuration returns cached instance
YopClient client2 = YopClientBuilder.builder()
    .withEndpoint("https://openapi.yeepay.com/yop-center")
    .build();

assert client1 == client2;  // Same instance
```

--------------------------------

### Initialize POST Form Request with YOP SDK

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/llms.txt

Creates and sends a POST request with form data. Requires a YopRequest object configured with the API endpoint, method, app key, and security requirements.

```Java
YopRequest request = new YopRequest("/rest/v1.0/test-wdc/test/http-json", "POST");

// 设置应用信息
String appKey = "app_10085525305"; // 替换为您的应用AppKey
request.getRequestConfig().setAppKey(appKey);
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");

// 添加表单参数
request.addParameter("string", "你好");

// 发送请求
YopClient yopClient = YopClientBuilder.builder().build();
YopResponse response = yopClient.request(request);

// 处理响应
if (response != null && response.getResult() != null) {
    LOGGER.info("API调用成功: {}", response.getResult());
    // 根据API文档解析 response.getResult()
} else {
    LOGGER.warn("API调用失败: {}", response.getResult());
}
```

--------------------------------

### YopRequest(String apiUri, String httpMethod)

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequest.md

Constructor to initialize a request with a specific API endpoint and HTTP method.

```APIDOC
## YopRequest(String apiUri, String httpMethod)

### Description
Creates a new request instance with the specified API endpoint path and HTTP method.

### Parameters
- **apiUri** (String) - Required - The API endpoint path (e.g., /rest/v1.0/test/product-query/query-for-doc).
- **httpMethod** (String) - Required - The HTTP method (e.g., GET, POST, PUT, DELETE).

### Example
```java
YopRequest request = new YopRequest("/rest/v1.0/test/product-query/query-for-doc", "GET");
```
```

--------------------------------

### Configure Standard Public Request

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequestConfig.md

Initializes a request without encryption using standard security requirements.

```java
YopRequest request = new YopRequest("/rest/v1.0/endpoint", "GET");
request.getRequestConfig().setAppKey("app_10085525305");
request.getRequestConfig().setSecurityReq("YOP-RSA2048-SHA256");
```

--------------------------------

### Configure Connection Timeout

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopRequestConfig.md

Methods for setting the HTTP connection establishment timeout in milliseconds.

```java
public int getConnectTimeout()
public YopRequestConfig setConnectTimeout(int connectTimeout)
```

```java
request.getRequestConfig().setConnectTimeout(15000); // 15 seconds
```

--------------------------------

### Configure HTTP Client Settings

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/YopClientBuilder.md

Customize connection and read timeouts by passing a ClientConfiguration object to the builder.

```java
ClientConfiguration config = new ClientConfiguration();
config.setConnectTimeout(20000);
config.setReadTimeout(60000);

YopClient client = YopClientBuilder.builder()
    .withClientConfiguration(config)
    .build();
```

--------------------------------

### Implement and use YopCachedCredentialsProvider

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/api-reference/Credentials.md

Demonstrates extending the cached provider and registering it with the YopClientBuilder.

```java
YopCachedCredentialsProvider provider = new YopCachedCredentialsProvider(1, TimeUnit.HOURS) {
    @Override
    protected YopAppConfig loadAppConfig(String appKey) {
        // Custom logic to load app configuration from database, file, or API
        // Return YopAppConfig with credentials for the appKey
        return null;
    }
};

YopClientBuilder builder = YopClientBuilder.builder()
    .withCredentialsProvider(provider);
```

--------------------------------

### Configure YOP SDK Credentials

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/README.md

Define the SDK configuration in a JSON file located at src/main/resources/config/yop_sdk_config_default.json.

```json
{
  "app_key": "app_10085525305",
  "isv_private_key": {
    "value": "-----BEGIN PRIVATE KEY-----\n...your-private-key...\n-----END PRIVATE KEY-----",
    "store_type": "STRING"
  },
  "yos_server_root": "https://yos.yeepay.com/yop-center",
  "http_client": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  }
}
```

--------------------------------

### Override Configuration Location via JVM Parameter

Source: https://github.com/yop-platform/yop-java-sdk/blob/main/_autodocs/configuration.md

Use the -Dyop.sdk.config.file JVM parameter to specify a custom path for the SDK configuration file.

```bash
java -Dyop.sdk.config.file=file:///etc/yop/config.json -jar app.jar
```

```bash
java -Dyop.sdk.config.file=file:///D:/config/yop_sdk_config.json -jar app.jar
```
Tokens:
Raw