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

Devices: basics, track

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

A device's track is under /v1/devices/{deviceId}/track and the vehicle it is bound to under /v1/devices/{deviceId}/vehicle; both are listed on Positions and Vehicles.

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.

Bind a device to an asset​

POST /v1/devices/{id}:bind

  • Scope: devices:write or devices:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: low risk
  • Step-up MFA: no

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
kindstring
targetIdstring

Response​

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

FieldTypeNotes
idstring
tenantIdstring
externalIdstring
namestringomitted when empty
modelstring
manufacturerstring
makerIdstringomitted when empty
modelIdstringomitted when empty
codecIdstring
deviceClassstring
statusstring
firmwareVersionstringomitted when empty
capabilitiesarray of stringomitted when empty
hasCommandPasswordboolean
simobjectomitted when empty
sim.iccidstringomitted when empty
sim.msisdnstringomitted when empty
sim.operatorstringomitted when empty
sim.apnstringomitted when empty
sim.statusstringomitted when empty
reportedFirmwarestringomitted when empty
firmwareReportedAtstringomitted when empty
portableboolean
boundToobjectomitted when empty
boundTo.kindstring
boundTo.targetIdstring
boundTo.boundAtstring
createdAtstring
updatedAtstring
versioninteger

Example​

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

curl -X POST "https://api.zaitrack.app/v1/devices/$ID:bind" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"kind": "…", "targetId": "…"}'

Unbind a device​

POST /v1/devices/{id}:unbind

  • Scope: devices:write or devices:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: low risk
  • Step-up MFA: no

Path parameters: id.

Request​

No body: the handler reads none.

Response​

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

The same fields as the response of Bind a device to an asset.

Example​

curl -X POST "https://api.zaitrack.app/v1/devices/$ID:unbind" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)"

Retire a device​

POST /v1/devices/{id}:retire

  • Scope: devices:write or devices:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: medium risk
  • Step-up MFA: no

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
reasonstring

Response​

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

The same fields as the response of Bind a device to an asset.

Example​

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

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

A device's positions (?from=&to=&limit=)​

GET /v1/devices/{deviceId}/track

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

Path parameters: deviceId.

Query parameterTypeNotes
fromstring
tostring
limitstring

Request​

No body.

Response​

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

FieldTypeNotes
deviceId—
from—
to—
pointsarray of object
points[].deviceIdstring
points[].occurredAtstring (date-time)
points[].latnumber
points[].lonnumber
points[].speedKphnumbermay be null
points[].headingDegnumbermay be null
points[].ignitionbooleanmay be null
truncated—

Example​

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