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

Fuel: cards, transactions

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.

List fuel cards​

GET /v1/fuel/cards

  • 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[].id—
items[].issuer—
items[].cardRef—
items[].last4—
items[].label—
items[].status—
items[].vehicleId—
items[].driverId—
items[].dailyLimitCents—
items[].maxLitresPerFill—
items[].allowedProducts—
items[].currency—
items[].createdAtstring
items[].updatedAtstring
items[].version—

Example​

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

Register a fuel card​

POST /v1/fuel/cards

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

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
issuerstring
cardRefstring
last4string
labelstringoptional
statusstringoptional
vehicleIdstringoptional
driverIdstringoptional
dailyLimitCentsintegeroptional
maxLitresPerFillnumberoptional
allowedProductsarray of stringoptional
currencystringoptional

Response​

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

FieldTypeNotes
id—
issuer—
cardRef—
last4—
label—
status—
vehicleId—
driverId—
dailyLimitCents—
maxLitresPerFill—
allowedProducts—
currency—
createdAtstring
updatedAtstring
version—

Example​

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

curl -X POST "https://api.zaitrack.app/v1/fuel/cards" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"issuer": "…", "cardRef": "…", "last4": "…", "label": "…", "status": "…", "vehicleId": "…", "driverId": "…", "dailyLimitCents": 0, "maxLitresPerFill": 0, "allowedProducts": [], "currency": "…"}'

Get a fuel card​

GET /v1/fuel/cards/{id}

  • 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: id.

Request​

No body.

Response​

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

The same fields as the response of Register a fuel card.

Example​

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

Update a fuel card​

PATCH /v1/fuel/cards/{id}

  • Scope: fuel:write or fuel:*
  • 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.

Request​

Fields the handler reads, taken from its source.

The same fields as the request of Register a fuel card.

Response​

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

The same fields as the response of Register a fuel card.

Example​

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

curl -X PATCH "https://api.zaitrack.app/v1/fuel/cards/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"issuer": "…", "cardRef": "…"}'

List fuel transactions​

GET /v1/fuel/transactions

  • 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
statusstring
pageSizestring
cursorstring
vehicleId—
cardId—
from—
to—

Request​

No body.

Response​

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

FieldTypeNotes
itemsarray of object
items[].id—
items[].externalId—
items[].source—
items[].cardId—
items[].vehicleId—
items[].driverId—
items[].stationName—
items[].station—
items[].purchasedAtstring
items[].product—
items[].litres—
items[].totalCents—
items[].currency—
items[].unitPriceCents—
items[].odometerKm—
items[].status—
items[].findings—
items[].vehicleDistanceM—
items[].distanceSincePrevKm—
items[].l100km—
items[].checkedAt—
items[].reviewedBy—
items[].reviewNote—
items[].reviewedAt—
items[].createdAtstring
items[].version—
nextCursorstring

Example​

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

Record a fuel transaction​

POST /v1/fuel/transactions

A transaction whose externalId was recorded before is not recorded twice: the response is the existing one, with 200 instead of 201.

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

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
externalIdstring
cardIdstringoptional
issuerstring
cardRefstring
vehicleIdstringoptional
driverIdstringoptional
stationNamestring
stationLatnumberoptional
stationLonnumberoptional
purchasedAtstring
productstring
litresnumber
totalCentsinteger
currencystring
odometerKmnumberoptional

Response​

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

FieldTypeNotes
id—
externalId—
source—
cardId—
vehicleId—
driverId—
stationName—
station—
purchasedAtstring
product—
litres—
totalCents—
currency—
unitPriceCents—
odometerKm—
status—
findings—
vehicleDistanceM—
distanceSincePrevKm—
l100km—
checkedAt—
reviewedBy—
reviewNote—
reviewedAt—
createdAtstring
version—

Example​

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

curl -X POST "https://api.zaitrack.app/v1/fuel/transactions" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"externalId": "…", "cardId": "…", "issuer": "…", "cardRef": "…", "vehicleId": "…", "driverId": "…", "stationName": "…", "stationLat": 0, "stationLon": 0, "purchasedAt": "…", "product": "…", "litres": 0, "totalCents": 0, "currency": "…", "odometerKm": 0}'

Import a card provider's statement​

POST /v1/fuel/transactions/import

  • Scope: fuel:write or fuel:*
  • Rate class: bulk (100 per hour)
  • Idempotency-Key: optional
  • Audited: medium risk
  • Step-up MFA: no

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
transactionsarray of object
transactions[].externalIdstring
transactions[].cardIdstringoptional
transactions[].issuerstring
transactions[].cardRefstring
transactions[].vehicleIdstringoptional
transactions[].driverIdstringoptional
transactions[].stationNamestring
transactions[].stationLatnumberoptional
transactions[].stationLonnumberoptional
transactions[].purchasedAtstring
transactions[].productstring
transactions[].litresnumber
transactions[].totalCentsinteger
transactions[].currencystring
transactions[].odometerKmnumberoptional

Response​

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

FieldTypeNotes
createdinteger
duplicatesinteger
rejected—
errorsarray of object
errors[].line—
errors[].detail—

Example​

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

curl -X POST "https://api.zaitrack.app/v1/fuel/transactions/import" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"transactions": []}'