Skip to main content

Java SDK

Installation​

Maven​

<dependency>
  <groupId>com.flexops</groupId>
  <artifactId>sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle​

implementation 'com.flexops:sdk:1.0.0'

Quick Start​

import com.flexops.FlexOpsClient;
import com.flexops.model.*;

var client = FlexOpsClient.builder()
    .apiKey("your-api-key")
    .build();

var rates = client.rates().get(RateRequest.builder()
    .from(Address.builder().zip("80202").country("US").build())
    .to(Address.builder().zip("10001").country("US").build())
    .parcel(Parcel.builder().weight(2.5).length(10).width(8).height(4).build())
    .build());

for (var rate : rates.getRates()) {
    System.out.printf("%s %s: $%.2f%n", rate.getCarrier(), rate.getService(), rate.getTotalPrice());
}

Configuration​

var client = FlexOpsClient.builder()
    .apiKey("your-api-key")
    .baseUrl("https://api.flexops.io/v1")  // optional
    .timeout(Duration.ofSeconds(30))        // default 30s
    .maxRetries(3)                          // default 3
    .build();

Shipping Operations​

Create a Label​

var label = client.labels().create(CreateLabelRequest.builder()
    .carrier("usps")
    .service("priority")
    .from(Address.builder()
        .name("Warehouse")
        .street1("123 Main St")
        .city("Denver")
        .state("CO")
        .zip("80202")
        .country("US")
        .build())
    .to(Address.builder()
        .name("Customer")
        .street1("456 Broadway")
        .city("New York")
        .state("NY")
        .zip("10001")
        .country("US")
        .build())
    .parcel(Parcel.builder().weight(2.5).length(10).width(8).height(4).build())
    .build(),
    Options.withIdempotencyKey("order-12345"));

System.out.println(label.getTrackingNumber());
System.out.println(label.getLabelUrl());

Track a Shipment​

var tracking = client.tracking().get("9400111899223456789012");

System.out.println(tracking.getStatus());
System.out.println(tracking.getEstimatedDelivery());

for (var event : tracking.getEvents()) {
    System.out.printf("%s: %s%n", event.getTimestamp(), event.getDescription());
}

Validate an Address​

var result = client.addresses().validate(Address.builder()
    .street1("123 Main St")
    .city("Denver")
    .state("CO")
    .zip("80202")
    .country("US")
    .build());

if (result.isValid()) {
    System.out.println("Validated: " + result.getNormalized());
}

Webhook Verification​

@PostMapping("/webhooks/flexops")
public ResponseEntity<String> handleWebhook(
        @RequestBody String payload,
        @RequestHeader("X-FlexOps-Signature") String signature) {

    if (!WebhookVerifier.verify(payload, signature, "whsec_your_secret")) {
        return ResponseEntity.status(401).body("Invalid signature");
    }

    var event = objectMapper.readValue(payload, WebhookEvent.class);
    switch (event.getType()) {
        case "tracking.delivered" -> handleDelivery(event.getData());
    }

    return ResponseEntity.ok("OK");
}

Error Handling​

try {
    var label = client.labels().create(request);
} catch (RateLimitException e) {
    System.out.printf("Retry after %d seconds%n", e.getRetryAfter());
} catch (FlexOpsException e) {
    System.err.printf("%s: %s%n", e.getCode(), e.getMessage());
}

Async Support​

var asyncClient = FlexOpsAsyncClient.builder()
    .apiKey("your-api-key")
    .build();

asyncClient.rates().getAsync(request)
    .thenAccept(rates -> {
        rates.getRates().forEach(rate ->
            System.out.printf("%s: $%.2f%n", rate.getCarrier(), rate.getTotalPrice()));
    })
    .exceptionally(ex -> {
        System.err.println("Error: " + ex.getMessage());
        return null;
    });