HyTrack API v2.0.0

A secure, high-performance REST API built with FastAPI to actively scrape and track shipment statuses for Blue Dart and Delhivery.

This application serves as an independent microservice that replaces unreliable public APIs or manual checking by automating web scraping intelligently. It includes robust local API key management, rate-limiting, and hardened bcrypt hashing for administrative scale and security.

Table of Contents

• Architecture & How It Works
• Hardware Platform
• Security Features
• Authentication & API Key Management
• Utilizing the Tracker API
• Local Development & Setup
• Production Deployment
• License

Architecture & How It Works

HyTrack is designed as a headless scraping microservice tailored for couriers with unreliable or strictly guarded backend APIs.

• Blue Dart: The API maps directly to their hidden third-party tracking GET endpoints and parses the HTML response using BeautifulSoup4.
• Delhivery: Because Delhivery's tracking portal is heavily JavaScript-rendered and blocks basic HTTP requests, HyTrack utilizes webdriver-manager to spin up live, headless Google Chrome instances via Selenium. It dynamically waits for the WebSockets and React components to load before extracting the tracking timeline.
• SQLite Database: The application manages its own independent SQLite database (api_keys.db) to locally store, validate, and revoke client API tokens without relying on a bulky external database.

Hardware Platform

The API is specifically optimized to perform bare-metal scraping on Edge hardware.

• Platform: Raspberry Pi 5 (AArch64) running Linux.
• Resource Management: Because launching headless Chrome browsers is highly RAM-intensive, the system utilizes global asynchronous semaphores to cap concurrent browser instances. This strictly prevents the Raspberry Pi from exhausting its memory and triggering OOM crashes under simultaneous request load.

Security Features

The application is heavily fortified against internal and external threat vectors:

• Military-Grade Hashing: All generated client keys are instantly hashed using native Python bcrypt (v5+). Plaintext tokens are never stored, ensuring full forward-secrecy.
• Rate Limiting: Active Rate Limiting via slowapi enforces a strict 10 requests/minute ceiling per IP address to prevent Denial of Service (DoS) sweeps that could overwhelm the tracking engines.
• Timing Attack Prevention: The Master API Key is verified using constant-time digest comparison (secrets.compare_digest) to defeat side-channel timing attacks.
• Parameter Injection Protection: The FastAPI endpoints enforce rigid Regex bounds and character limits on all tracking waybills to prevent URL injection or buffer overflows.
• Cloudflare WAF: The official production endpoint is shielded behind Cloudflare, with the interactive /docs Swagger UI blocked from public access via custom WAF rules to obscure the API topology.

---

Authentication & API Key Management

The API uses a two-tier authentication system.

1. Master Key: Defined securely in .env. Used only for the /admin/* endpoints.
2. Client Keys: Generated by the API. Used for the /track endpoint.

Public API Access: The official API is currently hosted at https://assa.hyclotron.com. To obtain an active Client API Key for this endpoint, please contact nick@hyclotron.com or submit a pull request detailing your integration use case.

Generate a Client Key

Include the Master Key in the X-API-Key header to request a new client token (Admin Only):

curl -X POST -H 'X-API-Key: your_super_secret_master_key_here' \
    "http://127.0.0.1:8000/admin/keys/generate?name=Mobile_App_Client"

Warning

The generated plaintext key will only be shown once! The API securely stores a bcrypt hash in the api_keys.db SQLite database.

---

Utilizing the Tracker API

Endpoint: GET /track
Headers Required: X-API-Key: <your_generated_client_key>
Query Parameters:

• courier: BLUEDART or DELHIVERY
• waybill: The tracking number (Alphanumeric only, max 50 characters)

Example Request (BlueDart)

curl -s -H "X-API-Key: 1.BpccXmw_secureClientKeyString" \
    "https://assa.hyclotron.com/track?courier=BLUEDART&waybill=12345678900"

Example Response

{
  "Courier": "Blue Dart",
  "Location": "cityexp",
  "Details": "Shipment Delivered",
  "Date": "2026-01-27",
  "Time": "15:56",
  "Link": "https://www.bluedart.com/trackdartresultthirdparty?trackFor=0&trackNo=12345678900"
}

---

Local Development & Setup

Ensure you have Python 3.9+ installed. The system requires Google Chrome (or Chromium) locally to execute the headless Selenium scraping instances.

1. Install Dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Environment: You must define a Master API_KEY for generating client tokens.

echo 'API_KEY="your_super_secret_master_key_here"' > .env

3. Start the Server:

./run.sh
# Alternatively: uvicorn api:app --host 127.0.0.1 --port 8000

Production Deployment

HyTrack API is designed to run as a persistent background service on Linux platforms.

1. Systemd Service: Create a systemd service file (e.g., hytrack.service) pointing ExecStart to the uvicorn binary inside your .venv. Set the server to bind to 0.0.0.0 to listen on your network interfaces.
2. Reverse Proxy: Place nginx or another reverse proxy in front of the application running on 127.0.0.1. This is necessary to properly forward the X-Real-IP and X-Forwarded-For HTTP headers so the rate-limiter functions correctly instead of blocking the local proxy.
3. WAF Protection: Route external traffic through Cloudflare or a similar Web Application Firewall to block access to the automatically generated /docs and /openapi.json standard FastAPI endpoints.

---

License

This project is licensed under the terms of the GNU General Public License v3.0 (GPLv3). Please review the LICENSE file in the root of the repository for full compliance and distribution expectations.