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.
For a C++ version visit this repo.
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 these sub-directories:
calls
config
public
types
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 elements which aren't described in the original docs.
Api Auth
Api-Auth class contains some helper methods for auth-key management.
ShipCloud
This directory contains the public ShipCloud interface. Clients should use it for type-safe API access.
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.
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
To test the binding in Node type:
npm run start:client
Now a special node instance called ts-node will load index.ts to boot the API client.
Type:
npm run build:client
The generated build will be located in dist/client.
Copy this directory to your web server and open index.html.
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.