DriverCard REST API

1. Purpose

The DriverCard API exposes the same parsed driver-card data used by the FLEET Mira desktop analysis. It is intended for local integration and the bundled web week view. It does not modify archived originals.

Default base URL: http://127.0.0.1:5055. Start/stop/open/log commands are available under System. Binding beyond loopback requires an external TLS/authentication gateway and an explicit risk assessment.

2. Time, formats and filters

• timestamps are ISO 8601 UTC;
• dates are YYYY-MM-DD;
• durations are integer seconds unless stated otherwise;
• card numbers are normalised strings;
• JSON uses UTF-8;
• validation errors return JSON with error and a readable message.

Common query parameters:

Parameter	Meaning
import_id	parsed import identifier
archive_id	stable tachodata archive identifier
card_number	exact normalised card number
date_from, date_to	inclusive UTC date range
limit, offset	bounded pagination where supported

3. Endpoints

Method and path	Function
GET /health	process and database readiness
POST /api/drivercard/parse	parse a supplied DDD payload and persist/reuse its import
GET /api/drivercard/imports	list parsed driver-card imports
GET /api/drivercard/time-summary	activity totals by type
GET /api/drivercard/activities	activity intervals
GET /api/drivercard/events	card events
GET /api/drivercard/faults	card faults
GET /api/drivercard/vehicles-used	vehicles recorded on the card
GET /api/drivercard/positions	recorded positions
GET /api/drivercard/day-overview	prepared day data
GET /api/drivercard/week-overview	prepared ISO-week data
GET /api/drivercard/eu561/violations	technical EU 561/2006 pre-check

4. Health

GET /health HTTP/1.1
Host: 127.0.0.1:5055

{"status":"ok","service":"drivercard-rest","database":"available"}

5. Parse a driver card

POST /api/drivercard/parse accepts JSON. The desktop web preload uses base64 so no local archive path appears in the browser URL.

{
  "file_name": "C_20250715_0615_Demo_1000000000000001.DDD",
  "content_base64": "BASE64_DATA",
  "archive_id": "optional-stable-id"
}

The response identifies import/archive, driver/card metadata, activity range and parser warnings. Binary input, signatures and certificates are never echoed. A repeated identical payload is idempotent by hash.

6. Activities and summaries

GET /api/drivercard/activities?archive_id=ARCHIVE_ID&date_from=2025-07-14&date_to=2025-07-20

Activity rows contain start/end UTC, activity code (DRIVING, WORK, AVAILABILITY, REST), duration, card, crew and slot information. Day/week endpoints return the same source intervals grouped for visualisation; they are not separate evidence records.

7. Events, faults, vehicles and positions

Event/fault responses include technical type/code, start/end and readable description where known. Unknown standard extensions remain represented by the technical code. Position rows contain timestamp, latitude, longitude, source/type, country/region codes and optional odometer.

8. EU 561/2006 pre-check

The endpoint evaluates only the selected data basis. Its response includes driver summary, violations, warnings, rule/algorithm version and data-gap notices. It is a technical pre-check, not an authority/legal decision. National exceptions, AETR and Article 12 circumstances are not decided automatically.

9. HTTP status codes

Status	Meaning
200	successful query or idempotent parse
400	malformed payload/filter
404	archive/import not found
409	conflicting or quarantined data for the requested trusted operation
413	payload too large for configured limit
422	DDD content cannot be parsed
500	unexpected internal failure; correlate with REST log

10. Security and operation

• Keep loopback binding unless a protected integration gateway is deployed.
• Do not put DDD data or local paths in query strings.
• Restrict REST log access; logs are English and exclude raw DDD/secrets.
• Stop the API through FLEET Mira before maintenance.
• API paths and response field names retain their technical compatibility even though the visible product is FLEET Mira.