This project provides a complete mapping of ShipCloud's API. At advarics we're currently evaluating their services and because our applications rely heavily on web technologies we've decided to create a proper JS API-binding. As far as we know there aren't any similar projects available.
This projects is still in development. At this time we're only utilizing the Address-Calls of the API. But soon it'll cover the missing parts of the API too.
We use these fine open source packages and languages:
However, to be able to communicate with the API you'll have to register first to obtain the free developer access keys. Then open src/config.json and put your keys in there.
The structure under src/api/v1 strictly follows the original documentation. It comprises of three sub-directories named calls, types and config
This directory contains all available API calls:
For example, the Address-Call comprises of three calls according to the docs: create, index and read
Therefore we define these call-mappings in our Address class: read, readAll and create.
In general these classes define the high-level portion of the complete API-binding as these don't touch more specific aspects like JSON or HTTP-Requests.
This directory contains all message and response definitions.
Additional Services
Address
Package
Pickup
Rate
Responses ---
|
| ---> Address-Response,
| ---> Carrier-Response
| ---> Pickup-Response
| ----> etc.
Shipment
Shipment Quote
Tracker
Webhook
These classes are DTOs for easy transfer between client and server.
This directory contains elements which aren't described in the original docs.
Api Auth
Api-Auth class contains some helper methods for auth-key management.
All API calls go via the RequestHelper class. This class utilizes node-fetch and implements the GET, POST, PUT and DELETE requests.
First, install node packages with npm install.
To create a development bundle type:
npm run build:dev
To create a production bundle type:
npm run build:prod
After a successful build a new bundle will be created in dist.
To activate hot-module reloading during the development type:
npm run start:hmr
This binding can be used in any JavaScript environment as it contains a complete WebPack build setup that generates a bundle in the dist directory. But it also can be used directly in Node by calling npm run start:client. In this case a special node instance called ts-node will load index.ts from the project root and instantiate a small client script. This script initializes the API binding located in src and some of their API calls to query data from ShipCloud.
Here's an example output:
Notice: It depends on your current setup what and if any data will be sent back from ShipCloud. Also, don't forget to check your API key in src/config.json if you experience any problems.
