In this Technical Documentation:
- Open API Specification
- Example Scenarios
- Getting Connected
- Code Snippets
- Selecting Carrier and Customer
- Date and Time Handling
- AddressRight
- Sequence Diagram
Open API Specification
View the Customer Integration Open API 3.0 Specification >
Example Scenarios
Validating an Address
Validating an address and determining the geo-coordinates of the address is performed using the AddressRight functionality we have integrated into the API via the following endpoints.
- /v1/addressFuzzy (go to endpoint)
- /v1/addressMatch (go to endpoint)
- /v1/addressAutocomplete (go to endpoint)
Once you have a verified address you can exchange the ID for a full address object which can be used for rating, consignments, and pickup requests using
- /v1/addresses/{addressId} (go to endpoint)
Unvalidated Addresses
If you do not have a validated address then you can still request rates and create consignments by providing an address with a valid suburb, town, and optional postcode.
The charges for the consignment will be indicative only of the specific address and hence available services will be unknown, further costs may be applied.
If we are unable to accurately identify the address a warning is returned within the response payload from the rating and consignment requests.
This consignment was created without a validated lat/lon. The costs were based on a proximity location. Further charges and a differing service level may apply based on the actual delivery address.
If you requested Saturday delivery and the address is unvalidated then the Saturday delivery option is ignored. If the Saturday delivery option has been selected, it will be shown in the responses' isSaturdayDelivery flag.
Fetching Services Available at an Address
Once a geo-coordinate has been obtained the services available to the address can be retrieved from the services endpoint /v1/services ( go to endpoint).
Fetching Local Service Locations
The geo-coordinate can also be used to retrieve the service locations in proximity using /v1/service-locations (go to endpoint).
This endpoint allows filtering by the type of Service Location and specifying a radius from the geo-coordinate. If no radius is provided it will return all service locations.
Fetching Rates for a Consignment
With a valid geo-coordinate for the address the rate for a consignment can be determined using /v1/carriers/{carrierName}/customers/{customerId}/rates (go to endpoint).
Creating a Consignment
A consignment can be created with a POST to /v1/carriers/{carrierName}/customers/{customerId}/consignments (go to endpoint).
The response will include the identifiers for each item, barcode strings for each consignment item, and the calculated cost.
This request can also be used to create a label in which case the response will include a link to retrieve the barcode.
Fetching Consignments
A list of consignments can be fetched using a GET from /v1/carriers/{carrierName}/customers/{customerId}/consignments (go to endpoint).
A single item can be retrieved from /v1/carriers/{carrierName}/customers/{customerId}/
consignments/{consignmentId}.
Cancelling a Consignment
A request to cancel a consignment can be made with a POST to /v1/carriers/{carrierName}/customers/{customerId}/consignments/
{consignmentId}/CancellationRequests (go to endpoint).
At this time, this will record a request to cancel which will be manually handled.
Placing a Pickup Request
A consignment can be created with a POST to /v1/carriers/{carrierName}/customers/{customerId}/pickup-location-pickup-requests (go to endpoint)
This post will identify the pickup location using the issued PIN identifier.
Reprinting a Label
If a label needs to be reprinted for an existing consignment place a GET request to /v1/carriers/{carrierName}/customers/{customerId}/consignments/
{consignmentId}/labels (go to endpoint).
Getting Connected
Access to the API is authorized using OAuth 2.0 client credentials flow which allows a client to authenticate with the authorisation server using a client_id and client_secret. Once authenticated, the client is issued with a token it can use to make authorized requests to the customer integration API.
Postman Examples for the Sandbox
The Freightways Customer Integration API Postman Workspace has example requests for each of the different endpoints in the API. You can use this as a quick start to exploring our API in the Sandbox, which is an area where you can safely experiment with our API.
Postman Variables:
| Variable | Description | Example |
|---|---|---|
| baseUrlCI |
URL of Customer Integration API |
https://customer-integration.ep-sandbox.freightways.co.nz |
| authurl | Authentication URL | https://auth.ep-sandbox.freightways.co.nz/oauth2/token |
| clientId | ||
| secret | ||
| carrierName | Account Carrier | NZCouriers, PostHaste, Castle Parcels, NowCouriers |
| customerId | Account Customer Id |
Endpoints
To use the API either in code or with another tool, you will need the following URLs.
These URLs are for the Sandbox, please enquire about the production endpoints after the completion of development and testing in the sandbox.
| Endpoint | URL | Description |
|---|---|---|
| Customer Integration | https://customer-integration.ep-sandbox.freightways.co.nz | This is the base URL you will use to access the customer integration endpoints as defined in the swagger spec. |
| Authorization | https://auth.ep-sandbox.freightways.co.nz/oauth2/token | The oauth endpoint you use to exchange your clientid and secret for a JWT token. |
Please ensure that only a single / is used in the URL, you may get http 404 Not Found errors if you use a URL such as https://customer-integration.ep-sandbox.freightways.co.nz//v1/addressFuzzy. So when configuring postman please do not add a trailing / to the baseUrlCI variable.
Code Snippets
Obtaining an Access Token
The following C# code snippet demonstrates making a call to the authorization server to obtain an access token. Replace #{CLIENT_ID_HERE}#, #{CLIENT_SECRET_HERE}# and #{OAUTH2_TOKEN_URL_HERE}# with your supplied values.
var httpClient = new HttpClient();
// Create request
httpClient.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
string credentials = String.Format("{0}:{1}", "#{CLIENT_ID_HERE}#", "#{CLIENT_SECRET_HERE}#");
httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes(credentials)));
var values = new Dictionary<string, string>
{
{ "grant_type", "client_credentials" }
};
var content = new FormUrlEncodedContent(values);
var response = await httpClient.PostAsync("#{OAUTH2_TOKEN_URL_HERE}#", content);
// Issue the request
var result = await response.Content.ReadAsStringAsync();
dynamic tokenDetails = JObject.Parse(result);
// Retrieve the token that can be used to make requests of the API
string accessToken = tokenDetails.access_token;Calling the API
Once a valid token has been obtained, requests can be made to the API, including the token in the header.
var httpClient = new HttpClient();
// Add the Access Token to the request
httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
string requestJson= "#{REQUEST_BODY_AS_JSON_HERE}#";
var content = new StringContent(requestJson, Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("#{CUSTOMER_INTEGRATION_URL_HERE}#", content);
// If you need to discuss a call with Freightways support the returned correlationId will enable us to identify the call in our logs
var correlationId = response.Headers.GetValues("X-Correlation-ID").FirstOrDefault();Selecting Carrier and Customer
When using the Customer Integration API, the Carrier and Customer ID are provided as part of the URL. e.g. /v1/carriers/NZCouriers/customers/12345678/rates.
Valid Carriers are:
- NZCouriers
- PostHaste
- CastleParcels
- NowCouriers
The Customer ID is validated against the access token to ensure the correct account is accessed.
Date and Time Handling
All dates in the request and response payloads are UTC times, and the standard ISO 8601 formatting is used. e.g. 2020-08-12T20:17:46.384Z
AddressRight
Detail on how to map AddressRight fields to our address object.
- Street = addressRightAddress.FormattedAddress.Line1
- Secondary = addressRightAddress.FormattedAddress.Line2
- Suburb = addressRightAddress.StructuredAddress.Suburb
- Town = addressRightAddress.StructuredAddress.Town
- PostCode = addressRightAddress.StructuredAddress.Postcode
- Country = addressRightAddress.StructuredAddress.Country
- AddressValidationSource = "AddressRight"
- AddressValidationId = addressRightAddress.References.Id
Sequence Diagram
