ZA – South Africa

Fastway2 Parcel API v3

Base URL: https://api.fastway2.org/v3

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

🚀 API reference – quick overview

Create shipment

POST /shipments

Book a parcel, get tracking number and label PDF. Supports SA addresses, HS codes, and itemised customs info.

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/PNG/ZPL). Links expire after 7 days.

Error codes

Standardised error responses with codes (1000–5002) to quickly identify issues like missing fields, auth failures, or carrier rejections.

Tracking codes

List of event codes (PENDING, ARRIVAL, DELIVERED, etc.) used in tracking details. Each maps to a specific logistics stage.

Create shipment (booking)

POST /shipments

Book a parcel with a South African carrier. Returns tracking number and label PDF link. All addresses must be in South Africa.

Request body (JSON)

Field	Type	Required	Length (max)	Description
service_code	string	yes	20	Service type: EXPRESS, ECONOMY, OVERNIGHT_GP, etc.
reference_no	string	no	40	Your custom reference (will appear on label).
sender	object	yes	–	Sender details (SA format).
name	string	yes	60	Full name / company.
phone	string	yes	20	e.g. +27 11 555 1234
email	string	no	80	Optional email for pickup notifications.
country	string	yes	2	Use "ZA".
state	string	yes	30	Province: Gauteng, Western Cape, etc.
city	string	yes	40	e.g. Johannesburg, Cape Town.
address_line1	string	yes	100	Street name & number.
address_line2	string	no	100	Complex, building, floor.
zip_code	string	yes	10	SA postal code.
recipient	object	yes	–	Recipient details (SA format).
name	string	yes	60	Full name / company.
phone	string	yes	20	e.g. +27 71 234 5678
email	string	no	80	For delivery notifications.
country	string	yes	2	Use "ZA".
state	string	yes	30	Province: Gauteng, Western Cape, etc.
city	string	yes	40	e.g. Johannesburg, Cape Town.
address_line1	string	yes	100	Street name & number.
address_line2	string	no	100	Complex, building, floor.
zip_code	string	yes	10	SA postal code.
parcel	object	yes	–	Physical properties & contents.
weight	number	yes	6,3	kg (up to 3 decimals).
length	integer	yes	4	cm
width	integer	yes	4	cm
height	integer	yes	4	cm
items	array	no	–	Itemised list (recommended).
[].sku	string	no	30	Your internal SKU.
[].name	string	yes	120	Item description.
[].hs_code	string	no	15	Harmonized System code (customs).
[].quantity	integer	yes	5	≥1
[].value	number	yes	8,2	Unit value in ZAR.

Complete request example (South African addresses)

{
  "service_code": "ECONOMY",
  "reference_no": "ZA-REF-20250317",
  "sender": {
    "name": "Lindiwe Khumalo",
    "phone": "+27 11 234 5678",
    "email": "lindiwe@example.co.za",
    "country": "ZA",
    "state": "Gauteng",
    "city": "Johannesburg",
    "address_line1": "23 Fredman Drive",
    "address_line2": "Sandton",
    "zip_code": "2196"
  },
  "recipient": {
    "name": "Thabo Ndlovu",
    "phone": "+27 21 555 9876",
    "email": "thabo@example.co.za",
    "country": "ZA",
    "state": "Western Cape",
    "city": "Cape Town",
    "address_line1": "15 Bree Street",
    "address_line2": "City Centre",
    "zip_code": "8001"
  },
  "parcel": {
    "weight": 2.45,
    "length": 35,
    "width": 25,
    "height": 15,
    "items": [
      {
        "sku": "BK-001",
        "name": "African Short Stories",
        "hs_code": "49019900",
        "quantity": 2,
        "value": 185.00
      }
    ]
  }
}
                

✅ Success (201 Created)

{
  "code": 0,
  "message": "Shipment created",
  "data": {
    "tracking_number": "ZA782345678ZA",
    "label_url": "https://api.fastway2.org/v3/labels/ZA782345678ZA.pdf",
    "label_format": "pdf",
    "estimated_cost": 94.30,
    "shipment_id": "shp_za_abc123"
  }
}
                        

❌ Error example (400)

{
  "code": 2001,
  "message": "Missing required field: recipient.name",
  "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). The request body accepts a list of tracking numbers; response contains a map of results and any errors.

Request body (JSON)

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

Response fields

Field	Type	Description
results	object	Dictionary mapping tracking number → tracking details (same structure as below).
errors	object	Invalid or not found numbers with error messages.
tracking_number	string	(inside each result) The tracking number.
status	string	Current status code (e.g. "in_transit")
status_desc	string	e.g. "Out for delivery"
estimated_delivery	string	YYYY-MM-DD
origin	string	Origin city.
destination	string	Destination city.
tracking_details	array	Events (latest first).
timestamp	string	UTC ISO
local_time	string	SAST (Africa/Johannesburg) format: YYYY-MM-DD HH:MM:SS
location	string	Facility/city
description	string	Event description
code	string	Standard tracking code (see codes section)

Request example (multiple)

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

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

✅ Success response (carrier removed)

{
  "code": 0,
  "message": "OK",
  "data": {
    "results": {
      "ZA782345678ZA": {
        "tracking_number": "ZA782345678ZA",
        "status": "out_for_delivery",
        "status_desc": "Out for delivery",
        "estimated_delivery": "2025-03-20",
        "origin": "Cape Town, WC",
        "destination": "Johannesburg, GP",
        "tracking_details": [
          {
            "timestamp": "2025-03-19T05:32:00Z",
            "local_time": "2025-03-19 07:32:00",
            "location": "Johannesburg Depot",
            "description": "Out for delivery",
            "code": "OUT_FOR_DELIVERY"
          }
        ]
      },
      "ZA998877ZA": {
        "tracking_number": "ZA998877ZA",
        "status": "arrived",
        "status_desc": "Arrived at sorting centre",
        "estimated_delivery": "2025-03-21",
        "origin": "Durban",
        "destination": "Pretoria",
        "tracking_details": []
      }
    },
    "errors": {}
  }
}
                        

❌ Partial errors

{
  "code": 0,
  "message": "Partial success",
  "data": {
    "results": { "ZA782345678ZA": { ... } },
    "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), png, zpl

✅ JSON response

{
  "code": 0,
  "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
0	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 (duplicate reference).
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 (EN)	Stage
PENDING	Information received	Pre-transit
PICKED_UP	Collected from sender	In transit
ARRIVAL	Arrived at facility	In transit
DEPARTURE	Departed from facility	In transit
CUSTOMS_HOLD	Held for customs (SA customs)	Customs
CUSTOMS_CLEARED	Cleared by customs	Customs
OUT_FOR_DELIVERY	Out for delivery	Delivery
DELIVERED	Delivered	Final
DELIVERY_FAILED	Attempt failed	Exception
RETURNING	Returning to sender	Return
RETURNED	Returned to sender	Returned
ADDRESS_CORRECTION	Address corrected	Exception
HELD	Held at request	Exception

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