Advanced Topics

This guide covers advanced features of the Retorna SDK for Java.

Advanced Configuration

Custom Base URL

If you need to use a different base URL:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.DEVELOP)
        .baseUrl("https://api-custom.retorna.com")
        // ... other configuration
        .build()
);

Initial Token

If you already have a valid token:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .initialAccessToken("your-existing-token")
        // ... other configuration
        .build()
);

Thread Safety

The RetornaClient is thread-safe. You can share it across multiple threads:

public class ThreadSafeService {
    private static final RetornaClient client = RetornaClient.create(
        RetornaClientOptions.builder()
            // ... configuration
            .build()
    );
    
    public void processInParallel() {
        ExecutorService executor = Executors.newFixedThreadPool(10);
        
        for (int i = 0; i < 100; i++) {
            executor.submit(() -> {
                try {
                    BalanceResponse balance = client.account.getBalance();
                    // Process balance
                } catch (Exception e) {
                    // Handle error
                }
            });
        }
    }
}

Advanced Logging

The SDK includes a structured logging system:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .loggingLevel(LoggingLevel.DEBUG)
        // ... other configuration
        .build()
);

// Logger is available
SdkLogger logger = client.getLogger();
logger.debug("Debug message");
logger.info("Info message");
logger.warn("Warning");
logger.error("Error");

Country Validation

The SDK automatically validates according to the platform:

• Argentina: Validates CUIT, CBU
• Colombia: Validates ID, bank account
• Peru: Validates DNI, interbank account
• Spain: Validates NIE/NIF, IBAN
• USA: Validates SSN, bank account
• Venezuela: Validates ID, bank account

Advanced Error Handling

The SDK categorizes errors:

try {
    OrderResponse order = client.order.createPayoutOrder(input);
} catch (RuntimeException e) {
    // SDK can provide structured error information
    // RetornaErrorReport errorReport = parseError(e);
    // RetornaErrorCategory category = errorReport.getCategory();
}

Best Practices

1. Reuse the client: Create one instance and reuse it
2. Error handling: Always handle exceptions appropriately
3. Logging: Use appropriate logging levels
4. Validation: Validate data before sending it
5. Thread safety: The client is thread-safe, use it in parallel