ZA – South Africa

Fastway2 Parcel API v3

🔵 Test Environment
Base URL: https://apitest.fastway2.org/v3
X-API-Key: fw3_test_za_8f7e3d2a1c

🟢 Production Environment
Base URL: https://api.fastway2.org/v3
X-API-Key: To be provided upon official application

Authentication: Include your API key in the X-API-Key header.
X-API-Key: your_api_key_here

🚀 API reference – quick overview

Create shipment

POST /shipments

Book a parcel, get tracking number and label PDF. Supports CN → ZA shipments with full item details.

Track parcel

POST /track

Retrieve full tracking history for up to 100 tracking numbers. Returns local SA timestamps and standardised event codes.

Get label

GET /labels/{tn}

Re‑download shipping label (PDF). Links expire after 7 days.

Error codes

Standardised error responses with codes (1000–5002) to quickly identify issues.

Tracking codes

List of event codes (PENDING, ARRIVAL, DELIVERED, etc.) used in tracking details.

Create shipment (booking)

POST /shipments

Book a parcel. Sender in China/Hong Kong, recipient in South Africa (ZA). Returns tracking number and label PDF link.

Request body (JSON)

Field	Type	Required	Length (max)	Description
service_code	string	yes	20	Default fixed value: `1575`.
reference_no	string	yes	40	Your unique reference number.
inco_term_code	string	yes	3	International Commercial Terms (e.g., "DDP").
specialInstruction1	string	no	255	Special handling instructions (e.g., "Fragile").
sender	object	yes	–	Sender details (CN/HK format).
name	string	yes	60	Full name / company.
phone	string	yes	20	e.g. +86 20 91234567
email	string	no	80	Email for pickup notifications.
country	string	yes	2	Use `CN` for China.
state	string	yes	30	e.g. "Guangdong"
suburb	string	yes	40	City/District.
address_line_1	string	yes	200	Street address, building, floor.
address_line_2	string	no	200	Additional address details.
postcode	string	no	10	Postal code if any.
recipient	object	yes	–	Recipient details (South Africa).
name	string	yes	60	Full name / company.
phone	string	yes	20	e.g. +27 71 234 5678
email	string	yes	80	For delivery notifications (mandatory).
country	string	yes	2	Use `ZA`.
state	string	yes	30	Province: Gauteng, Western Cape, etc.
suburb	string	yes	40	e.g. "Sandton", "Braamfontein".
address_line_1	string	yes	200	Street address, building, floor.
address_line_2	string	no	200	Additional address details.
postcode	string	yes	10	South African postal code (4 digits).
parcel	object	yes	–	Physical properties & contents.
weight	number	yes	6,3	Total parcel weight in kg (up to 3 decimals).
length	integer	yes	4	cm
width	integer	yes	4	cm
height	integer	yes	4	cm
items	array	yes	–	Itemised list (mandatory).
[].sku	string	yes	30	Your internal SKU (mandatory).
[].quantity	number	yes	4	Item quantity.
[].name	string	yes	120	Item description.
[].hs_code	string	yes	10	Harmonized System code (mandatory).
[].currency	string	yes	3	ISO currency code, e.g. ZAR, USD.
[].value	number	yes	8,2	Unit value in the specified currency.
[].sku_weight	number	yes	6,3	Weight of a single unit of this SKU.
[].sku_weight_unit	string	yes	5	Unit: `kg` or `g` (default kg).
[].image_url	string	yes	500	URL to product image (Recommend).
[].product_url	string	yes	500	URL to product sales page (Recommend).

Complete request example (CN → ZA)

{
  "service_code": "1575",
  "reference_no": "ZA-REF-20250126-001",
  "inco_term_code": "DDP",
  "specialInstruction1": "Fragile - handle with care",
  "sender": {
    "name": "Li Wei",
    "phone": "+86 20 91234567",
    "email": "li.wei@example.cn",
    "country": "CN",
    "state": "Guangdong",
    "suburb": "Guangzhou",
    "address_line_1": "123 Tianhe Road",
    "address_line_2": "Unit 1802",
    "postcode": "510620"
  },
  "recipient": {
    "name": "Thabo Ndlovu",
    "phone": "+27 71 234 5678",
    "email": "thabo@example.co.za",
    "country": "ZA",
    "state": "Gauteng",
    "suburb": "Braamfontein",
    "address_line_1": "45 Smit Street",
    "address_line_2": "",
    "postcode": "2000"
  },
  "parcel": {
    "weight": 2.45,
    "length": 35,
    "width": 25,
    "height": 15,
    "items": [
      {
        "sku": "BK-001",
        "quantity":1,
        "name": "African Short Stories",
        "hs_code": "49019900",
        "currency": "ZAR",
        "value": 185.00,
        "sku_weight": 0.45,
        "sku_weight_unit": "kg",
        "image_url": "https://example.com/images/book1.jpg",
        "product_url": "https://example.com/product/49019900"
      }
    ]
  }
}

✅ Success (200 OK)

{
  "code": 200,
  "message": "Shipment created",
  "data": {
    "tracking_number": "ZA782345678ZA",
    "label_url": "https://api.fastway2.org/v3/labels/ZA782345678ZA.pdf",
    "label_format": "pdf",
    "reference_no": "ZA-REF-20250126-001"
  }
}
                        

❌ Error example (400)

{
  "code": 2001,
  "message": "Missing required field: items[0].currency",
  "data": null
}
                        

Label URL expires after 7 days. Use the Get label endpoint to refresh.

Track parcel

POST /track

Retrieve tracking history for one or multiple tracking numbers (max 100 per request).

Request body (JSON)

Field	Type	Required	Description
tracking_numbers	array of strings	yes	Array of tracking numbers, e.g. `["ZA782345678ZA"]`. Max 100 items.

Response fields

Field	Type	Description
results	object	Dictionary mapping tracking number → tracking details.
errors	object	Invalid or not found numbers with error messages.
tracking_number	string	The tracking number.
latest_status_code	string	Current status code (e.g., "created_01").
latest_status_description	string	Human-readable description of current status.
latest_extended_description	string	Additional details about current status.
latest_local_time	string	Local timestamp (SAST) of the latest event.
latest_location	string	Location of the latest event.
origin	string	Origin city.
destination	string	Destination city.
tracking_details	array	List of tracking events (latest first).
timestamp	string	UTC ISO timestamp of the event.
local_time	string	Local SAST time (YYYY-MM-DD HH:MM:SS).
location	string	Facility or city where the event occurred.
status_code	string	Tracking event code (see Tracking event codes table).
status_description	string	Description of the event.
extended_description	string	Optional additional information about the event.

Request example

POST /v3/track
Content-Type: application/json

{
  "tracking_numbers": ["ZA782345678ZA", "ZA998877ZA"]
}
                

✅ Success response

{
  "code": 200,
  "message": "OK",
  "data": {
    "results": {
      "ZA782345678ZA": {
        "tracking_number": "ZA782345678ZA",
        "latest_status_code": "delivered_09",
        "latest_status_description": "Delivery Completed",
        "latest_extended_description": "Parcel handed to resident and signed",
        "latest_local_time": "2025-03-25 16:20:00",
        "latest_location": "Johannesburg",
        "origin": "Hong Kong",
        "destination": "Johannesburg, GP",
        "tracking_details": [
          {
            "timestamp": "2025-03-25T14:20:00Z",
            "local_time": "2025-03-25 16:20:00",
            "location": "Johannesburg",
            "status_code": "delivered_09",
            "status_description": "Delivery Completed",
            "extended_description": "Proof of delivery signed by recipient"
          },
          {
            "timestamp": "2025-03-25T08:15:00Z",
            "local_time": "2025-03-25 10:15:00",
            "location": "Johannesburg Depot",
            "status_code": "od_01",
            "status_description": "Out for Delivery",
            "extended_description": "Driver assigned to route 12B"
          },
          {
            "timestamp": "2025-03-24T22:00:00Z",
            "local_time": "2025-03-25 00:00:00",
            "location": "Johannesburg Hub",
            "status_code": "depot_01",
            "status_description": "Arrived at destination depot",
            "extended_description": "Parcel sorted for delivery"
          },
          {
            "timestamp": "2025-03-23T18:30:00Z",
            "local_time": "2025-03-23 20:30:00",
            "location": "Johannesburg Sorting Centre",
            "status_code": "sorted_01",
            "status_description": "In Transit",
            "extended_description": "Processed at sorting facility"
          },
          {
            "timestamp": "2025-03-22T10:45:00Z",
            "local_time": "2025-03-22 12:45:00",
            "location": "Johannesburg Customs",
            "status_code": "customs_cleared_01",
            "status_description": "Released from Customs",
            "extended_description": "Customs clearance completed, duties paid"
          },
          {
            "timestamp": "2025-03-21T09:00:00Z",
            "local_time": "2025-03-21 11:00:00",
            "location": "Johannesburg Customs",
            "status_code": "under_clearance_03",
            "status_description": "Your parcel is currently with customs.",
            "extended_description": "Awaiting customs inspection"
          },
          {
            "timestamp": "2025-03-19T10:30:00Z",
            "local_time": "2025-03-19 18:30:00",
            "location": "Hong Kong Hub",
            "status_code": "processed_01",
            "status_description": "Parcel Check In",
            "extended_description": "Parcel accepted at origin facility"
          },
          {
            "timestamp": "2025-03-18T08:00:00Z",
            "local_time": "2025-03-18 16:00:00",
            "location": "Hong Kong",
            "status_code": "created_01",
            "status_description": "We have been notified of your order.",
            "extended_description": "Shipping label created, awaiting pickup"
          }
        ]
      },
      "ZA998877ZA": {
        "tracking_number": "ZA998877ZA",
        "latest_status_code": "sorted_01",
        "latest_status_description": "In Transit",
        "latest_extended_description": "Parcel in transit to destination country",
        "latest_local_time": "2025-03-26 09:45:00",
        "latest_location": "Hong Kong International Hub",
        "origin": "Durban",
        "destination": "Pretoria",
        "tracking_details": [
          {
            "timestamp": "2025-03-26T07:45:00Z",
            "local_time": "2025-03-26 09:45:00",
            "location": "Hong Kong International Hub",
            "status_code": "sorted_01",
            "status_description": "In Transit",
            "extended_description": "Handed over to airline"
          },
          {
            "timestamp": "2025-03-25T22:30:00Z",
            "local_time": "2025-03-26 00:30:00",
            "location": "Durban Hub",
            "status_code": "processed_04",
            "status_description": "Shipment Added in Transit Bag",
            "extended_description": "Bagged for export"
          },
          {
            "timestamp": "2025-03-25T14:00:00Z",
            "local_time": "2025-03-25 16:00:00",
            "location": "Durban",
            "status_code": "created_01",
            "status_description": "We have been notified of your order.",
            "extended_description": "Order received"
          }
        ]
      }
    },
    "errors": {}
  }
}
                        

❌ Partial errors

{
  "code": 200,
  "message": "Partial success",
  "data": {
    "results": {
      "ZA782345678ZA": {
        "tracking_number": "ZA782345678ZA",
        "status": "in_transit",
        "status_desc": "In transit",
        "origin": "Cape Town",
        "destination": "Johannesburg",
        "tracking_details": []
      }
    },
    "errors": {
      "INVALID999": "Tracking number format invalid",
      "ZA000000ZA": "Not found"
    }
  }
}
                        

Get shipping label

GET /labels/{trackingNumber}

Download a previously generated label. Default response is JSON with URL; add ?format=pdf to get the file directly.

Path & query

Parameter	Type	Description
trackingNumber	string	e.g. ZA782345678ZA
format (opt)	string	pdf (default)

✅ JSON response

{
  "code": 200,
  "message": "Success",
  "data": {
    "tracking_number": "ZA782345678ZA",
    "label_url": "https://api.fastway2.org/v3/labels/ZA782345678ZA.pdf",
    "label_format": "pdf",
    "created_at": "2025-03-17T10:30:00Z",
    "expires_at": "2025-03-24T10:30:00Z"
  }
}
                        

❌ Not found error

{
  "code": 4000,
  "message": "Label not found / expired",
  "data": null
}
                        

Error codes

Code	Message	Description
200	Success	No error.
1000	Internal server error	Try again later.
1001	Service unavailable	Maintenance.
2000	Invalid parameter	Check field format.
2001	Missing required field	Field is mandatory.
2002	Parameter out of range	Value exceeds allowed length/range.
3000	Authentication failed	Invalid or missing X-API-Key.
3001	Permission denied	Key lacks access.
4000	Resource not found	Tracking number not recognised.
4001	Duplicate request	Idempotency conflict.
5000	Business validation failed	Address unreachable / P.O. Box not allowed.
5001	Carrier rejection	Downstream carrier error.
5002	Quota exceeded	Too many requests.

Tracking event codes

Code	Description	Stage
cre_01	We have been notified of your order.	Created
cre_02	Collection Assigned	Created
pro_01	Parcel Check In	Processed
pro_04	Shipment Added in Transit Bag	Processed
arr_01	Flight Partial Arrived	Arrived
unc_01	Parcel Collected from Airport	Under Clearance
unc_02	Your parcel has been stopped at customs.	Under Clearance
unc_03	Your parcel is currently with customs.	Under Clearance
unc_04	Customs rejected the shipment.	Under Clearance
ccl_01	Released from Customs	Cleared
ccl_02	Customs Invoice Paid	Cleared
cus_03	Released from Security	Cleared
sor_01	In Transit	Sorted to destination
sor_02	Collected	Sorted to destination
sor_03	Ready For Dispatch	Sorted to destination
dep_01	Arrived at destination depot	Reach destination depot
dep_02	Pickup Point Depot	Reach destination depot
ofd_01	Out for Delivery	Out for delivery
tex_01	Delayed Parcel	Transit exception
tex_02	Misdirected	Transit exception
tex_03	Damaged	Transit exception
tex_04	Parcel Intercepted	Transit exception
exe_01	Protest Action	Delivery Exception
exe_02	Premises closed on arrival	Delivery Exception
exe_03	Traffic Congestion	Delivery Exception
exe_04	Out of Time	Delivery Exception
exe_05	Calling Card Left	Delivery Exception
exe_06	Bad Weather	Delivery Exception
exe_07	Problem Freight	Delivery Exception
exe_08	Address Unclear	Delivery Exception
exe_09	Consignee on Holiday	Delivery Exception
exe_10	Rejected Delivery	Delivery Exception
exe_11	Cannot Locate Receiver	Delivery Exception
exe_12	Change of Address	Delivery Exception
exe_13	Out of Regional Boundaries	Delivery Exception
del_01	Signature Obtained	Delivered
del_02	Back door Delivery	Delivered
del_03	Left in Letterbox	Delivered
del_04	Contactless Signature	Delivered
del_05	Left in Safe Place	Delivered
del_06	Manual POD	Delivered
del_07	Left As Instructed	Delivered
del_08	Left with Neighbour	Delivered
del_09	Delivery Completed	Delivered
del_10	Parcel Collected by Customer	Delivered
cla_01	Insurance Claim	Claim
cla_02	Hijacking Claim	Claim
cla_03	Damaged Claim	Claim
can_01	Cancelled Shipment	Cancelled
ret_01	Return to Sender	Returned
aba_01	Abandoned Shipment	Destroyed/Abandoned

All local times are South African Standard Time (SAST, UTC+2).