In this Documentation:
- Authentication
- Rate Limiting
- Sandbox Account
- Data Types and Formats
- Concepts
- Common Use Cases
- Endpoints
- Tracing Your Calls
- FAQ
Freight API provides programmatic access to GSS functionality and content.
The API is REST API and uses single token key authentication. Currently, the return format for all endpoints is JSON.
Authentication
We only support authenticated requests. Every API request needs to contain the following headers:
- access_key : your unique API key provided by GSS
- site_id : which site you are requesting action for
- supportemail : your developer email address, that we may email, if a high level of failures or request issues are encountered.
You can get your API access key by signing in to GoSweetSpot at nzc.gosweetspot.com/ and going to your Administration > Preferences & Settings page, then expanding Advanced Settings and your API access key is at the bottom. Note that API access keys are different for each user and each account. It helps the API identify which client account and user to use.
Rate Limiting
Presently, we are not enforcing any rate-limiting. If you find that you are hitting our API at the rate of more than 60 calls per minute or 1000 calls per hour, then your usage needs to be reviewed. More often or not, there could be a better way to deal with the problem.
Sandbox Account
You can create a sandbox account by visiting https://nzc.gosweetspot.com/opensandbox
Data Types and Formats
- All requests and responses are in JSON format only.
- Date & Time: when not specified on the endpoint, the timezone will be NZ Timezone.
Concepts
Customer orders and shipments are two important but different concepts in GoSweetSpot, where a customer order maps one-to-one with an order from an e-commerce system. In contrast, a shipment is one or more packages going to the same destination on the same carrier.
GoSweetSpot dispatches a customer's order as one or more shipments depending on the item's nature, dimensions and weight. e.g. a single order with a large 30kg plant pot and some seed packets might be split into two shipments - 1 bulk carrier shipment for the plant pot and 1 courier shipment for the seed packets.
If you are integrating with an eCommerce, most likely, you will want to create customer orders rather than shipments, and the user will use GoSweetSpot's system to create the shipments from the orders.
Common Use Cases
You have a custom bespoke e-commerce or order platform
Your site does not allow external systems to feed information into it directly.
Your approach will be to publish orders to GSS once the orders are ready for dispatch/labelling. On the GSS system your user would process the order.
At some stage, your system will request the order status update from GSS.
The API interactions would be:
- PUT api/customerorders - triggered from your site when the order is ready for ticketing.
- Using the GSS web portal, your dispatcher tickets the goods.
- GET api/customerorders - triggered by your system every 6 hours, to get status updates on the order published earlier.
You have a very specialised dispatch workflow
You might have a special requirement to integrate the ticketing directly into your existing system. Using an external system to do one part of the workflow may affect performance and be unacceptable. You can use the GSS API to build the ticketing into your system.
The api interactions would be:
- POST api/rates - your system at dispatch, calls the API to get all available freight options and rates
-
POST api/shipments - the dispatcher reviews the freight options from (1) and makes a selection. A second call to generate the shipment is triggered.
You use an open-source platform
Many open source systems, also have an open API platform that GSS can tap into to build the integration directly from within GSS. We would consider any platform that our customers are using. However, depending on platform popularity, the implementation time frames would be considered. If there are very few users on the platform, it may not be a sufficient business case for us to undertake the integration.
You use an open-source platform
Many open-source systems, also have an open API platform that GSS can tap into to build the integration directly from within GSS. We would consider any platform that our customers are using. However, the implementation time frames would be considered depending on platform popularity. If there are very few users on the platform, it may not be a sufficient business case for us to undertake the integration.
Others
Surely, there will be other cases that the API can be applied to. Talk to us, and we will be able to help.
Endpoints
Customer Orders
Using this endpoint, you can publish from your ERP or orders system, into the GSS orders queue. Once published, your operators on GSS can search/scan/click on the order number, to populate the order delivery details automatically. This saves time entering the delivery details.
- GET api/customerorders : Retreives the list of orders already published to GSS. This can be filtered on multiple criteria.
- PUT api/customerorders : Publish into the GSS queue your orders.
Price Enquiry / Rates Query
- POST api/rates : Returns your available rates for the origin to destination specified.
Creating Shipments
- GET api/shipments : Retreives all your historically created shipments, including current status details.
- POST api/shipments : Create a new shipment using a rate or with auto rating. Printing can be automatically triggered as well.
- DELETE api/shipments : Deletes the specified shipment.
Manifesting
- POST v2/publishmanifest : Batch and manifest your current shipments ready for collection. Available on certain carriers only.
Printing
- GET /api/printers : returns a list of available printers
- GET /api/labels : download the labels as PNG or pdf
- POST /api/labels : enqueues the supplied shipment for printing
- POST /api/labels/enqueue enqueues a raw image into the print queue for printing
Pickup Booking
- POST /api/pickupbooking : book a driver to collect your parcels.
Webhooks
GSS can provide feedback to your site using webhooks for certain action triggers.
Actions that can be subscribed to include:
- Shipment created
- Shipment pickup registered by courier
- Shipment delivery registered by courier
- Configuration & Post data
Tracing Your Calls
We allow you to view your most recent API calls to us. To view, use https://nzc.gosweetspot.com/developer/apitrace
This is provided to help you develop/debug your code.
FAQ
How do I connect to the API?
The API is only available to authenticated clients. Clients should authenticate users using an access_key obtained from the Preferences & Settings screen. Once authenticated, you need to request a resource from one of the endpoints using HTTP. Generally, reading any data is done through a request with GET method.
If the user with the access_key has access to multiple sites in the account, a site_id HTTP header with the site id is also required, e.g. site_id: 123456.
What return formats do you support?
Freight API currently returns data in JSON format. Some methods may return [XML] data, however we don't actively test for XML compatibility.
What kind of authentication is required?
Applications must identify themselves to access any resource.
You need to contact your account manager to obtain a test access key.
Every request requires an HTTP header property access_key, as well as support_email. The Support Email should contain the IT-level contact for the organisation. This will be used to contact you, should we find your requests need attention.
If the user with the access_key has access to multiple sites in the account, a site_id HTTP header with the site ID is also required.
Is there a request rate limit?
Presently, there is no rate limiting on the API. We, however, reserve the right to your enforce limits or block calls at our discretion. We request that you limit your requests to 60 calls per minute. If you expect to call at a higher rate, please contact us.
Backwards Compatibility
We try to make every effort to ensure all our functions are backwards compatible. However, as our system evolves, we cannot guarantee that we will be able to support all old/deprecated functions forever. If your implementation breaks due to a change on our system, it will be your responsibility to update the functionality of your system.
Should I crack on?
Sure, fire away. However, we do suggest you talk to us, before starting so we can understand your requirements and explain how best to use this API.