Mercedes DFE - API Documentation

Authentication

The API uses two authentication methods:

API Key: Required for all /api/v1/ endpoints. Pass via X-API-Key header.
Session Token: Required for authenticated operations. Pass via X-Session-Token header.

Web GUI endpoints (/api/) use cookie-based session authentication via /api/auth/login.

POST /api/v1/auth/login Authenticate and get session token

Request Headers

X-API-Key: your_api_key

Request Body

{
    "username": "your_username",
    "password": "your_password"
}

Response

{
    "success": true,
    "session_token": "abc123...",
    "expires_at": "2024-01-01T08:00:00",
    "user_id": "D6SAFAKH"
}

POST /api/v1/auth/logout Logout and invalidate session

Request Headers

X-API-Key: your_api_key
X-Session-Token: your_session_token

POST /api/auth/login Web GUI login (cookie-based session)

Request Body

{
    "username": "your_username",
    "password": "your_password"
}

Response

{
    "success": true,
    "user_id": "D6SAFAKH"
}

GET /api/auth/status Check authentication status

Response

{
    "authenticated": true,
    "user_id": "D6SAFAKH"
}

Markets & Dealers

GET /api/v1/markets Get available markets

Response

{
    "markets": [
        {"mpc": "EG02", "displayURL": "Egypt"},
        {"mpc": "AE01", "displayURL": "United Arab Emirates"}
    ]
}

GET /api/v1/markets/{mpc}/dealers Get dealers for a market

Path Parameters

Parameter	Type	Description
mpc	string	Market code (e.g., EG02)

Response

{
    "dealers": [
        {"dealerId": "EGC40000", "dealerName": "Abou Ghaly Motors"}
    ],
    "market": "EG02"
}

GET /api/v1/dealers/{mpc}/{dealer_id}/groups Get vehicle groups for a dealer

Response

{
    "groups": [
        {"label": "A-Class", "vehicle_type": "Passenger Cars"},
        {"label": "C-Class", "vehicle_type": "Passenger Cars"}
    ],
    "market": "EG02",
    "dealer_id": "EGC40000"
}

Extraction

POST /api/v1/extraction/start Start extraction job

Request Body

{
    "markets": ["EG02"],
    "all_dealers": true,
    "all_groups": true,
    "lob_codes": ["01", "03", "07", "11", "EQ"],
    "download_mode": "collective"
}

Response

{
    "success": true,
    "job_id": "20240101_120000",
    "message": "Extraction started."
}

GET /api/v1/extraction/status Get extraction status

Response

{
    "status": "running",
    "job_id": "20240101_120000",
    "overall_progress": 45.5,
    "markets_done": 1,
    "markets_total": 2,
    "dealers_done": 5,
    "dealers_total": 10,
    "vehicles_downloaded": 150,
    "elapsed_time": "00:05:30"
}

POST /api/v1/extraction/stop Stop extraction

Sends a stop signal to the running extraction job.

Files

GET /api/v1/files List downloaded files

Response

{
    "files": [
        {
            "name": "enquiries_20240101_120000.json",
            "size": 1048576,
            "size_formatted": "1.0 MB",
            "modified": "2024-01-01T12:30:00"
        }
    ],
    "count": 1
}

GET /api/v1/files/{filename} Download file as JSON or raw

Returns file content as JSON. Add ?raw=true for raw file download.

GET /api/v1/files/{filename}/excel Download file as Excel

Converts JSON vehicle data to Excel (.xlsx) with styled headers and auto-adjusted column widths.

DELETE /api/v1/files/{filename} Delete file

Permanently deletes the specified file.

Credit Balance

GET /api/credit/current Get latest balance snapshot with change info

Response

{
    "has_data": true,
    "balance": 1250000.00,
    "credit_limit": 5000000.00,
    "total_receivables": 3200000.00,
    "special_liabilities": 0.00,
    "credit_exposure": 3750000.00,
    "balance_change": -150000.00,
    "last_updated": "2024-01-15T14:30:00",
    "source": "scheduled"
}

GET /api/credit/history Get balance snapshots with filtering and pagination

Query Parameters

Parameter	Type	Default	Description
date_from	YYYY-MM-DD	today	Start date
date_to	YYYY-MM-DD	today	End date
changes_only	true/false	true	Only show snapshots where balance changed
page	int	1	Page number
per_page	int	20	Items per page

Response

{
    "snapshots": [...],
    "total": 45,
    "page": 1,
    "per_page": 20,
    "pages": 3,
    "changes_only": true
}

GET /api/credit/chart-data Get time-series data for Chart.js

Query Parameters

Parameter	Type	Description
date	YYYY-MM-DD	Single date (or use date_from/date_to for range)
date_from	YYYY-MM-DD	Range start
date_to	YYYY-MM-DD	Range end

Response

{
    "labels": ["14:00", "14:30", "15:00"],
    "datasets": {
        "balance": [1400000, 1250000, 1250000],
        "credit_limit": [5000000, 5000000, 5000000]
    },
    "multi_day": false,
    "count": 3
}

POST /api/credit/refresh Manually trigger balance check Cooldown

Triggers an immediate balance check. Subject to cooldown (default 1200s).

Response (success)

{"success": true, "message": "Balance check started"}

Response (cooldown active)

{"success": false, "message": "...", "cooldown_remaining": 845}

Wholesale Tracking

GET /api/wholesale/today Get latest wholesale batch with vehicles

Response

{
    "has_data": true,
    "batch": {
        "id": 42,
        "timestamp": "2024-01-15T10:00:00",
        "total_vehicles": 15,
        "new_vehicles": 3,
        "balance_before": 1400000.00,
        "balance_after": 1250000.00,
        "estimated_batch_cost": 150000.00,
        "source": "scheduled"
    },
    "vehicles": [
        {
            "id": 1,
            "commission_number": "EG123456",
            "vin": "WDD2130...",
            "model_description": "C 200",
            "vehicle_class": "C-Class",
            "wholesale_date": "2024-01-15",
            "is_sale": true,
            "is_return": false,
            "resolved_price": 850000.00,
            "price_source": "actual",
            "price_badge": "Actual"
        }
    ]
}

GET /api/wholesale/summary Get lightweight summary for dashboard

Response

{
    "has_data": true,
    "total_vehicles": 15,
    "new_vehicles": 3,
    "last_updated": "2024-01-15T10:00:00"
}

GET /api/wholesale/history Get paginated batch history

Query Parameters

Parameter	Type	Default	Description
date_from	YYYY-MM-DD	-	Filter by vehicle wholesale date
date_to	YYYY-MM-DD	-	Filter by vehicle wholesale date
page	int	1	Page number
per_page	int	20	Items per page

GET /api/wholesale/batch/{batch_id}/vehicles Get vehicles for a specific batch

Path Parameters

Parameter	Type	Description
batch_id	int	Batch ID

Query Parameters

Parameter	Type	Description
date_from	YYYY-MM-DD	Optional wholesale date filter
date_to	YYYY-MM-DD	Optional wholesale date filter

GET /api/wholesale/vehicles Search/filter vehicles across all batches

Query Parameters

Parameter	Type	Default	Description
search	string	-	Search commission_number, VIN, model_description
date_from	YYYY-MM-DD	-	Wholesale date start
date_to	YYYY-MM-DD	-	Wholesale date end
page	int	1	Page number
per_page	int	20	Items per page

POST /api/wholesale/refresh Manually trigger wholesale scrape Cooldown

Triggers a wholesale report fetch. Subject to cooldown.

POST /api/wholesale/explore Live wholesale explorer with custom filters

Live-query the DFE wholesale report with custom filters. No cooldown.

Request Body

{
    "date_from": "20240101",
    "date_to": "20240115",
    "division": "01",
    "material_type": "MBPC",
    "grouping": "model_class",
    "material_number": "",
    "vehicle_number": "",
    "report_type": "period",
    "dealer_summary": true,
    "class_summary": true
}

Response

{
    "success": true,
    "vehicles": [...],
    "count": 15,
    "new_count": 3,
    "batch_id": 42,
    "filters": {...}
}

Enquiries

GET /api/enquiries/summary Get lightweight summary for dashboard

Response

{
    "has_data": true,
    "total_vehicles": 245,
    "group_count": 12,
    "last_updated": "2024-01-15T08:00:00",
    "total_value": 185000000.00
}

GET /api/enquiries/latest Get most recent snapshot per vehicle group

Response

{
    "snapshots": [
        {
            "id": 1,
            "snapshot_date": "2024-01-15",
            "vehicle_group": "C-Class",
            "vehicle_count": 35,
            "created_at": "2024-01-15T08:00:00"
        }
    ],
    "total_vehicles": 245,
    "group_count": 12
}

GET /api/enquiries/vehicles Get paginated vehicle list with filtering/sorting

Query Parameters

Parameter	Type	Default	Description
group	string	-	Comma-separated vehicle group(s)
nst	string	-	Comma-separated model number(s)/NST
search	string	-	Search commission, VIN, model, location, salesperson
sort	string	commission_number	Sort column
order	asc/desc	asc	Sort order
page	int	1	Page number
per_page	int	20	Items per page

Sort columns: commission_number, vin, model_description, colour, wholesale_price, mbeg_stock_date, location, sales_person_name

GET /api/enquiries/groups Get vehicle groups with NST options

Response

{
    "groups": [
        {
            "label": "C-Class",
            "vehicle_type": "Passenger Cars",
            "vehicle_count": 35,
            "national_types": [
                {"label": "C 200", "value": "20543"}
            ]
        }
    ],
    "source": "dfe"
}

source can be dfe (live), cache, or snapshots (fallback).

POST /api/enquiries/refresh Manually trigger enquiry scrape Cooldown

Triggers an enquiry snapshot scrape. Subject to cooldown.

GET /api/enquiries/new-allocations Get new vehicle allocations for a date

Query Parameters

Parameter	Type	Default	Description
date	YYYY-MM-DD	today	Target date

Response

{
    "date": "2024-01-15",
    "total_new": 5,
    "groups": {
        "C-Class": {
            "vehicles": [...],
            "count": 3,
            "total_value": 2550000.00
        },
        "E-Class": {
            "vehicles": [...],
            "count": 2,
            "total_value": 2100000.00
        }
    }
}

GET /api/enquiries/stats Get per-group statistics

Query Parameters

Parameter	Type	Default	Description
date	YYYY-MM-DD	today	Target date

Response

{
    "date": "2024-01-15",
    "stats": [
        {
            "vehicle_group": "C-Class",
            "current_count": 35,
            "previous_count": 32,
            "new_today": 3,
            "total_value": 29750000.00
        }
    ],
    "summary": {
        "total_current": 245,
        "total_previous": 240,
        "total_new": 5
    }
}

GET /api/enquiries/diff/{date_str} Get diff view for a specific date

Path Parameters

Parameter	Type	Description
date_str	YYYY-MM-DD	Target date

Response

{
    "date": "2024-01-15",
    "total_new": 5,
    "groups": {
        "C-Class": {
            "new_vehicles": [...],
            "removed_commissions": ["EG654321"],
            "new_count": 3,
            "total_value": 2550000.00
        }
    }
}

GET /api/enquiries/export Download filtered vehicles as Excel

Query Parameters

Parameter	Type	Description
group	string	Comma-separated vehicle group(s)
nst	string	Comma-separated model number(s)
search	string	Search term
preset	string	Preset name (for reference in export)

Returns an Excel file (.xlsx) with one sheet per vehicle group containing all 21 vehicle columns.

Filename: DFE_Enquiries_YYYY-MM-DD.xlsx

Filter Presets

GET /api/presets?type={type} List all presets of a given type

Query Parameters

Parameter	Type	Description
type required	string	Preset type (e.g., enquiry_filter, wholesale_filter)

Response

{
    "presets": [
        {
            "id": 1,
            "name": "My C-Class Filter",
            "preset_type": "enquiry_filter",
            "filters": {"group": "C-Class", "nst": "20543"},
            "use_count": 5,
            "created_at": "2024-01-10T09:00:00",
            "last_used_at": "2024-01-15T14:00:00"
        }
    ]
}

POST /api/presets Create a new preset

Request Body

{
    "name": "My C-Class Filter",
    "preset_type": "enquiry_filter",
    "filters": {"group": "C-Class", "nst": "20543"}
}

Response (201)

{
    "id": 1,
    "name": "My C-Class Filter",
    "preset_type": "enquiry_filter",
    "filters": {"group": "C-Class", "nst": "20543"},
    "use_count": 0,
    "created_at": "2024-01-15T14:00:00",
    "last_used_at": null
}

PUT /api/presets/{preset_id} Update an existing preset

Request Body

{
    "name": "Updated Name",
    "filters": {"group": "E-Class"}
}

DELETE /api/presets/{preset_id} Delete a preset

Response

{"success": true}

POST /api/presets/{preset_id}/apply Apply preset and return its filters

Increments use_count, updates last_used_at, and returns the preset with its filters.

Dashboard & Scheduler

GET /api/dashboard/credit-balance Get latest credit balance for dashboard widget

Response

{
    "has_data": true,
    "balance": 1250000.00,
    "credit_limit": 5000000.00,
    "total_receivables": 3200000.00,
    "credit_exposure": 3750000.00,
    "balance_change": -150000.00,
    "change_direction": "down",
    "last_updated": "2024-01-15T14:30:00"
}

GET /api/dashboard/today-summary Get today's operations summary

Query Parameters

Parameter	Type	Default	Description
date	YYYY-MM-DD	today	Target date

Response

{
    "has_data": true,
    "is_live": true,
    "balance_trend": "down",
    "cars_bought": 3,
    "cars_sold": 1,
    "new_allocations": 5,
    "opening_balance": 1400000.00,
    "closing_balance": 1250000.00,
    "total_spent": 150000.00
}

GET /api/dashboard/scheduler-status Get scheduler status

Response

{
    "scheduler_enabled": true,
    "scheduler_mode": "standalone",
    "jobs": [
        {
            "type": "check_balance",
            "name": "Check Credit Balance",
            "last_run": "2024-01-15T14:30:00",
            "last_status": "completed",
            "error_message": null
        }
    ]
}

POST /api/scheduler/trigger/{job_type} Manually trigger a scheduler job Cooldown

Path Parameters

Parameter	Type	Description
job_type	string	check_balance, scrape_wholesale, etc.

Response (429 if in cooldown)

{"success": false, "error": "Job is in cooldown period", "remaining_seconds": 845}

GET /api/scheduler/cooldowns Get cooldown status for all job types

Response

{
    "cooldowns": {
        "check_balance": {"allowed": true, "remaining_seconds": 0},
        "scrape_wholesale": {"allowed": false, "remaining_seconds": 845}
    }
}

Notifications

GET /api/notifications Get notifications list

Query Parameters

Parameter	Type	Default	Description
limit	int	20	Maximum notifications to return

Response

{
    "notifications": [
        {
            "id": 1,
            "timestamp": "2024-01-15T14:30:00",
            "title": "Balance Changed",
            "message": "Credit balance decreased by 150,000",
            "level": "warning",
            "read": false,
            "dismissed": false
        }
    ]
}

GET /api/notifications/count Get unread notification count

Response

{"unread_count": 3}

POST /api/notifications/{notif_id}/read Mark a notification as read

Response

{"success": true}

POST /api/notifications/{notif_id}/dismiss Dismiss a notification

Response

{"success": true}

POST /api/notifications/mark-all-read Mark all notifications as read

Response

{"success": true}

Insights & Pricing

GET /api/insights/today Get live today's summary

Response

{
    "date": "2024-01-15",
    "is_live": true,
    "balance_trend": "down",
    "opening_balance": 1400000.00,
    "closing_balance": 1250000.00,
    "total_spent": 150000.00,
    "cars_bought": 3,
    "cars_sold": 1,
    "new_allocations": 5,
    "bought_details": [...],
    "sold_details": [...]
}

GET /api/insights/{date_str} Get summary for a specific date

Path Parameters

Parameter	Type	Description
date_str	YYYY-MM-DD	Target date

GET /api/insights/{date_str}/events Get chronological events for a day

Response

{
    "date": "2024-01-15",
    "events": [
        {
            "timestamp": "2024-01-15T10:00:00",
            "type": "wholesale_purchase",
            "description": "3 vehicles purchased"
        }
    ]
}

GET /api/insights/range Get summaries for a date range (max 90 days)

Query Parameters

Parameter	Type	Description
from required	YYYY-MM-DD	Range start
to required	YYYY-MM-DD	Range end

GET /api/vehicles/{commission_number}/price Get vehicle price breakdown

Response

{
    "commission_number": "EG123456",
    "active_price": 850000.00,
    "active_source": "actual",
    "sources": [
        {
            "source": "actual",
            "badge": "Actual",
            "amount": 850000.00,
            "date": "2024-01-15",
            "is_active": true
        },
        {
            "source": "enquiry",
            "badge": "Enquiry",
            "amount": 845000.00,
            "date": "2024-01-10",
            "is_active": false
        }
    ],
    "discrepancy": null
}

Job History

GET /api/history/jobs Get paginated job history

Query Parameters

Parameter	Type	Default	Description
type	string	all	Job type filter (check_balance, scrape_wholesale, etc.)
page	int	1	Page number
per_page	int	20	Items per page

Response

{
    "jobs": [
        {
            "id": 1,
            "job_type": "check_balance",
            "status": "completed",
            "started_at": "2024-01-15T14:30:00",
            "completed_at": "2024-01-15T14:30:45",
            "duration_seconds": 45,
            "error_message": null
        }
    ],
    "total": 150,
    "page": 1,
    "per_page": 20,
    "pages": 8
}

GET /api/history/jobs/{job_id} Get full details for a job

Path Parameters

Parameter	Type	Description
job_id	int	Job ID

POST /api/history/jobs/{job_id}/stop Request cancellation of a running job

Response

{"success": true, "message": "Cancellation requested"}

GET /api/history/daily-summaries Get daily summaries list

Query Parameters

Parameter	Type	Default	Description
limit	int	30	Maximum summaries

Response

{
    "summaries": [
        {
            "id": 1,
            "summary_date": "2024-01-15",
            "opening_balance": 1400000.00,
            "closing_balance": 1250000.00,
            "cars_bought": 3,
            "cars_sold": 1,
            "new_allocations": 5,
            "total_spent": 150000.00,
            "created_at": "2024-01-15T23:59:00"
        }
    ]
}

Reference Data

GET /api/v1/lob-codes Get LOB codes

Response

{
    "codes": [
        {"code": "01", "name": "Passenger Cars"},
        {"code": "03", "name": "Commercial Vehicles"},
        {"code": "07", "name": "Trucks"},
        {"code": "11", "name": "Buses"},
        {"code": "EQ", "name": "Electric Vehicles"}
    ]
}

GET /api/v1/history Get extraction history

Query Parameters

Parameter	Type	Description
status	string	Filter by status (completed, failed, stopped)
limit	integer	Limit number of results

GET /api/v1/keys List API keys Session Token

Returns all API keys for the authenticated user.

POST /api/v1/keys Create new API key Session Token

Creates a new API key. The full key is only returned once on creation.

DELETE /api/v1/keys/{key_id} Delete an API key Session Token

Permanently revokes and deletes the specified API key.

OpenAPI Specification

Download the full OpenAPI 3.0 specification:

Download OpenAPI Spec

API Documentation

Sections

Authentication

Request Headers

Request Body

Response

Request Headers

Request Body

Response

Response

Markets & Dealers

Response

Path Parameters

Response

Response

Extraction

Request Body

Response

Response

Files

Response

Credit Balance

Response

Query Parameters

Response

Query Parameters

Response

Response (success)

Response (cooldown active)

Wholesale Tracking

Response

Response

Query Parameters

Path Parameters

Query Parameters

Query Parameters

Request Body

Response

Enquiries

Response

Response

Query Parameters

Response

Query Parameters

Response

Query Parameters

Response

Path Parameters

Response

Query Parameters

Filter Presets

Query Parameters

Response

Request Body

Response (201)

Request Body

Response

Dashboard & Scheduler

Response

Query Parameters

Response

Response

Path Parameters

Response (429 if in cooldown)

Response

Notifications

Query Parameters

Response

Response

Response

Response

Response

Insights & Pricing

Response

Path Parameters

Response

Query Parameters

Response

Job History

Query Parameters