DITA Tracking App

A modern shipping integration service that provides a unified API for multiple carriers (DHL, FedEx).

Current Status (March 12, 2025)

⚠️ Important Notice: While the server is operational, some configuration and integration points need attention:

1. API Integration Status:

   • ✅ DHL API Integration: Functional and tested
   • ✅ FedEx API Integration: Functional and tested (including international rates from Mexico to US)
   • ✅ Rate Comparison: Enhanced with precise component calculations
   • ⚠️ Database Integration: Needs configuration

2. Known Configuration Requirements:

   • Database pooling configuration needs to be verified
   • Event logging system needs to be properly configured
   • Performance monitoring needs to be set up

3. Next Steps:

   • Complete database pooling configuration
   • Implement comprehensive error logging
   • Set up monitoring and alerting
   • Configure rate limiting and API quotas

Features

API Endpoints (9/9 Implemented, Configuration Required)

DHL Endpoints

1. ✅ /api/dhl/track - Track DHL shipments
2. ✅ /api/dhl/rates - Get DHL shipping rates
3. ✅ /api/dhl/validate-address - Validate addresses with DHL

FedEx Endpoints

1. ✅ /api/fedex/track - Track FedEx shipments
2. ✅ /api/fedex/rates - Get FedEx shipping rates (supports domestic and international shipments)
3. ✅ /api/fedex/validate-address - Validate addresses with FedEx

Compare Endpoints

1. ✅ /api/compare/track - Compare tracking across carriers
2. ✅ /api/compare/rates - Compare rates across carriers
3. ✅ /api/compare/validate-address - Compare address validation across carriers

Enhanced Features

Multiple Tracking Number Support

• The tracking API now provides support for tracking multiple shipments at once:
  • ✅ Submit multiple tracking numbers for both DHL and FedEx in a single request
  • ✅ Get consolidated tracking results for all shipments
  • ✅ Efficiently handles large batches of tracking requests
  • Optimized to use carrier-specific bulk tracking APIs when available

International Shipping Support

• The system now fully supports international shipments:
  • ✅ FedEx international rates from Mexico to the US with proper customs information
  • ✅ DHL international rates with component-based pricing
  • Includes automatic customs information for cross-border shipments
  • Properly handles duties and taxes for international shipping
  • Supports different packaging types and service levels for international shipping

Multi-Piece Shipment Support

The tracking API now provides comprehensive support for multi-piece shipments:

• Detects and indicates if a shipment consists of multiple pieces
• Provides total piece count and current piece number
• Shows total shipment weight separate from individual package weight
• Optimized for FedEx multi-piece shipments

Improved Tracking Status Messages

• Ship Date: Shows "Not Scanned Yet" for newly created shipments
• Estimated Delivery: Shows "Updated Once Scanned" until the package is in transit
• Enhanced event tracking with precise status descriptions

Precise DHL Rate Calculation

• Component-based rate breakdown following exact business formula (A1 + A2 + A3 + A4)
  • A1: Base transportation charge extracted from the main service component
  • A2: Fuel surcharge component with proper pricing tier application
  • A3: Premium service charges or additional surcharges when applicable
  • A4: Tax component with precise calculation based on jurisdiction
• Intelligent discount handling for domestic vs. international shipments
  • Domestic shipping: Special 60% discount handling for ECONOMY SELECT DOMESTIC
  • International shipping: Complex multi-tier discounting with appropriate surcharges
• Advanced price component extraction technique:
  • Uses basePrice from DISCOUNT type when available for true pre-discount values
  • Falls back to basePrice from TAX type for non-discounted components
  • Accurately identifies and processes STTXA tax codes for proper tax calculation
• High-performance memory optimization:
  • Zero database operations for all calculations
  • Direct in-memory processing of API responses
  • Minimal data transformations to maintain efficiency
  • Precise decimal handling to ensure financial accuracy
• Response includes both list and account rates with detailed breakdowns
  • List price: Original carrier pricing before discounts
  • Account price: Discounted pricing with applied contract rates
  • All components shown with proper labeling for transparency

Dynamic Delivery Date Estimation

• Smart dynamic delivery date calculation that adjusts based on real-time package status
• Detects when packages are delayed and adjusts estimated delivery accordingly
• Accounts for actual transit progress between major shipping hubs
• Overrides carrier estimates when actual tracking events suggest a different timeline
• Handles special cases such as customs delays and delivery facility arrivals

Transit Days Information

• Tracking responses now include enhanced transit day calculations:
  • ✅ Shows the number of days a package has been in transit
  • ✅ Displays estimated days remaining until delivery
  • ✅ Formats messages like "In Transit: X of Y days completed"
  • ✅ Provides consistent transit information across both DHL and FedEx carriers

API Documentation

DHL Endpoints

Track Shipment

POST /api/dhl/track

Request body:

{
    "tracking_number": "5778969350",
    "carrier": "DHL"
}

Get Rates

POST /api/dhl/rates

Request body (Simplified Format):

{
    "origin": {
        "city": "San Francisco",
        "country": "US",
        "postal_code": "94105"
    },
    "destination": {
        "city": "New York",
        "country": "US",
        "postal_code": "10001"
    },
    "weight": 1.5,
    "length": 20,
    "width": 15,
    "height": 10
}

Validate Address

POST /api/dhl/validate-address

Request body:

{
    "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
    }
}

FedEx Endpoints

Track Shipment

POST /api/fedex/track

Request body:

{
    "tracking_number": "282148584205",
    "carrier": "FEDEX"
}

Response body (standard shipment):

{
    "carrier": "FEDEX",
    "tracking_number": "282148584205",
    "status": "Delivered",
    "estimated_delivery": "2025-01-08T23:32:13.270Z",
    "ship_date": "2025-01-05T12:00:00.000Z",
    "events": [
        {
            "timestamp": "2025-01-08T23:32:13.270Z",
            "location": "NEW YORK, NY",
            "description": "Package delivered",
            "status": "Delivered",
            "additional_details": {}
        }
    ],
    "additional_details": {
        "package_details": {
            "weight": "1.0 KG",
            "dimensions": "25x20x15 CM",
            "service": "FedEx International Priority"
        }
    }
}

Get Rates - International Example

POST /api/fedex/rates

Request body (International Mexico to US):

{
    "origin": {
        "city": "Mexico City",
        "country": "MX",
        "postal_code": "06500"
    },
    "destination": {
        "city": "New York",
        "country": "US",
        "postal_code": "10001"
    },
    "weight": 2.5,
    "length": 30,
    "width": 20,
    "height": 15,
    "planned_shipment_date": "2025-03-20T10:00:00"
}

The system will automatically include the required customs information such as:

• Customs value (default: $100 USD)
• Description (default: "Merchandise")
• Quantity (default: 1)
• Weight (matching package weight)
• Proper duties payment information

Compare Endpoints

Compare Tracking

Endpoint: POST /api/compare/tracking

Description: Compare tracking information across carriers. Now supports multiple tracking numbers for each carrier.

Request body:

{
    "dhl_tracking": ["1637960940", "5778969350"],
    "fedex_tracking": ["282148584205", "772324478403"]
}

Note: Each carrier parameter can accept either a single string or an array of strings for tracking numbers.

Response:

{
    "carriers": ["dhl", "fedex"],
    "services": [
        {
            "carrier": "dhl",
            "tracking_number": "1637960940",
            "status": "Delivered",
            "estimated_delivery": "2025-03-10T12:30:00",
            "events": [...]
        },
        {
            "carrier": "dhl",
            "tracking_number": "5778969350",
            "status": "In Transit",
            "estimated_delivery": "2025-03-13T15:45:00",
            "events": [...]
        },
        {
            "carrier": "fedex",
            "tracking_number": "282148584205",
            "status": "Delivered",
            "estimated_delivery": "2025-03-09T14:22:00",
            "events": [...]
        },
        {
            "carrier": "fedex",
            "tracking_number": "772324478403",
            "status": "In Transit",
            "estimated_delivery": "2025-03-14T10:15:00",
            "events": [...]
        }
    ],
    "data": {
        "carriers": ["dhl", "fedex"],
        "tracking_numbers": {
            "dhl": ["1637960940", "5778969350"],
            "fedex": ["282148584205", "772324478403"]
        },
        "statuses": {
            "dhl": ["Delivered", "In Transit"],
            "fedex": ["Delivered", "In Transit"]
        },
        "estimated_deliveries": {
            "dhl": ["2025-03-10T12:30:00", "2025-03-13T15:45:00"],
            "fedex": ["2025-03-09T14:22:00", "2025-03-14T10:15:00"]
        },
        "events": {
            "dhl": [...],
            "fedex": [...]
        }
    }
}

Compare Rates

Endpoint: POST /api/compare/rates

Description: Compare rates across carriers.

Request body:

{
    "origin": {
        "city": "San Francisco",
        "country": "US",
        "postal_code": "94105"
    },
    "destination": {
        "city": "New York",
        "country": "US",
        "postal_code": "10001"
    },
    "weight": 1.5,
    "length": 20,
    "width": 15,
    "height": 10
}

Response:

{
    "carriers": ["dhl", "fedex"],
    "services": [
        {
            "carrier": "dhl",
            "rate": 12.50,
            "currency": "USD",
            "service": "DHL Ground"
        },
        {
            "carrier": "fedex",
            "rate": 15.00,
            "currency": "USD",
            "service": "FedEx Ground"
        }
    ],
    "data": {
        "carriers": ["dhl", "fedex"],
        "rates": {
            "dhl": 12.50,
            "fedex": 15.00
        },
        "currencies": {
            "dhl": "USD",
            "fedex": "USD"
        },
        "services": {
            "dhl": "DHL Ground",
            "fedex": "FedEx Ground"
        }
    }
}

Installation & Setup

Prerequisites

• Python 3.9 or higher
• PostgreSQL 13 or higher
• Valid DHL and FedEx API credentials

Environment Configuration

Create a .env file with the following structure:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=dita_db
DB_USER=postgres
DB_PASSWORD=your_password

# DHL API Configuration
DHL_API_BASE_URL=https://express.api.dhl.com/mydhlapi/v1
DHL_API_KEY=your_dhl_api_key
DHL_API_SECRET=your_dhl_api_secret

# FedEx API Configuration
FEDEX_SHIPPING_API_BASE_URL=https://apis.fedex.com
FEDEX_SHIPPING_AUTH_URL=https://apis.fedex.com/oauth/token
FEDEX_SHIPPING_API_KEY=your_fedex_shipping_api_key
FEDEX_SHIPPING_API_SECRET=your_fedex_shipping_api_secret
FEDEX_TRACKING_API_BASE_URL=https://apis.fedex.com
FEDEX_TRACKING_AUTH_URL=https://apis.fedex.com/oauth/token
FEDEX_TRACKING_API_KEY=your_fedex_tracking_api_key
FEDEX_TRACKING_API_SECRET=your_fedex_tracking_api_secret

Setup Steps

1. Install dependencies:

   pip install -r requirements.txt

2. Run database migrations:

   alembic upgrade head

3. Start the server:

   python start.py

4. Access the Swagger documentation: http://localhost:8000/docs

Development

Adding a New Carrier

1. Create a new service class in app/services/
2. Implement required methods: get_rates(), track_shipment(), etc.
3. Update the carrier factory in app/services/carrier_factory.py
4. Add any new endpoints in app/api/routes/

Running Tests

pytest tests/

License

Proprietary - DITA Corp