Getting Started with Shipium
Set up your organization's Shipium account.
First steps
To start using Shipium's application programming interfaces (APIs), you must first:
- set up your organization's account within the Shipium Console; and
- create an authentication method for your organization.
How to create your Shipium account
To create your organization's Shipium account:
- Create an API key (API key; or OAuth 2.0) by using the Shipium Console application. You can read more about the console in Shipium Console Overview.
- Follow the procedures in the API Key-based Authentication / OAuth 2.0-based Authentication documentation. Both are industry-standard protocols for authorization, and your organization may have a preferred authentication method.
- (OPTIONAL: authenticate via OAuth 2.0 to get what is needed for the OAuth 2.0-based calls).
- Make the API calls using your preferred authentication method.
For more information
See Authentication for more information about:
- creating API credentials;
- API key-based authentication;
- OAuth 2.0-based authentication; and
- using your API credentials with Postman. (Postman is an API platform for building, testing, and using APIs.)
About the general organization of the APIs
The Shipium APIs follow the REST, or REpresentational State Transfer, paradigm.
This means our APIs:
- use predictable resource-oriented uniform resource locators (URLs);
- accept JavaScript Object Notation (JSON) request bodies;
- return responses as JSON-encoded data; and
- use standardized response codes, authentication, and verbs.
You'll interact with our APIs using mostly the POST (meaning "create") or GET (meaning "read") methods.
Response codes and error conditions
Broadly, Shipium responses come in three flavors:
Response code | What it means | What to expect |
---|---|---|
200 | Success! | You'll get back what you expected. |
4XX | Failure | Something at your end needs to be fixed for the API call to succeed. |
5XX | Failure | Something at Shipium's end needs to be fixed for the API call to succeed, or potentially an error from a carrier or other system on which Shipium depends needs to be resolved. |
Error body format
All errors returned by this service follow the same JSON 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'll be provided with two API keys when you create your organization's Shipium account: 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 testing. This prevents you from accidentally impacting your production data while testing or pointing your production services at the test endpoint.
About the API test mode
The Shipium API set has separate endpoints when you're 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. You can find more details in Authentication.
Date formats
All dates in the API are strings in the ISO 8601 "combined date and time representation" format. The following table provides Coordinated Universal Time (UTC) and Pacific Time Zone (PT) examples:
Date and time | Format |
---|---|
UTC time | 2020-01-01T23:30:00Z |
Time with PT | 2015-05-15T15:30:00-8:00 |
Terminology guide
Updated 4 months ago