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:readorfuel:* - 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.
| Field | Type | Notes |
|---|---|---|
items | array 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[].createdAt | string | |
items[].updatedAt | string | |
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:writeorfuel:* - 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.
| Field | Type | Notes |
|---|---|---|
issuer | string | |
cardRef | string | |
last4 | string | |
label | string | optional |
status | string | optional |
vehicleId | string | optional |
driverId | string | optional |
dailyLimitCents | integer | optional |
maxLitresPerFill | number | optional |
allowedProducts | array of string | optional |
currency | string | optional |
Response
201: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
id | — | |
issuer | — | |
cardRef | — | |
last4 | — | |
label | — | |
status | — | |
vehicleId | — | |
driverId | — | |
dailyLimitCents | — | |
maxLitresPerFill | — | |
allowedProducts | — | |
currency | — | |
createdAt | string | |
updatedAt | string | |
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:readorfuel:* - 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:writeorfuel:* - 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:readorfuel:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
| Query parameter | Type | Notes |
|---|---|---|
status | string | |
pageSize | string | |
cursor | string | |
vehicleId | — | |
cardId | — | |
from | — | |
to | — |
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].id | — | |
items[].externalId | — | |
items[].source | — | |
items[].cardId | — | |
items[].vehicleId | — | |
items[].driverId | — | |
items[].stationName | — | |
items[].station | — | |
items[].purchasedAt | string | |
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[].createdAt | string | |
items[].version | — | |
nextCursor | string |
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:writeorfuel:* - 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.
| Field | Type | Notes |
|---|---|---|
externalId | string | |
cardId | string | optional |
issuer | string | |
cardRef | string | |
vehicleId | string | optional |
driverId | string | optional |
stationName | string | |
stationLat | number | optional |
stationLon | number | optional |
purchasedAt | string | |
product | string | |
litres | number | |
totalCents | integer | |
currency | string | |
odometerKm | number | optional |
Response
201 or 200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
id | — | |
externalId | — | |
source | — | |
cardId | — | |
vehicleId | — | |
driverId | — | |
stationName | — | |
station | — | |
purchasedAt | string | |
product | — | |
litres | — | |
totalCents | — | |
currency | — | |
unitPriceCents | — | |
odometerKm | — | |
status | — | |
findings | — | |
vehicleDistanceM | — | |
distanceSincePrevKm | — | |
l100km | — | |
checkedAt | — | |
reviewedBy | — | |
reviewNote | — | |
reviewedAt | — | |
createdAt | string | |
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:writeorfuel:* - 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.
| Field | Type | Notes |
|---|---|---|
transactions | array of object | |
transactions[].externalId | string | |
transactions[].cardId | string | optional |
transactions[].issuer | string | |
transactions[].cardRef | string | |
transactions[].vehicleId | string | optional |
transactions[].driverId | string | optional |
transactions[].stationName | string | |
transactions[].stationLat | number | optional |
transactions[].stationLon | number | optional |
transactions[].purchasedAt | string | |
transactions[].product | string | |
transactions[].litres | number | |
transactions[].totalCents | integer | |
transactions[].currency | string | |
transactions[].odometerKm | number | optional |
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
created | integer | |
duplicates | integer | |
rejected | — | |
errors | array 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": []}'