Fastway Couriers Web Application

A professional web application for tracking parcels and getting shipping quotes using the Fastway Couriers South Africa API.

📋 Table of Contents

• Features
• Technology Stack
• Installation
• Configuration
• Usage
• Project Structure
• API Integration
• Testing
• Troubleshooting

✨ Features

1. Parcel Tracking

• Real-time parcel tracking with tracking number
• Display current status and location
• Complete tracking history timeline
• Estimated delivery information
• Mobile-responsive interface

2. Shipping Quote Lookup

• Calculate shipping costs instantly
• Support for multiple delivery types (Standard, Express, Overnight)
• Optional parcel dimensions for accurate pricing
• Multiple service options display
• Detailed pricing breakdown

3. Additional Features

• Clean, professional Bootstrap UI
• Mobile-responsive design
• Input validation and error handling
• Loading indicators
• Print-friendly results pages

🛠 Technology Stack

• Frontend: HTML5, CSS3, Bootstrap 5.3
• JavaScript: Vanilla JavaScript (ES6+)
• Backend: PHP 7.4+
• API: Fastway Couriers REST API
• Icons: Bootstrap Icons

📦 Installation

Prerequisites

• PHP 7.4 or higher
• Web server (Apache/Nginx) or PHP built-in server
• cURL extension enabled in PHP
• Modern web browser

Step 1: Download/Clone the Application

# If using Git
git clone <repository-url> fastway-app
cd fastway-app

# Or download and extract the ZIP file
unzip fastway-app.zip
cd fastway-app

Step 2: Check PHP Installation

# Check PHP version
php -v

# Check if cURL is enabled
php -m | grep curl

Step 3: Configure File Permissions

# Create logs directory
mkdir -p logs
chmod 755 logs

# Ensure API files are readable
chmod 755 api
chmod 644 api/*.php

Step 4: Start the Application

Option A: Using PHP Built-in Server (Development)

# Start server on port 8000
php -S localhost:8000

# Access the application at:
# http://localhost:8000

Option B: Using Apache/Nginx

1. Copy the application to your web server's document root:

   # For Apache (Ubuntu/Debian)
   sudo cp -r fastway-app /var/www/html/
   
   # For Apache (CentOS/RHEL)
   sudo cp -r fastway-app /var/www/html/

2. Configure virtual host (optional)

3. Access via: http://localhost/fastway-app

⚙️ Configuration

API Configuration

The API settings are configured in api/config.php:

// API Key (provided in requirements)
define('FASTWAY_API_KEY', '9f57d11554c24fb8f03a4875f513ce9f');

// API Base URL
define('FASTWAY_API_BASE_URL', 'https://sa.api.fastway.org');

// Required RF Code for Johannesburg
define('FASTWAY_RF_CODE', 'JNB');

Customization

You can customize the application by editing:

• Styling: assets/css/style.css
• Colors: CSS variables in :root selector
• API Settings: api/config.php
• Error Messages: Constants in api/config.php

🚀 Usage

Tracking a Parcel

1. Navigate to the home page or click "Track Parcel" in the navigation
2. Enter a tracking number (e.g., Z60000983328)
3. Click "Track Parcel" button
4. View real-time tracking information including:
   • Current status
   • Current location
   • Tracking history timeline
   • Estimated delivery date
   • Destination information

Test Tracking Numbers:

• Z60000983328
• Z30002408261

Getting a Shipping Quote

1. Click "Get Quote" in the navigation
2. Fill in the required information:
   • Destination Suburb: e.g., Sandton
   • Postal Code: 4-digit code (e.g., 2196)
   • Weight: In kilograms (0.1 - 30 kg)
   • Delivery Type: Standard, Express, or Overnight
3. Optionally add parcel dimensions:
   • Check "Add parcel dimensions"
   • Enter Length, Width, Height in centimeters
4. Click "Calculate Quote"
5. View available shipping options with:
   • Service names and descriptions
   • Pricing breakdown
   • Estimated delivery times
   • Service features

📁 Project Structure

fastway-app/
├── index.php                 # Home/Dashboard page
├── track.php                 # Parcel tracking page
├── quote.php                 # Shipping quote page
├── README.md                 # This file
├── SOP.md                    # Standard Operating Procedure
│
├── api/                      # Backend API handlers
│   ├── config.php           # API configuration and helper functions
│   ├── track.php            # Track & trace API handler
│   └── quote.php            # Quote lookup API handler
│
├── includes/                 # Reusable components
│   ├── header.php           # Navigation header
│   └── footer.php           # Footer
│
├── assets/                   # Frontend assets
│   ├── css/
│   │   └── style.css        # Custom styles
│   ├── js/
│   │   ├── track.js         # Tracking page JavaScript
│   │   └── quote.js         # Quote page JavaScript
│   └── images/              # Images (if any)
│
└── logs/                     # Error logs (auto-created)
    └── error.log            # Application error log

🔌 API Integration

Track & Trace API

Endpoint: https://sa.api.fastway.org/v3/tracktrace/detail

Parameters:

• LabelNo: Tracking number
• api_key: API authentication key

Response: JSON containing tracking information

Quote Lookup API

Endpoint: https://sa.api.fastway.org/v3/psc/lookup

Parameters:

• DestinationPostCode: Postal code
• DestinationSuburb: Suburb name
• WeightInKg: Parcel weight
• RFCode: Region code (JNB)
• Length, Width, Height: Optional dimensions
• api_key: API authentication key

Response: JSON containing quote information

Error Handling

The application handles the following error scenarios:

1. Invalid Input

   • Missing required fields
   • Invalid format (postal code, weight, etc.)
   • Out of range values

2. API Errors

   • Connection timeouts
   • HTTP errors
   • Invalid responses
   • Rate limiting

3. Network Errors

   • No internet connection
   • DNS resolution failures
   • SSL/TLS errors

🧪 Testing

Manual Testing

1. Test Tracking Feature:

   # Valid tracking numbers
   Z60000983328
   Z30002408261
   
   # Invalid tracking number
   INVALID123
   

2. Test Quote Feature:

   # Valid inputs
   Suburb: Sandton
   Postal Code: 2196
   Weight: 2.5 kg
   Delivery Type: Express
   
   # Invalid inputs
   Postal Code: 123 (too short)
   Weight: 50 (over limit)
   

Browser Testing

Test on the following browsers:

• Google Chrome (latest)
• Mozilla Firefox (latest)
• Safari (latest)
• Microsoft Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Responsive Testing

Test on different screen sizes:

• Desktop (1920x1080)
• Laptop (1366x768)
• Tablet (768x1024)
• Mobile (375x667)

🐛 Troubleshooting

Common Issues

1. "cURL error" or API connection failed

Solution:

# Check if cURL is enabled
php -m | grep curl

# If not enabled, install it
# Ubuntu/Debian
sudo apt-get install php-curl

# CentOS/RHEL
sudo yum install php-curl

# Restart web server
sudo service apache2 restart

2. Page shows blank or errors

Solution:

• Check PHP error log: tail -f /var/log/apache2/error.log
• Check application log: tail -f logs/error.log
• Verify PHP version: php -v (must be 7.4+)

3. API returns 401 Unauthorized

Solution:

• Verify API key in api/config.php
• Check if API key is valid and active

4. Tracking/Quote not working

Solution:

• Check network connectivity
• Verify API endpoints are accessible
• Check browser console for JavaScript errors
• Enable error logging in api/config.php

5. Styling issues or broken layout

Solution:

• Clear browser cache
• Check if Bootstrap CSS is loading
• Verify file permissions for CSS files
• Check browser console for 404 errors

Debug Mode

To enable debug mode, edit api/track.php and api/quote.php:

// Change this line
ini_set('display_errors', 0);

// To this
ini_set('display_errors', 1);

Reember to disable debug mode in production!

Getting Help

If you encounter issues:

1. Check the error log: logs/error.log
2. Review browser console for JavaScript errors
3. Verify API configuration in api/config.php
4. Test API endpoints directly using tools like Postman
5. Consult Fastway API documentation

📝 Notes

• This application uses the Fastway Couriers South Africa API
• API key and endpoints are configured for demonstration purposes
• RFCode is set to "JNB" for Johannesburg region
• The application includes fallback mock data for demonstration when API is unavailable
• All prices are shown in South African Rand (ZAR)

🔒 Security Considerations

• Input validation on both client and server side
• XSS prevention through HTML escaping
• SQL injection prevention (not applicable - no database)
• HTTPS recommended for production deployment
• API key should be kept secure and not committed to version control

📄 License

This application was developed as a demonstration project for Fastway Couriers integration.

👨‍💻 Author

Dickson Thabo Masipa

Last Updated: January 2026