Integrations

Nuxt Module

Integration with Nuxt

Nuxt Module

The @fatturazione-elettronica-aruba/nuxt module allows you to integrate the SDK directly into Nuxt applications with auto-imported composables and simplified configuration.

Features

  • Server-side only composables for security
  • Auto-import in Nitro server routes
  • Full TypeScript support
  • Automatic OAuth2 authentication
  • Configuration via runtimeConfig

Installation

pnpm add @fatturazione-elettronica-aruba/nuxt

Configuration

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@fatturazione-elettronica-aruba/nuxt'],

  fatturazioneAruba: {
    environment: 'demo', // or 'production'
  },

  runtimeConfig: {
    fatturazioneAruba: {
      username: '', // Use NUXT_FATTURAZIONE_ARUBA_USERNAME
      password: '', // Use NUXT_FATTURAZIONE_ARUBA_PASSWORD
    },
  },
});

Environment Variables

For security, credentials should be set via environment variables:

NUXT_FATTURAZIONE_ARUBA_USERNAME=your_username
NUXT_FATTURAZIONE_ARUBA_PASSWORD=your_password

Composables

The module provides server-side composables that are auto-imported in Nitro server routes.

useArubaClient

Returns the main ArubaClient instance:

// server/api/user.get.ts
export default defineEventHandler(async () => {
  const client = useArubaClient();
  return await client.auth.getUserInfo();
});

useArubaInvoices

Manage electronic invoices:

// server/api/invoices/sent.get.ts
export default defineEventHandler(async () => {
  const invoices = useArubaInvoices();

  return await invoices.findSent({
    creationDateStart: '2024-01-01',
    creationDateEnd: '2024-12-31',
  });
});
// server/api/invoices/upload.post.ts
import { encodeBase64 } from '@fatturazione-elettronica-aruba/utils';

export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  const invoices = useArubaInvoices();

  return await invoices.upload({
    dataFile: encodeBase64(body.xml),
    signed: false,
  });
});

useArubaNotifications

Handle SDI notifications:

// server/api/notifications/receipts.get.ts
export default defineEventHandler(async () => {
  const notifications = useArubaNotifications();

  // Delivery receipts (RC)
  const receipts = await notifications.findDeliveryReceipts({
    creationDateStart: '2024-01-01',
    creationDateEnd: '2024-12-31',
  });

  return receipts;
});
// server/api/notifications/rejections.get.ts
export default defineEventHandler(async () => {
  const notifications = useArubaNotifications();

  // Rejection notices (NS)
  return await notifications.findRejections({
    creationDateStart: '2024-01-01',
    creationDateEnd: '2024-12-31',
  });
});

useArubaCommunications

Communications with Agenzia delle Entrate:

// server/api/communications/liquidazioni.get.ts
export default defineEventHandler(async () => {
  const communications = useArubaCommunications();

  return await communications.findLiquidazioni({
    creationDateStart: '2024-01-01',
    creationDateEnd: '2024-12-31',
  });
});

Complete Example

Here's an example API for managing invoices:

// server/api/fatture/index.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const invoices = useArubaInvoices();

  const { year, month } = query;
  const startDate = `${year}-${month.toString().padStart(2, '0')}-01`;
  const endDate = `${year}-${month.toString().padStart(2, '0')}-31`;

  const [sent, received] = await Promise.all([
    invoices.findSent({
      creationDateStart: startDate,
      creationDateEnd: endDate,
    }),
    invoices.findReceived({
      creationDateStart: startDate,
      creationDateEnd: endDate,
    }),
  ]);

  return {
    sent: sent.content,
    received: received.content,
    totals: {
      sent: sent.totalElements,
      received: received.totalElements,
    },
  };
});
// server/api/fatture/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id');
  const invoices = useArubaInvoices();

  const xml = await invoices.downloadSent({
    filename: id,
  });

  return {
    filename: id,
    xml,
  };
});

Security

All composables are server-side only and cannot be used in client-side code. API credentials are never exposed to the browser.
Never expose Aruba credentials in client code or public repositories. Always use environment variables.

TypeScript

The module includes complete TypeScript declarations. Composables are automatically typed:

// Types are automatically inferred
const invoices = useArubaInvoices();
//    ^? InvoicesClient

const result = await invoices.findSent({ ... });
//    ^? PagedResponse<SentInvoice>

Differences from Standard SDK

AspectStandard SDKNuxt Module
InitializationManualAutomatic
AuthenticationManualAutomatic
ConfigurationCodenuxt.config.ts
EnvironmentRuntimeBuild + Runtime
SingletonTo implementIncluded