Connector Ingest

Customer-owned connectors run outside Telematics Core. They map third-party fleet systems into Telematics Core ingest payloads.

Required HMAC Headers

Content-Type: application/json
X-Connector-Key: <connector-key>
X-Ingest-Timestamp: <utc-iso-timestamp>
X-Ingest-Nonce: <unique-nonce>
X-Ingest-Signature: v1=<hex-hmac-sha256>

Signature Base String

v1
<HTTP_METHOD>
<PATH>
<X-Ingest-Timestamp>
<X-Ingest-Nonce>
<sha256 hex of raw request body>

The path must be exact. For telemetry, use /ingest/http/raw.

Endpoints

Debug Logs

GET /ingest/http/logs is signed with the same HMAC headers. Use an empty raw body for the signature and sign the path /ingest/http/logs without the query string.

The response is scoped to the authenticated connector and includes recent raw ingest receipts, staged provisioning items, and hints such as missing platform vehicleId when telemetry was accepted but cannot be normalized yet.

External ID Mapping

Connector telemetry can send third-party IDs only. Use payloadJson.externalVehicleId and payloadJson.externalDriverId. After the matching staged vehicle or driver is applied in admin-web, ingest resolves those external IDs to platform vehicleId and driverUserId before normalization. Normal connectors should not persist platform UUID mappings just to send GPS or CAN telemetry.

Driver Provisioning

Use POST /ingest/http/provisioning/drivers to stage drivers from a vendor system before sending driver-bound telemetry or tachograph data. Admins review staged drivers in the connector provisioning queue. Applying a driver creates or reuses a platform user, creates an active driver membership, and assigns the customer-scoped driver role.

{
  "drivers": [
    {
      "externalId": "vendor-driver-456",
      "email": "driver@example.com",
      "displayName": "Driver One",
      "tachographCardNumber": "D12345678901234",
      "temporaryPassword": "change-me-on-first-login",
      "phone": "+38640111222"
    }
  ]
}

After the driver item is applied, normal GPS/CAN/tacho telemetry can keep using payloadJson.externalDriverId. Telematics Core resolves it to driverUserId during ingest when the applied provisioning item has a user mapping.

Tachograph Data

There are two connector paths for tachograph-related data.

Tachograph download callbacks are HMAC-signed like other ingest requests. Use resultStatus values completed, unsupported, or failed. For completed downloads, include one artifact body as artifactJson, artifactText, or artifactBase64. The ingest service stores the artifact, deduplicates by artifactKey when provided, and returns duplicate status for repeated callbacks.

{
  "connectorKey": "fleet-http-primary",
  "customerId": "customer-uuid",
  "vehicleId": "platform-vehicle-uuid",
  "driverUserId": "platform-driver-user-uuid",
  "sessionId": "optional-session-uuid",
  "downloadedAt": "2026-05-16T11:45:00.000Z",
  "resultStatus": "completed",
  "artifact": {
    "artifactKey": "vendor-download-123",
    "fileName": "driver-card-D12345678901234.ddd.json",
    "contentType": "application/json",
    "artifactJson": {
      "cardNumber": "D12345678901234",
      "events": []
    },
    "metadata": {
      "source": "vendor-api"
    }
  },
  "metadata": {
    "vendorDownloadId": "download-123"
  }
}

If the vendor only has external driver or vehicle IDs, stage and apply those entities first, then use raw telemetry with externalVehicleId and externalDriverId. The download-result endpoint currently expects platform UUIDs for vehicleId, driverUserId, deviceId, and sessionId when those fields are supplied.

For GPS telemetry, include payloadJson.occurredAt and set top-level eventTs to the same timestamp. Use heading or headingDegrees for bearing. payloadJson.raw is optional and is only for preserving the original vendor record during debugging.

{
  "connectorKey": "fleet-http-primary",
  "customerId": "customer-uuid",
  "endpoint": "/ingest/http/raw",
  "eventTs": "2026-05-16T11:30:27.000Z",
  "payloadJson": {
    "kind": "gps",
    "occurredAt": "2026-05-16T11:30:27.000Z",
    "externalVehicleId": "A34054EF-334E-43E4-B852-24924DCB2D1E",
    "latitude": 46.1252022,
    "longitude": 15.5775185,
    "speedKph": 0,
    "heading": 264
  }
}

Minimal CAN payload:

{
  "connectorKey": "fleet-http-primary",
  "customerId": "customer-uuid",
  "endpoint": "/ingest/http/raw",
  "eventTs": "2026-05-16T11:30:27.000Z",
  "payloadJson": {
    "kind": "can",
    "occurredAt": "2026-05-16T11:30:27.000Z",
    "externalVehicleId": "A34054EF-334E-43E4-B852-24924DCB2D1E",
    "signals": [
      { "signalName": "engine_rpm", "signalValue": 1420, "unit": "rpm" },
      { "signalName": "fuel_level", "signalValue": 62.5, "unit": "percent" },
      { "signalName": "ignition", "signalValue": true },
      { "signalName": "water_temp", "signalValue": 86, "unit": "celsius" },
      { "signalName": "consumption", "signalValue": 18422.7, "unit": "liters" },
      { "signalName": "odometer", "signalValue": 440465.32, "unit": "km" },
      { "signalName": "engine_hours", "signalValue": 9821.5, "unit": "hours" },
      { "signalName": "adblue_level", "signalValue": 74, "unit": "percent" }
    ]
  }
}

Recommended CAN signal names are engine_rpm, fuel_level, ignition, water_temp, consumption, odometer, engine_hours, and adblue_level. consumption is the cumulative total fuel consumed by the vehicle, not average fuel economy.

Retry Rules

Retry 429 and 5xx with exponential backoff. Generate a new nonce and signature for each retry. Stop on 401 and 403 until credentials or connector status are fixed.

Idempotency

Telemetry deduplicates by connector, path, payload hash, identifiers, and event timestamp. Provisioning deduplicates by connector, customer, resource type, and externalId.