Java SDK

The Staqr Java SDK provides enterprise-grade Java support with OkHttp client and Gson serialization.

Installation

Maven

<!-- Staqr Platform API -->
<dependency>
    <groupId>com.staqr</groupId>
    <artifactId>staqr-api-client</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Commerce APIs -->
<dependency>
    <groupId>com.staqr</groupId>
    <artifactId>staqr-commerce-v1</artifactId>
    <version>13.3.0</version>
</dependency>

Gradle

// Staqr Platform API
implementation 'com.staqr:staqr-api-client:1.0.0'

// Commerce APIs
implementation 'com.staqr:staqr-commerce-v1:13.3.0'  // Recommended
implementation 'com.staqr:staqr-commerce-v2:13.3.0'  // Generic CRUD
implementation 'com.staqr:staqr-commerce-v0:13.3.0'  // Legacy

From Local SDK

<dependency>
    <groupId>com.staqr</groupId>
    <artifactId>staqr-api-client</artifactId>
    <version>1.0.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/sdks/staqr-java/target/staqr-api-client-1.0.0.jar</systemPath>
</dependency>

Quick Start

import com.staqr.client.ApiClient;
import com.staqr.client.Configuration;
import com.staqr.client.api.FlowsApi;
import com.staqr.client.model.Flow;

public class Example {
    public static void main(String[] args) throws Exception {
        // Configure the client
        ApiClient client = Configuration.getDefaultApiClient();
        client.setBasePath("https://my.staqr.com/api/v1");
        client.setAccessToken(System.getenv("STAQR_API_KEY"));
        client.addDefaultHeader("x-seller-id", System.getenv("STAQR_SELLER_ID"));

        // Create API instance
        FlowsApi flowsApi = new FlowsApi(client);

        // List flows
        List<Flow> flows = flowsApi.listFlows();
        flows.forEach(flow -> System.out.println("Flow: " + flow.getDisplayName()));
    }
}

Authentication

API Key Authentication

import com.staqr.client.ApiClient;
import com.staqr.client.Configuration;

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://my.staqr.com/api/v1");
client.setAccessToken(System.getenv("STAQR_API_KEY"));
client.addDefaultHeader("x-seller-id", System.getenv("STAQR_SELLER_ID"));

OAuth2 (Commerce APIs)

import com.staqr.commerce.ApiClient;

// For Commerce Direct access (Keycloak OAuth2)
ApiClient client = new ApiClient();
client.setBasePath("https://commerce.staqr.com/api");
client.setAccessToken(commerceOAuthToken);
client.addDefaultHeader("X-Tenant", "YOUR_TENANT_CODE");

Available Packages

Artifact ID	API	Maven Coordinates
staqr-api-client	Staqr Platform	com.staqr:staqr-api-client:1.0.0
staqr-commerce-v1	Commerce v1 (Structured)	com.staqr:staqr-commerce-v1:13.3.0
staqr-commerce-v2	Commerce v2 (Generic CRUD)	com.staqr:staqr-commerce-v2:13.3.0
staqr-commerce-v0	Commerce v0 (Legacy)	com.staqr:staqr-commerce-v0:13.3.0

Common Operations

Working with Customers (Commerce)

import com.staqr.commerce.api.CustomerManagementApi;
import com.staqr.commerce.model.CustomerDto;

CustomerManagementApi customerApi = new CustomerManagementApi(client);

// List customers
List<CustomerDto> customers = customerApi.listCustomers(null, null, null);

// Get customer by code
CustomerDto customer = customerApi.getCustomerByCode("CUST001");

// Create customer
CustomerDto newCustomer = new CustomerDto();
newCustomer.setCode("CUST002");
newCustomer.setDescription("New Customer");
customerApi.createCustomer(newCustomer);

Async Operations

import java.util.concurrent.CompletableFuture;

// Using CompletableFuture for async calls
CompletableFuture.supplyAsync(() -> {
    try {
        return customerApi.listCustomers(null, null, null);
    } catch (ApiException e) {
        throw new RuntimeException(e);
    }
}).thenAccept(customers -> {
    customers.forEach(c -> System.out.println(c.getCode()));
});

Error Handling

import com.staqr.client.ApiException;

try {
    Flow flow = flowsApi.getFlow("invalid-id");
} catch (ApiException e) {
    System.err.println("API Error: " + e.getMessage());
    System.err.println("Status Code: " + e.getCode());
    System.err.println("Response Body: " + e.getResponseBody());
    System.err.println("Response Headers: " + e.getResponseHeaders());
}

Spring Boot Integration

Configuration

// application.properties
staqr.api.url=https://my.staqr.com/api/v1
staqr.api.token=${STAQR_API_KEY}
staqr.api.seller-id=${STAQR_SELLER_ID}

Bean Configuration

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.staqr.client.ApiClient;
import com.staqr.client.api.FlowsApi;

@Configuration
public class StaqrConfig {

    @Bean
    public ApiClient staqrApiClient(
            @Value("${staqr.api.url}") String baseUrl,
            @Value("${staqr.api.token}") String token,
            @Value("${staqr.api.seller-id}") String sellerId) {

        ApiClient client = new ApiClient();
        client.setBasePath(baseUrl);
        client.setAccessToken(token);
        client.addDefaultHeader("x-seller-id", sellerId);
        return client;
    }

    @Bean
    public FlowsApi flowsApi(ApiClient client) {
        return new FlowsApi(client);
    }
}

Service Usage

import org.springframework.stereotype.Service;
import com.staqr.client.api.FlowsApi;
import com.staqr.client.model.Flow;

@Service
public class FlowService {

    private final FlowsApi flowsApi;

    public FlowService(FlowsApi flowsApi) {
        this.flowsApi = flowsApi;
    }

    public List<Flow> getAllFlows() throws ApiException {
        return flowsApi.listFlows();
    }
}

Java Requirements

• Java 17 or higher
• Maven 3.6+ or Gradle 7+

Dependencies

The SDK uses:

• OkHttp 4.x for HTTP client
• Gson for JSON serialization
• javax.annotation-api for annotations

Examples

See the examples directory for complete usage examples:

• Basic API calls
• Spring Boot integration
• Error handling patterns
• Pagination handling
• Retry strategies

API Reference

For complete API documentation, see:

• Staqr Platform API Reference
• Commerce API Reference

Troubleshooting

SSL Certificate Issues

import okhttp3.OkHttpClient;
import javax.net.ssl.*;

// Custom SSL context (development only!)
OkHttpClient.Builder builder = new OkHttpClient.Builder();
// Configure custom SSL...

ApiClient client = new ApiClient(builder.build());

Connection Timeouts

ApiClient client = new ApiClient();
client.setConnectTimeout(30000);  // 30 seconds
client.setReadTimeout(30000);
client.setWriteTimeout(30000);