Cards

Cards represent physical MAES fuel cards that can be managed through the API.

Card Lifecycle

┌─────────┐      activate()      ┌─────────┐
│   NEW   │ ──────────────────►  │  ACTIVE │
└─────────┘                      └────┬────┘
                                      │
                          ┌───────────┴───────────┐
                          │                       │
                     disable()                enable()
                          │                       │
                          ▼                       │
                    ┌──────────┐                  │
                    │ INACTIVE │ ─────────────────┘
                    └──────────┘

Card Statuses

Status	Description	Can Enable	Can Disable
new	Card synced but not yet activated	❌	❌
active	Card activated with fuel enabled	❌	✅
inactive	Card activated but fuel disabled	✅	❌

Card Properties

Property	Type	Description
id	UUID	Unique identifier
cardNumber	string	Physical card number
maesCardId	string	MAES internal ID
environment	enum	sandbox or production
status	enum	new, active, inactive
licensePlate	string	Vehicle license plate
driver	string	Driver name
expirationDate	datetime	Card expiration date
authGasoline	boolean	Gasoline authorization
authDiesel	boolean	Diesel authorization
authLpg	boolean	LPG authorization
authHeatingOil	boolean	Heating oil authorization
syncStatus	enum	synced, pending, failed
lastSyncedAt	datetime	Last sync timestamp

Fuel Authorizations

Each card has four fuel type authorizations:

Authorization	Description
authGasoline	Gasoline/Petrol (E5/E10)
authDiesel	Diesel fuel
authLpg	LPG/Autogas
authHeatingOil	Heating oil

When you enable a card, all four authorizations are set to true. When you disable a card, all four are set to false.

Card Operations

Activate a Card

Activates a new card with license plate and driver information.

POST /projects/{projectId}/cards/{cardId}/activate
{
  "licensePlate": "AB-123-CD",
  "driver": "John Doe"
}

info

Only cards with status: new can be activated. After activation, all fuel authorizations are enabled by default.

Enable a Card

Enables all fuel authorizations for an inactive card.

POST /projects/{projectId}/cards/{cardId}/enable

Disable a Card

Disables all fuel authorizations for an active card.

POST /projects/{projectId}/cards/{cardId}/disable

Sync Status

Cards are synced from MAES portal in the background:

Sync Status	Description
synced	Data is up-to-date with MAES
pending	Operation in progress
failed	Sync failed (check syncErrorMessage)

Example Card Object

{
  "id": "09c9861c-4c4b-411f-be85-c16ed7e26da4",
  "cardNumber": "782521009000153700",
  "maesCardId": "134208",
  "environment": "production",
  "status": "active",
  "licensePlate": "AB-123-CD",
  "driver": "John Doe",
  "expirationDate": "2027-12-31T00:00:00.000Z",
  "authGasoline": true,
  "authDiesel": true,
  "authLpg": true,
  "authHeatingOil": true,
  "syncStatus": "synced",
  "lastSyncedAt": "2025-12-27T16:24:05.712Z",
  "createdAt": "2025-12-26T10:30:00.000Z",
  "updatedAt": "2025-12-27T16:24:05.712Z"
}