إنتقل إلى المحتوى الرئيسي

Fuel: vehicles, tanks, tank events

6 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.

Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.

Set a vehicle's fuel profile​

PUT /v1/fuel/vehicles/{vehicleId}/profile

  • Scope: fuel:write or fuel:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: vehicleId.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
productstring
tankLitresnumber
expectedL100kmnumber

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
vehicleId—
productstring
tankLitresnumber
expectedL100kmnumber
updatedAtstring

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X PUT "https://api.zaitrack.app/v1/fuel/vehicles/$VEHICLE_ID/profile" \
-H "Authorization: Bearer zk_test_…" \
-H "Content-Type: application/json" \
-d '{"product": "…", "tankLitres": 0, "expectedL100km": 0}'

Tank levels across the fleet​

GET /v1/fuel/tanks

  • Scope: fuel:read or fuel:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray of object
items[].vehicleId—
items[].source—
items[].capacityL—
items[].calibration—
items[].refuelMinL—
items[].drainMinL—
items[].updatedAtstring
items[].version—
items[].last—
items[].levelPct—

Example​

curl "https://api.zaitrack.app/v1/fuel/tanks" \
-H "Authorization: Bearer zk_test_…"

A vehicle's tank​

GET /v1/fuel/vehicles/{vehicleId}/tank

  • Scope: fuel:read or fuel:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: vehicleId.

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
vehicleId—
source—
capacityL—
calibration—
refuelMinL—
drainMinL—
updatedAtstring
version—
last—
levelPct—

Example​

curl "https://api.zaitrack.app/v1/fuel/vehicles/$VEHICLE_ID/tank" \
-H "Authorization: Bearer zk_test_…"

Set a vehicle's tank​

PUT /v1/fuel/vehicles/{vehicleId}/tank

  • Scope: fuel:write or fuel:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
  • If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: vehicleId.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
sourcestring
capacityLnumber
calibrationarray of object
calibration[].rawnumber
calibration[].litresnumber
refuelMinLnumber
drainMinLnumber

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of A vehicle's tank.

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X PUT "https://api.zaitrack.app/v1/fuel/vehicles/$VEHICLE_ID/tank" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"source": "…", "capacityL": 0, "calibration": [], "refuelMinL": 0, "drainMinL": 0}'

A vehicle's fuel level over time​

GET /v1/fuel/vehicles/{vehicleId}/levels

  • Scope: fuel:read or fuel:*
  • Rate class: telemetry (10 per second and 180,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: vehicleId.

Query parameterTypeNotes
pointsstring
fromstring
tostring

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray of object
items[].atstring
items[].litres—
items[].moving—
items[].lat—
items[].lon—

Example​

curl "https://api.zaitrack.app/v1/fuel/vehicles/$VEHICLE_ID/levels" \
-H "Authorization: Bearer zk_test_…"

Refuels and drains​

GET /v1/fuel/tank-events

  • Scope: fuel:read or fuel:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
Query parameterTypeNotes
kindstring
vehicleIdstring
limitstring
fromstring
tostring

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray of object
items[].id—
items[].vehicleId—
items[].kind—
items[].fromstring
items[].tostring
items[].litres—
items[].beforeL—
items[].afterL—
items[].lat—
items[].lon—
items[].transactionId—
items[].createdAtstring

Example​

curl "https://api.zaitrack.app/v1/fuel/tank-events" \
-H "Authorization: Bearer zk_test_…"