Integration API - Technical Documentation

In this Technical Documentation:



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.

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

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.
Delete

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


Did this article answer your question?

Can't find the answer to your question?

Suggest an article