README.md

ShipEngine Java SDK

The official Java SDK for ShipEngine API.

Quick Start

Install shipengine from the Maven Central Repository by adding the following under the dependencies key in your pom.xml:

<dependency>
    <groupId>com.shipengine</groupId>
    <artifactId>shipengine</artifactId>
    <version>1.0.1</version>
</dependency>

• The only configuration requirement for the SDK is providing an API Key.

Instantiate ShipEngine Class

import com.shipengine.ShipEngine;

public class ShipEngineDemo {
    public static void main() {
        ShipEngine shipengine = new ShipEngine("<YOUR_API_KEY_HERE>");
    }
}

• You can also pass in a HashMap/Map containing configuration options instead of just passing in a string that is your API Key.

import com.shipengine.ShipEngine;

public class ShipEngineDemo {
    public static void main() {
        ShipEngine shipengine = new ShipEngine(new HashMap<>() {{
            put("apiKey", "<YOUR_API_KEY_HERE>");
            put("pageSize", 75);
            put("retries", 3);
            put("timeout", 60000);
        }});
    }
}

Methods

• createLabelFromRate - When retrieving rates for shipments using the getRatesWithShipmentDetails method, the returned information contains a rateId property that can be used to purchase a label without having to refill in the shipment information repeatedly.
• createLabelFromShipmentDetails - Purchase and print a label for shipment.
• getRatesWithShipmentDetails - Given some shipment details and rate options, this method returns a list of rate quotes.
• listCarriers - Returns a list of carrier accounts that have been connected through the ShipEngine dashboard.
• trackUsingLabelId - Track a package by its associated label ID.
• trackUsingCarrierCodeAndTrackingNumber - Track a package for a given carrier and tracking number.
• validateAddresses - Indicates whether the provided addresses are valid. If the addresses are valid, the method returns a normalized version based on the standards of the country in which the address resides. If an address cannot be normalized, an error is returned.
• voidLabelWithLabelId - Void a label with its Label ID.

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

1. Clone this repo
   git clone https://github.com/ShipEngine/shipengine-java.git

2. Install dependencies
   mvn install

3. Build the code
   mvn package

4. Lint the code
   mvn checkstyle:check

5. Run the tests
   mvn test

VS Code Setup

Install the Java Extension Pack to help write, test and debug the application, and install Checkstyle for Java to enable code formatting.

Committing

This project adheres to the Conventional Commits specification.