Integrazioni

Nuxt Module

Integrazione con Nuxt

Nuxt Module

Il modulo @fatturazione-elettronica-aruba/nuxt permette di integrare l'SDK direttamente nelle applicazioni Nuxt con composables auto-importati e configurazione semplificata.

Caratteristiche

  • Composables server-side only per sicurezza
  • Auto-import nelle server routes di Nitro
  • Supporto TypeScript completo
  • Autenticazione OAuth2 automatica
  • Configurazione tramite runtimeConfig

Installazione

pnpm add @fatturazione-elettronica-aruba/nuxt

Configurazione

Aggiungi il modulo a nuxt.config.ts:

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

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

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

Variabili d'Ambiente

Per sicurezza, le credenziali devono essere impostate tramite variabili d'ambiente:

NUXT_FATTURAZIONE_ARUBA_USERNAME=tuo_username
NUXT_FATTURAZIONE_ARUBA_PASSWORD=tua_password

Composables

Il modulo fornisce composables server-side auto-importati nelle server routes di Nitro.

useArubaClient

Restituisce l'istanza principale di ArubaClient:

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

useArubaInvoices

Gestione fatture elettroniche:

// 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

Gestione notifiche SDI:

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

  // Ricevute di consegna (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();

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

useArubaCommunications

Comunicazioni con l'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',
  });
});

Esempio Completo

Ecco un esempio di API per gestire le fatture:

// 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,
  };
});

Sicurezza

Tutti i composables sono server-side only e non possono essere usati nel codice client-side. Le credenziali API non vengono mai esposte al browser.
Non esporre mai le credenziali Aruba nel codice client o in repository pubblici. Usa sempre le variabili d'ambiente.

TypeScript

Il modulo include dichiarazioni TypeScript complete. I composables sono tipizzati automaticamente:

// I tipi sono inferiti automaticamente
const invoices = useArubaInvoices();
//    ^? InvoicesClient

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

Differenze con l'SDK Standard

AspettoSDK StandardNuxt Module
InizializzazioneManualeAutomatica
AutenticazioneManualeAutomatica
ConfigurazioneCodicenuxt.config.ts
AmbienteRuntimeBuild + Runtime
SingletonDa implementareIncluso