Technical Documentation
Read our Release Notes here.
In this technical documentation:
Open API Specification
View the Customer Integration Open API 3.0 Specification >
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 | |
authurl | Authentication url | |
clientId |
|
|
secret |
|
|
carrierName | Account Carrier | NZCouriers, PostHaste, CastleParcels, 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 for the production endpoints after completion of development and testing in the sandbox.
Endpoint | URL | Description |
|---|---|---|
Customer Integration | This is the base URL that you will use to access the customer integration endpoints as defined in the swagger spec. | |
Authorization | The oauth endpoint you use to exchange your clientid and secret for a JWT token. |
NOTE: Please ensure that only a single / is used in the url, you may get htpp 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 the Freightways 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 Diagrams
Example Scenarios