API Overview

The MAES Platform REST API allows you to programmatically manage fuel cards.

Base URL

https://api.maes-platform.nuvoni.eu/v1

SDK (Recommended)

We recommend using the official Node.js SDK:

npm install @nuvoni/maes-sdk

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

const client = new MaesClient({
  apiKey: 'sk_live_xxxxx',
  projectId: 'your-project-id',
});

// List cards
const { docs, total } = await client.cards.list();

// Enable a card
await client.cards.enable('card-id');

Authentication

All API requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Request Format

• Use Content-Type: application/json for request bodies
• All timestamps are in ISO 8601 format
• UUIDs are used for resource identifiers

Response Format

Success Response

{
  "id": "09c9861c-4c4b-411f-be85-c16ed7e26da4",
  "cardNumber": "782521009000153700",
  "status": "active"
}

List Response

{
  "docs": [{ "id": "...", "cardNumber": "..." }],
  "total": 150
}

Error Response

{
  "code": "error.error_type",
  "message": "Human-readable error message"
}

Pagination

List endpoints support pagination:

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page (max 100)

Rate Limiting

Environment	Limit
Sandbox	100 requests/minute
Production	Based on plan

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703693400

API Endpoints

Cards

Method	Endpoint	Description
GET	/projects/{id}/cards	List all cards
GET	/projects/{id}/cards/{cardId}	Get card details
POST	/projects/{id}/cards/{cardId}/activate	Activate a new card
POST	/projects/{id}/cards/{cardId}/enable	Enable fuel authorizations
POST	/projects/{id}/cards/{cardId}/disable	Disable fuel authorizations

Webhooks

Method	Endpoint	Description
GET	/projects/{id}/webhook	Get webhook
POST	/projects/{id}/webhook	Create webhook
PATCH	/projects/{id}/webhook	Update webhook
DELETE	/projects/{id}/webhook	Delete webhook
POST	/projects/{id}/webhook/test	Send test event
POST	/projects/{id}/webhook/rotate-secret	Rotate secret
GET	/projects/{id}/webhook/deliveries	List deliveries
POST	/projects/{id}/webhook/deliveries/{id}/retry	Retry delivery