API Documentation
REST API for Mercedes DFE data extraction, credit monitoring, wholesale tracking, enquiry management, and analytics.
Getting Started
Get an API Key
Go to Settings in the web app and scroll to the API Keys section. Click "Create New Key", give it a name, and copy the key. The key is shown only once — store it securely.
Or via API: POST /api/v1/keys (requires web session auth)
Authenticate with DFE
For DFE data access (markets, extraction), get a session token:
Response: {"session_token": "abc123...", "expires_at": "..."} (valid for 8 hours)
Make API Calls
Include the API key (and session token for DFE endpoints) in every request:
Authentication
Three authentication methods depending on the endpoint type:
API Key X-API-Key Header
Required for all /api/v1/* external endpoints. Pass via X-API-Key header or ?api_key= query param. Create keys in Settings.
Session X-Session-Token Header
Required for DFE operations (markets, dealers, extraction). Get a token via POST /api/v1/auth/login. Expires in 8 hours. Always requires API key too.
Headers
Request Body
Response (200)
Headers
Response
Request Body
Response
Sections
- Authentication
- Markets & Dealers (3)
- Extraction (3)
- Files (4)
- Credit Balance (4)
- Wholesale Tracking (7)
- Enquiries (11)
- Enquiry Analytics (8)
- Filter Presets (5)
- Dashboard & Scheduler (5)
- Notifications (5)
- Insights & Pricing (8)
- Job History (4)
- Customs Documents (10)
- Reference & API Keys (5)
- User Management (4)
Markets & Dealers
| Param | Type | Description |
|---|---|---|
| mpc | string | Market code (e.g. EG02) |
Extraction
Request Body
Response
Files
Returns parsed JSON by default. Add ?raw=true for raw file download.
Returns an Excel binary with styled headers and auto-adjusted columns.
Credit Balance
| Param | Type | Default | Description |
|---|---|---|---|
| date_from | YYYY-MM-DD | today | Start date |
| date_to | YYYY-MM-DD | today | End date |
| changes_only | bool | true | Only snapshots where balance changed |
| page | int | 1 | Page number |
| per_page | int | 20 | Items per page |
| Param | Type | Description |
|---|---|---|
| date | YYYY-MM-DD | Single date (or use date_from/date_to) |
| date_from | YYYY-MM-DD | Range start |
| date_to | YYYY-MM-DD | Range end |
Subject to 1-minute cooldown. Returns 429 if in cooldown.
Wholesale Tracking
| Param | Type | Description |
|---|---|---|
| date_from / date_to | YYYY-MM-DD | Filter by vehicle wholesale date |
| page / per_page | int | Pagination |
| Param | Type | Description |
|---|---|---|
| batch_id | int | Batch ID (path) |
| date_from / date_to | YYYY-MM-DD | Optional wholesale date filter |
| Param | Type | Description |
|---|---|---|
| search | string | Search commission, VIN, model |
| date_from / date_to | YYYY-MM-DD | Wholesale date range |
| page / per_page | int | Pagination |
Subject to 1-minute cooldown.
Live-query the DFE wholesale report. Requires active DFE login. No cooldown.
Request Body
Response
Enquiries
Query Parameters
| Param | Type | Default | Description |
|---|---|---|---|
| group | csv | - | Vehicle group(s) |
| nst | csv | - | Model number(s) / NST |
| search | string | - | Search commission, VIN, model, location, salesperson |
| colour | csv | - | Colour filter |
| location | csv | - | Location filter |
| sales_person | csv | - | Sales person (use "(No Sales Person)" for null) |
| sales_type | csv | - | Sales type (use "(No Sales Type)" for null) |
| price_min / price_max | number | - | Wholesale price range |
| stock_date_from / stock_date_to | YYYY-MM-DD | - | MBEg stock date range |
| days_min / days_max | int | - | Days in stock range |
| model_year | csv | - | Model year filter (e.g. MY26,MY27) |
| sort | string | commission_number | Sort column |
| order | asc/desc | asc | Sort order |
| page / per_page | int | 1 / 20 | Pagination |
Sort columns: commission_number, vin, model_description, model_year, colour, wholesale_price, mbeg_stock_date, location, sales_person_name
Response includes: vehicles, pagination, and metrics (total_count, total_value, group_count, group_stats per-group breakdown).
source: "dfe" (live), "cache", or "snapshots" (fallback)
Subject to 1-minute cooldown.
| Param | Type | Default |
|---|---|---|
| date | YYYY-MM-DD | today |
| Param | Type | Default |
|---|---|---|
| date | YYYY-MM-DD | today |
Same filter params as /api/enquiries/vehicles, plus preset name. Returns .xlsx with one sheet per vehicle group, plus additional tabs grouped by Model Year.
Enquiry Analytics
All analytics endpoints accept the same vehicle filter params as /api/enquiries/vehicles.
| Param | Type | Default | Options |
|---|---|---|---|
| dimension | string | vehicle_group | vehicle_group, colour, location, sales_person_name, vehicle_usage_desc, sales_type_desc, damage_level, model_description, trim |
| Param | Type | Default |
|---|---|---|
| date_from | YYYY-MM-DD | 30 days ago |
| date_to | YYYY-MM-DD | today |
| group | csv | all |
| Param | Type |
|---|---|
| date_from / date_to | YYYY-MM-DD |
| group, colour, location | csv |
| Param | Type | Default |
|---|---|---|
| bins | int | 10 (3-30) |
| Param | Type | Default |
|---|---|---|
| metric | string | count (or value) |
| limit | int | 10 (1-50) |
Filter Presets
| Param | Type | Description |
|---|---|---|
| type required | string | e.g. enquiry_filter, wholesale_filter |
Increments use_count and returns preset with filters.
Dashboard & Scheduler
| Param | Type | Default |
|---|---|---|
| date | YYYY-MM-DD | today |
Valid types: check_balance, scrape_wholesale
Notifications
| Param | Type | Default |
|---|---|---|
| limit | int | 20 |
Insights & Pricing
Path param date_str in YYYY-MM-DD. Returns persisted or live summary.
| Param | Type | Description |
|---|---|---|
| from required | YYYY-MM-DD | Start |
| to required | YYYY-MM-DD | End |
Aggregates daily summaries for the current month. Returns month-level totals plus a daily_breakdown array for charting.
| Param | Type | Description |
|---|---|---|
| year_month | YYYY-MM | Target month (path param) |
Same response shape as /api/insights/month/current.
| Param | Type | Description |
|---|---|---|
| from required | YYYY-MM | Start month |
| to required | YYYY-MM | End month |
Returns totals only (no daily_breakdown) for overview grids.
Job History
| Param | Type | Default |
|---|---|---|
| type | string | all |
| page / per_page | int | 1 / 20 |
Full details for a single scheduler job.
| Param | Type | Default |
|---|---|---|
| limit | int | 30 |
Customs Documents
Upload, parse, and search Egyptian customs/traffic publication PDFs. Extracted vehicle data (VIN, declaration, outgoing numbers) is cross-linked with enquiries and wholesale records.
Upload one or more customs PDF files for parsing. Vehicles (VINs starting with 'W') are extracted and stored. Invoice and shipment numbers are parsed from the Arabic filename.
Request
Response
Same as above but uses web session auth (for the drag-and-drop UI upload). Accepts multipart/form-data with files field.
Response
| Param | Type | Default |
|---|---|---|
| page | int | 1 |
| per_page | int | 15 |
Response
| Param | Type | Desc |
|---|---|---|
| download | flag | Add ?download to force download |
Returns the PDF file with Content-Type: application/pdf. Used by the PDF.js viewer for inline display.
Request
Response
Upload an Excel file (billing sheet). VINs are extracted from column Y (index 25). Returns the same cross-linked results as /api/customs/search.
Re-parses all uploaded customs PDFs to update row bounding boxes and vehicle data. Use after deploying parser fixes.
Reference & API Keys
| Param | Type |
|---|---|
| status | completed, failed, stopped |
| limit | int |
Request
Response (key shown only once!)
User Management
All endpoints require admin role via web session.
OpenAPI & Swagger
Full OpenAPI 3.0 specification with all endpoints, parameters, and schemas: