Getting Started with Shipium

This page explains how to get started using Shipium's APIs.

First steps

The first steps are:

  1. Create an API key (API Key or OAuth 2.0) by using the Shipium Console application.
  2. Follow the procedures in the API Key-based Authentication / OAuth 2.0-based Authentication documentation.
  3. (OPTIONAL: authenticate via OAuth 2.0 to get what is needed for the OAuth 2.0-based calls).
  4. Make the API calls using your preferred authentication method.

See Authentication for more information.

General organization of the APIs

The Shipium APIs follow the REST paradigm.

They use predictable resource-oriented URLs, accept JSON request bodies, return JSON-encoded responses, and use standardized response codes, authentication, and verbs. Most interactions use either the POST or GET verbs.

Terminology guide

See Common Terms and Definitions

Response codes and error conditions

Broadly, Shipium responses come in three flavors:

  • 200 - Success! You will get back what you expected.
  • 4XX - Failure, something at your end needs to be fixed for the call to succeed.
  • 5XX - Failure, something at Shipium's end or potentially an error from a carrier or other system on which Shipium depends.

Error body format

All errors returned by this service follow the same format:

{
    "timestamp": "2020-11-07T01:08:41.934+00:00",
    "status": XXX,
    "error": "Useful information",
    "message": "XXX STANDARD_HTTP_LABEL",
    "path": "/api/v1/path/that/was/called"
}

Error conditions

The Package Sizing APIs conform to Shipium's standard API Response Codes.

About your test and production API keys

You will be provided with two API keys when you sign up: one for production and one for testing.

The testing API key will not work in production and the production API key will not work in test. This prevents you from accidentally impacting your production data while testing or pointing your production services at the test endpoint!

About the test mode

The Shipium API set has a separate endpoints when you are in test mode.

Working in test mode does not affect your organization's live data.

General format and syntax information

Authorization

Request authentication is via OAuth 2.0 using the Authorization request header or authorization URL parameter. See Authentication.

Date formats

All dates in the API are strings in the ISO 8601 "combined date and time representation" format. Below are UTC and Pacific Time Zone examples:

Date and Time

Format

UTC time

2020-01-01T23:30:00Z

Time with TimeZone

2015-05-15T15:30:00-8:00


Did this page help you?