Endpoints꞉ Internationals - Fastway-Couriers-South-Africa/myFastway.ApiClient GitHub Wiki

Contents

  1. Prerequisites
  2. Quick Start
  3. Address Endpoints
  4. Shipment Endpoints

Endpoints

Address Endpoints

Endpoint Verb Paging Description
/api/internationals/addresses/countries GET returns all countries
/api/internationals/addresses/countries/{countryCode} GET returns country by code
/api/internationals/addresses/countries/{countryCode}/cities GET Y returns cities for given country
/api/internationals/addresses/countries/{countryCode}/cities?startsWith={startsWith} GET returns cities for given country
/api/internationals/addresses/countries/{countryCode}/states GET returns states for given country
/api/internationals/addresses/validate POST validates consignee address

Shipment Endpoints

Endpoint Verb Paging Description
/api/internationals/shipments GET Y returns all international shipments
/api/internationals/shipments POST creates shipment
/api/internationals/shipments/{id} GET returns shipment for a given Id
/api/internationals/shipments/{id}/files GET returns all files (meta-data only) for a given shipment
/api/internationals/shipments/{id}/files/{fileId} GET returns given file and content for a given shipment
/api/internationals/shipments/{id} DELETE Deletes shipment for a given Id
/api/internationals/shipments?from={from}&to={to} GET Y returns shipments for a given date range
/api/internationals/shipments/quote PUT returns quotation

Prerequisites

Aramex account setup

If you have previously registered an account with Aramex, ensure your account details are configured in the myFastway portal (under Administration | Options) before sending a shipment. This will ensure the correct rates are used.

shipping account options

Quick Start

Recommended Approach

The recommended approach to shipping is to validate the Consignee address first. A given address only has to be validated once, once validated, subsequent shipments can miss this step.

Using the international address endpoints to return the countries, cities and states (where applicable) will give the highest chance of successfully validating.

  1. Get all Countries (or specific country if code is known)
  2. Get all Cities for given country
  3. Get all States for given country
  4. Populate address with Country, City and State provided
  5. Populate address with all other fields (AddressLine1, AddressLine2, AddressLine3 and PostalCode)
  6. Validate Address

Once the Consignee address is validated, this object can then be used to create a shipment

Minimum Information Required to ship internationally

The following is the minimum amount of information required to create a shipment. All fields below are mandatory.

Shipping a Document

{
  "to": {
    "code": "",
    "contactName": "",
    "phoneNumber": "",
    "email": "",
    "address": {
      "addressLine1": "",
      "addressLine2": "",
      "addressLine3": "",
      "city": "",
      "postalCode": "",
      "country": ""
    }
  },
  "productType": "PDX",
  "numberOfPieces": 1,
  "actualWeight": "1.00",
  "descriptionOfGoods": "",
  "declaredValue": "1.00"
}

Shipping a Parcel

{
  "to": {
    "code": "",
    "contactName": "",
    "phoneNumber": "",
    "email": "",
    "address": {
      "addressLine1": "",
      "addressLine2": "",
      "addressLine3": "",
      "city": "",
      "postalCode": "",
      "country": ""
    }
  },
  "productType": "PPX",
  "numberOfPieces": 1,
  "length": 1,
  "width": 1,
  "height": 1,
  "unit": "CM",
  "actualWeight": "1.00",
  "descriptionOfGoods": "",
  "declaredValue": "1.00"
}

productType One of the available Shipment Product Types

Address Endpoints

Countries

/api/internationals/addresses/countries

/api/internationals/addresses/countries/{countryCode}

Returns all Countries (or specific Country if countryCode supplied)

Response Object
{
    "data": [
        {
            "code": "AR",
            "name": "Argentina"
        },
        {
            "code": "BR",
            "name": "Brazil"
        },
        {
            "code": "CA",
            "name": "Canada"
        },
        {
            "code": "FR",
            "name": "France"
        },
        {
            "code": "DE",
            "name": "Germany"
        },
        ...
    ]
}

Cities

/api/internationals/addresses/countries/{countryCode}/cities?PageNumber=0

/api/internationals/addresses/countries/{countryCode}/cities?startsWith={startsWith}&PageNumber=0

Returns all Cities for a given Country, the result set can be narrowed by providing a startsWith with a minimum of 2 characters

Response Object
{
    "data": [
        "Aarons Pass",
        "Abba River",
        "Abbey",
        "Abbeyard",
        "Abbeywood",
        "Abbotsbury",
        "Abbotsford",
        "Abbotsham",
        "Abeckett Street",
        "Abels Bay",
        "Abercorn",
        "Abercrombie",
        ...
    ]
}

States

/api/internationals/addresses/countries/{countryCode}/states

Returns all States for a given Country. Note: Not all Countries will have States and this field can be often ommitted.

Response Object
{
  "data": [
    {
      "code": "AC",
      "name": "ACT"
    },
    {
      "code": "NS",
      "name": "New South Wales"
    },
    {
      "code": "NT",
      "name": "Northern Territory"
    },
    {
      "code": "QL",
      "name": "Queensland"
    },
    {
      "code": "SA",
      "name": "South Australia"
    },
    {
      "code": "TA",
      "name": "Tasmania"
    },
    {
      "code": "VI",
      "name": "VICTORIA"
    },
    {
      "code": "WA",
      "name": "Western Australia"
    }
  ]
}

Address Validation

/api/internationals/addresses/validate

International address validation is less restrictive than domestic, not requiring geo-coordinates focusing more on the Country, City and PostalCode values. To Validate an address, POST the model below

{
  "addressLine1": "",
  "addressLine2": "",
  "addressLine3": "",
  "city": "",
  "postalCode": "",
  "state": "",
  "country": ""
}

country (length: 2) The country code returned from /api/internationals/addresses/countries

A successful validation will return an HttpStatusCode (200 OK), a failed validation will return a HttpStatusCode (400 BadRequest) with an array of Error Response Objects

Shipment Endpoints

Create Shipment

With new Consignee

Note: It is recommended that all new address are validated before attempting a shipment

{
  "to": {
    "code": "",
    "contactName": "",
    "phoneNumber": "",
    "email": "",
    "address": {
      "addressLine1": "",
      "addressLine2": "",
      "addressLine3": "",
      "city": "",
      "postalCode": "",
      "country": ""
    }
  },
  "productType": "PDX",
  "numberOfPieces": 1,
  "actualWeight": "1.00",
  "descriptionOfGoods": "",
  "declaredValue": "1.00"
}

to.country One of the available Country Codes e.g. for New Zealand use 'NZ'

With known Consignee Request

This request will use a previously saved contact using the ContactId provided

{
  "to": {
    "contactId": 0
  },
  "productType": "PPX",
  "numberOfPieces": 1,
  "length": 1,
  "width": 1,
  "height": 1,
  "unit": "CM",
  "actualWeight": "1.00",
  "descriptionOfGoods": "",
  "declaredValue": "1.00"
}

Get Shipment By Id

/api/internationals/shipments/{id}

returns shipment object for given Id

Response Object
{
  "data": {
    "shipmentId": 0,
    "from": {
      "contactId": 0,
      "code": "",
      "businessName": "",
      "contactName": "",
      "phoneNumber": "",
      "email": "",
      "address": {
        "addressLine1": "",
        "addressLine2": "",
        "addressLine3": "",
        "city": "",
        "addressId": 0,
        "stateOrProvince": "",
        "postalCode": "",
        "country": "",
        "hash": "",
        "updatedOn": "0001-01-01T00:00:00",
        "updatedBy": null
      },
      "version": null
    },
    "to": {
      "contactId": 0,
      "code": "",
      "businessName": "",
      "contactName": "",
      "phoneNumber": "",
      "email": "",
      "address": {
        "addressLine1": "",
        "addressLine2": "",
        "addressLine3": "",
        "city": "",
        "addressId": 0,
        "stateOrProvince": "",
        "postalCode": "",
        "country": "",
        "hash": "",
        "updatedOn": "0001-01-01T00:00:00",
        "updatedBy": null
      },
      "version": null
    },
    "label": "",
    "hawb": "",
    "descriptionOfGoods": "",
    "packageType": "",
    "length": 1.0,
    "width": 1.0,
    "height": 1.0,
    "unit": "CM",
    "numberOfPieces": 1,
    "createdOn": "",
    "actualWeight": 1.0,
    "hasAttachments": true,
    "customsValueCurrencyCode": "AUD",
    "customsValueAmount": 1.0,
    "expectedCurrencyCode": "AUD",
    "expectedTotal": 1.0,
    "actualCurrencyCode": "",
    "actualTotal": 0.0,
    "invoiceNo": 0,
    "isDutiable": true,
    "uriPart": "10795bad-a678-432c-b034-0cad07797a31",
    "trackingItems": [
      {
        "updateDate": "2020-04-24T14:27:00",
        "description": "Record created.",
        "location": "Sydney, Australia",
        "comments": ""
      }
    ],
    "shipmentFiles": [
      {
        "shipmentId": 601,
        "shipmentFileId": 1,
        "fileTypeId": 2,
        "fileName": "label.pdf",
        "fileType": "Label"
      },
      {
        "shipmentId": 601,
        "shipmentFileId": 2,
        "fileTypeId": 1,
        "fileName": "CommercialInvoice.pdf",
        "fileType": "Invoice"
      }
    ]
  }
}

shipmentFiles.fileTypeId One of the available Shipment File Types

Shipment Files

/api/internationals/shipments/{id}/files

returns all files for a given shipment, exluding the binary content.

Response Object
{
  "data": [
    {
      "shipmentId": 0,
      "shipmentFileId": 1,
      "fileTypeId": 2,
      "fileName": "8200394882.pdf",
      "fileType": "Label"
    },
    {
      "shipmentId": 0,
      "shipmentFileId": 2,
      "fileTypeId": 1,
      "fileName": "CommercialInvoice.pdf",
      "fileType": "Invoice"
    }
  ]
}

Shipment File

/api/internationals/shipments/{id}/files/{fileId}

returns a specific file a given shipment, including the binary content.

Response Object
{
  "data": {
    "shipmentId": 0,
    "shipmentFileId": 2,
    "fileTypeId": 1,
    "fileName": "CommercialInvoice.pdf",
    "fileType": "Invoice",
    "content": "j5SH2md1cfqY+0O9Yn6TOui..."
  }
}

Get By Date Range

/api/internationals/shipments?from={from}&to={to}

The format for the from and to query params is YYYYMMDD, e.g. for consignments between the 1st and 3rd of August 2018, the query string would be /api/consignments?from=20180801&to=20180603

Get Quote

/api/internationals/shipments/quote (PUT)

Passing up the same model as required by the minimum information required to ship internationally will return the following response

Response Object
{
  "data": {
    "currencyCode": "AUD",
    "price": 0.0,
    "tax": 0.0,
    "total": 0.0
  }
}