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

Vehicles: basics, devices, drivers, status history

7 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.

Put a vehicle in service mode​

POST /v1/vehicles/{id}:service

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

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
reasonstring

Response​

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

FieldTypeNotes
idstring
tenantIdstring
subOrgIdstringomitted when empty
vinstringomitted when empty
registrationobjectomitted when empty
registration.countrystring
registration.platestring
makestring
modelstring
yearinteger
assetClassstring
statusstring
capabilitiesarray of string
currentRegionstringomitted when empty
odometerKminteger
capacityTonsnumber
fuelTypestring
primaryDriverIdstringomitted when empty
attachedDevicesarray of string
markerIconstring
markerIconSetboolean
speedLimitKphintegermay be null
createdAtstring
updatedAtstring
versioninteger
etagstring

Example​

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

curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID:service" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "…"}'

Return a vehicle to normal mode​

POST /v1/vehicles/{id}:normal

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

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

The same fields as the request of Put a vehicle in service mode.

Response​

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

The same fields as the response of Put a vehicle in service mode.

Example​

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

curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID:normal" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason": "…"}'

Devices bound to a vehicle​

GET /v1/vehicles/{id}/devices

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

Path parameters: id.

Request​

No body.

Response​

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

Keys: items. Their types are not described.

Example​

curl "https://api.zaitrack.app/v1/vehicles/$ID/devices" \
-H "Authorization: Bearer zk_test_…"

Bind a device to a vehicle​

POST /v1/vehicles/{id}/devices

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

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
deviceIdstring

Response​

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

The same fields as the response of Put a vehicle in service mode.

Example​

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

curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID/devices" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"deviceId": "…"}'

Unbind a device from a vehicle​

DELETE /v1/vehicles/{id}/devices/{deviceId}

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

Path parameters: id, deviceId.

Request​

No body.

Response​

204: no body.

Example​

curl -X DELETE "https://api.zaitrack.app/v1/vehicles/$ID/devices/$DEVICE_ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"'

Assign a driver to a vehicle​

POST /v1/vehicles/{id}/drivers

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

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
driverIdstring

Response​

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

The same fields as the response of Put a vehicle in service mode.

Example​

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

curl -X POST "https://api.zaitrack.app/v1/vehicles/$ID/drivers" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"driverId": "…"}'

Vehicle status changes over a period​

GET /v1/vehicles/status-history

  • Scope: vehicles:read or vehicles:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
Query parameterTypeNotes
vehicleIdstring
from—
to—

Request​

No body.

Response​

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

FieldTypeNotes
itemsarray of object
items[].vehicleId—
items[].status—
items[].reason—
items[].actor—
items[].at—

Example​

curl "https://api.zaitrack.app/v1/vehicles/status-history" \
-H "Authorization: Bearer zk_test_…"