Il package @fatturazione-elettronica-aruba/nuxt fornisce l'integrazione con Nuxt tramite composables server-side auto-importati.
pnpm add @fatturazione-elettronica-aruba/nuxt
Opzioni di configurazione del modulo in nuxt.config.ts:
export default defineNuxtConfig({
modules: ['@fatturazione-elettronica-aruba/nuxt'],
fatturazioneAruba: {
environment: 'demo',
},
});
| Proprietà | Tipo | Default | Descrizione |
|---|---|---|---|
environment | 'demo' | 'production' | 'demo' | Ambiente API Aruba |
Credenziali configurabili tramite runtimeConfig:
export default defineNuxtConfig({
runtimeConfig: {
fatturazioneAruba: {
username: '',
password: '',
},
},
});
| Proprietà | Tipo | Env Variable | Descrizione |
|---|---|---|---|
username | string | NUXT_FATTURAZIONE_ARUBA_USERNAME | Username API Aruba |
password | string | NUXT_FATTURAZIONE_ARUBA_PASSWORD | Password API Aruba |
Tutti i composables sono disponibili esclusivamente nelle server routes di Nitro e vengono auto-importati.
Restituisce l'istanza singleton di ArubaClient configurata automaticamente.
function useArubaClient(): ArubaClient
Ritorna: ArubaClient - Client principale con accesso a auth e http.
Esempio:
// server/api/user.get.ts
export default defineEventHandler(async () => {
const client = useArubaClient();
// Accesso alle info utente
const userInfo = await client.auth.getUserInfo();
return {
username: userInfo.username,
vatCode: userInfo.vatCode,
accountStatus: userInfo.accountStatus,
};
});
Restituisce l'istanza singleton di InvoicesClient per la gestione delle fatture.
function useArubaInvoices(): InvoicesClient
Ritorna: InvoicesClient - Client per operazioni sulle fatture.
Metodi disponibili:
| Metodo | Descrizione |
|---|---|
upload(params) | Carica una fattura |
findSent(params) | Cerca fatture inviate |
findReceived(params) | Cerca fatture ricevute |
downloadSent(params) | Scarica XML fattura inviata |
downloadReceived(params) | Scarica XML fattura ricevuta |
sendOutcome(params) | Invia esito committente |
Esempio:
// server/api/invoices/index.get.ts
export default defineEventHandler(async (event) => {
const invoices = useArubaInvoices();
const query = getQuery(event);
const result = await invoices.findSent({
creationDateStart: query.from as string,
creationDateEnd: query.to as string,
page: Number(query.page) || 0,
size: Number(query.size) || 20,
});
return result;
});
// 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();
const result = await invoices.upload({
dataFile: encodeBase64(body.xml),
signed: body.signed ?? false,
});
return {
success: true,
filename: result.uploadFileName,
};
});
Restituisce l'istanza singleton di NotificationsClient per le notifiche SDI.
function useArubaNotifications(): NotificationsClient
Ritorna: NotificationsClient - Client per operazioni sulle notifiche.
Metodi disponibili:
| Metodo | Descrizione |
|---|---|
findDeliveryReceipts(params) | Ricevute di consegna (RC) |
findFailedDeliveries(params) | Mancate consegne (MC) |
findRejections(params) | Notifiche di scarto (NS) |
findExpirations(params) | Decorrenze termini (DT) |
downloadNotification(params) | Scarica XML notifica |
Esempio:
// server/api/notifications/index.get.ts
export default defineEventHandler(async (event) => {
const notifications = useArubaNotifications();
const query = getQuery(event);
const [receipts, rejections] = await Promise.all([
notifications.findDeliveryReceipts({
creationDateStart: query.from as string,
creationDateEnd: query.to as string,
}),
notifications.findRejections({
creationDateStart: query.from as string,
creationDateEnd: query.to as string,
}),
]);
return {
receipts: receipts.content,
rejections: rejections.content,
};
});
Restituisce l'istanza singleton di CommunicationsClient per le comunicazioni AdE.
function useArubaCommunications(): CommunicationsClient
Ritorna: CommunicationsClient - Client per comunicazioni con l'Agenzia delle Entrate.
Metodi disponibili:
| Metodo | Descrizione |
|---|---|
uploadLiquidazione(params) | Carica liquidazione IVA |
findLiquidazioni(params) | Cerca liquidazioni |
downloadLiquidazione(params) | Scarica XML liquidazione |
uploadDatiFatture(params) | Carica dati fatture |
findDatiFatture(params) | Cerca dati fatture |
Esempio:
// server/api/liquidazioni/index.get.ts
export default defineEventHandler(async (event) => {
const communications = useArubaCommunications();
const query = getQuery(event);
const result = await communications.findLiquidazioni({
creationDateStart: query.from as string,
creationDateEnd: query.to as string,
year: query.year as string,
quarter: query.quarter as string,
});
return result;
});
Il modulo estende automaticamente i tipi di Nuxt e Nitro:
// Dichiarazione runtime config
declare module '@nuxt/schema' {
interface RuntimeConfig {
fatturazioneAruba: {
username: string;
password: string;
environment: 'demo' | 'production';
};
}
}
// Dichiarazione composables in #imports
declare module '#imports' {
export function useArubaClient(): ArubaClient;
export function useArubaInvoices(): InvoicesClient;
export function useArubaNotifications(): NotificationsClient;
export function useArubaCommunications(): CommunicationsClient;
}
Tutti i composables usano il pattern singleton per ottimizzare le performance:
// Prima chiamata: crea l'istanza
const invoices1 = useArubaInvoices();
// Chiamate successive: riusa la stessa istanza
const invoices2 = useArubaInvoices();
invoices1 === invoices2 // true
L'autenticazione viene eseguita automaticamente alla prima chiamata con le credenziali configurate in runtimeConfig.
server/api/, server/routes/, server/middleware/). Non possono essere usati in componenti Vue o nel codice client.runtimeConfig. Senza credenziali valide, le chiamate API falliranno con errore di autenticazione.