Skip to main content

Managing Cards

This guide covers all aspects of managing fuel cards through the MAES Platform SDK.

Card Lifecycle Overview​

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

Listing Cards​

Basic List​

import { MaesClient } from '@nuvoni/maes-sdk';

const client = new MaesClient({
  apiKey: process.env.MAES_API_KEY!,
  projectId: process.env.MAES_PROJECT_ID!,
});

const { docs, total } = await client.cards.list();
console.log(`Found ${total} cards`);

With Pagination​

const { docs, total } = await client.cards.list({
  page: 1,
  limit: 50,
});

With Filters​

// Filter by status
const { docs } = await client.cards.list({ status: 'active' });

// Search by license plate
const { docs } = await client.cards.list({ licensePlate: 'AB-123' });

// Full-text search
const { docs } = await client.cards.list({ search: 'John' });

Getting Card Details​

const card = await client.cards.get('card-id');

console.log(`Card: ${card.cardNumber}`);
console.log(`Status: ${card.status}`);
console.log(`Driver: ${card.driver}`);
console.log(`License Plate: ${card.licensePlate}`);
console.log(`Gasoline: ${card.authGasoline ? '✅' : '❌'}`);
console.log(`Diesel: ${card.authDiesel ? '✅' : '❌'}`);
console.log(`LPG: ${card.authLpg ? '✅' : '❌'}`);
console.log(`Heating Oil: ${card.authHeatingOil ? '✅' : '❌'}`);

Activating a New Card​

New cards from MAES need to be activated before use.

Requirements​

  • Card must have status: new
  • License plate is required
  • Driver name is required

Example​

const card = await client.cards.activate('card-id', {
  licensePlate: 'AB-123-CD',
  driver: 'John Doe',
});

console.log(`Card activated: ${card.status}`); // 'active'
// All fuel authorizations are enabled by default

Common Errors​

import { MaesValidationError, MaesApiError } from '@nuvoni/maes-sdk';

try {
  await client.cards.activate('card-id', {
    licensePlate: 'AB-123-CD',
    driver: 'John Doe',
  });
} catch (error) {
  if (error instanceof MaesValidationError) {
    console.log('Validation error:', error.message);
  } else if (error instanceof MaesApiError) {
    if (error.code === 'error.card_already_active') {
      console.log('Card is already activated');
    }
  }
}

Enabling Fuel Authorization​

Re-enables fuel for a disabled card.

const card = await client.cards.enable('card-id');

console.log(`Status: ${card.status}`); // 'active'
console.log(`Gasoline: ${card.authGasoline}`); // true
console.log(`Diesel: ${card.authDiesel}`); // true

Disabling Fuel Authorization​

Disables all fuel types for a card.

const card = await client.cards.disable('card-id');

console.log(`Status: ${card.status}`); // 'inactive'
console.log(`Gasoline: ${card.authGasoline}`); // false
console.log(`Diesel: ${card.authDiesel}`); // false

Batch Operations​

For multiple cards, process them in sequence with error handling:

async function disableMultipleCards(cardIds: string[]) {
  const results = [];

  for (const cardId of cardIds) {
    try {
      await client.cards.disable(cardId);
      results.push({ cardId, success: true });
    } catch (error) {
      results.push({
        cardId,
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      });
    }

    // Respect rate limits
    await new Promise((r) => setTimeout(r, 100));
  }

  return results;
}

Monitoring Card Sync​

Cards are synced from MAES portal periodically. Check sync status:

const card = await client.cards.get('card-id');

switch (card.syncStatus) {
  case 'synced':
    console.log(`Last synced: ${card.lastSyncedAt}`);
    break;
  case 'pending':
    console.log('Sync in progress...');
    break;
  case 'failed':
    console.log(`Sync failed: ${card.syncErrorMessage}`);
    break;
}

Best Practices​

  1. Cache card data — Avoid fetching the same card repeatedly
  2. Handle rate limits — Implement delays in batch operations
  3. Use webhooks — Instead of polling for status changes
  4. Validate locally — Check card status before API calls
  5. Log operations — Keep records for debugging