Riferimento API

Utils

Funzioni di utilità e costanti per lavorare con le API di Fatturazione Elettronica Aruba.

Package Utils

Il package @fatturazione-elettronica-aruba/utils fornisce funzioni helper e costanti per le operazioni comuni quando si lavora con le API Aruba.

Installazione

pnpm add @fatturazione-elettronica-aruba/utils

Funzioni Base64

encodeBase64

Codifica una stringa o dati binari in Base64. Usata per l'upload delle fatture alle API.

function encodeBase64(data: string | Uint8Array): string

Parametri:

NomeTipoDescrizione
datastring | Uint8ArrayI dati da codificare

Ritorna: Stringa codificata in Base64

Esempio:

import { encodeBase64 } from '@fatturazione-elettronica-aruba/utils';
import fs from 'node:fs';

// Codifica stringa
const xmlString = '<FatturaElettronica>...</FatturaElettronica>';
const encoded = encodeBase64(xmlString);

// Codifica buffer file
const fileBuffer = fs.readFileSync('fattura.xml');
const encodedFile = encodeBase64(new Uint8Array(fileBuffer));

decodeBase64

Decodifica una stringa Base64 in dati binari (Uint8Array). Usata per scaricare fatture dalle API.

function decodeBase64(base64: string): Uint8Array

Parametri:

NomeTipoDescrizione
base64stringLa stringa Base64 da decodificare

Ritorna: Dati decodificati come Uint8Array

Esempio:

import { decodeBase64 } from '@fatturazione-elettronica-aruba/utils';
import fs from 'node:fs';

// Decodifica e salva su file
const base64Data = response.file;
const binaryData = decodeBase64(base64Data);
fs.writeFileSync('fattura-scaricata.xml', binaryData);

decodeBase64ToString

Decodifica una stringa Base64 direttamente in una stringa UTF-8.

function decodeBase64ToString(base64: string): string

Parametri:

NomeTipoDescrizione
base64stringLa stringa Base64 da decodificare

Ritorna: Stringa UTF-8 decodificata

Esempio:

import { decodeBase64ToString } from '@fatturazione-elettronica-aruba/utils';

const xmlContent = decodeBase64ToString(response.file);
console.log(xmlContent); // <?xml version="1.0"?>...

Funzioni Data

formatDateISO

Formatta un oggetto Date in formato ISO 8601.

function formatDateISO(date: Date): string

Ritorna: 2024-01-15T10:30:00.000Z

formatDateOnly

Formatta un oggetto Date in formato solo data (YYYY-MM-DD).

function formatDateOnly(date: Date): string

Ritorna: 2024-01-15

Esempio:

import { formatDateOnly } from '@fatturazione-elettronica-aruba/utils';

const date = new Date();
const searchDate = formatDateOnly(date);

await invoices.findSent({
  creationStartDate: searchDate,
  creationEndDate: searchDate,
});

formatDateAruba

Formatta una Date nel formato datetime specifico di Aruba.

function formatDateAruba(date: Date): string

Ritorna: 2024-01-15 10:30:00

parseArubaDate

Analizza una stringa data nel formato Aruba e restituisce un oggetto Date.

function parseArubaDate(dateString: string): Date

Parametri:

NomeTipoDescrizione
dateStringstringData nel formato YYYY-MM-DD HH:mm:ss

Ritorna: Oggetto JavaScript Date

getDateRange

Genera un intervallo di date da N giorni fa fino ad oggi.

function getDateRange(days: number): { startDate: string; endDate: string }

Parametri:

NomeTipoDescrizione
daysnumberNumero di giorni da sottrarre

Ritorna: Oggetto con startDate e endDate in formato ISO

Esempio:

import { getDateRange } from '@fatturazione-elettronica-aruba/utils';

// Ottieni fatture degli ultimi 30 giorni
const { startDate, endDate } = getDateRange(30);

await invoices.findSent({
  creationStartDate: startDate,
  creationEndDate: endDate,
});

Costanti

SYNC_ERROR_CODES

Codici di errore sincroni restituiti immediatamente dalle API.

const SYNC_ERROR_CODES = {
  '0000': 'Operazione effettuata',
  '0001': 'Nome file già presente nel sistema',
  '0002': 'Fattura duplicata',
  '0003': 'Superato il limite di spazio',
  '0004': 'File non valido',
  '0005': 'Contenuto Base64 non valido',
  '0006': 'Tipo documento non valido',
  '0007': 'Firma non valida',
  '0008': 'Certificato scaduto',
  '0009': 'Certificato revocato',
  '0010': 'Certificato non attendibile',
  '0096': 'Servizio non disponibile',
  '0097': 'Errore interno',
  '0098': 'Timeout',
  '0099': 'Errore generico',
} as const;

ASYNC_ERROR_CODES

Codici di errore asincroni ricevuti tramite notifiche NS (scarto) dallo SDI.

const ASYNC_ERROR_CODES = {
  FATRSM200: 'File non conforme al formato',
  FATRSM201: 'Identificativo trasmissione non valido',
  FATRSM212: 'IdTrasmittente diverso da quello Aruba',
  FATRSM213: 'Codice destinatario non valido',
  FATRSM214: 'PEC destinatario non valida',
  FATRSM215: 'Formato trasmissione non supportato',
} as const;

INVOICE_STATUS

Possibili stati delle fatture.

const INVOICE_STATUS = {
  INVIATA: 'Inviata',
  CONSEGNATA: 'Consegnata',
  NON_CONSEGNATA: 'Non Consegnata',
  SCARTATA: 'Scartata',
  ACCETTATA: 'Accettata',
  RIFIUTATA: 'Rifiutata',
  DECORRENZA_TERMINI: 'Decorrenza Termini',
  ERRORE_ELABORAZIONE: 'Errore Elaborazione',
  IN_ELABORAZIONE: 'In Elaborazione',
} as const;

DOCUMENT_TYPES

Tutti i 28 codici tipo documento (TD01-TD28) con descrizioni.

const DOCUMENT_TYPES = {
  TD01: 'Fattura',
  TD02: 'Acconto/Anticipo su fattura',
  TD03: 'Acconto/Anticipo su parcella',
  TD04: 'Nota di credito',
  TD05: 'Nota di debito',
  TD06: 'Parcella',
  TD07: 'Fattura semplificata',
  TD08: 'Nota di credito semplificata',
  TD09: 'Nota di debito semplificata',
  TD10: 'Fattura per acquisto intracomunitario beni',
  TD11: 'Fattura per acquisto intracomunitario servizi',
  TD12: 'Documento riepilogativo (art. 6 DPR 695/1996)',
  TD16: 'Integrazione fattura reverse charge interno',
  TD17: 'Integrazione/autofattura acquisto servizi estero',
  TD18: 'Integrazione acquisto beni intracomunitari',
  TD19: 'Integrazione/autofattura acquisto beni art. 17 c.2 DPR 633/72',
  TD20: 'Autofattura per regolarizzazione',
  TD21: 'Autofattura per splafonamento',
  TD22: 'Estrazione beni da deposito IVA',
  TD23: 'Estrazione beni da deposito IVA con versamento IVA',
  TD24: 'Fattura differita art. 21 c.4 lett. a',
  TD25: 'Fattura differita art. 21 c.4 terzo periodo lett. b',
  TD26: 'Cessione beni ammortizzabili e passaggi interni',
  TD27: 'Fattura autoconsumo/cessioni gratuite senza rivalsa',
  TD28: 'Acquisti da San Marino con IVA',
} as const;

NOTIFICATION_TYPES

Tipi di notifica SDI.

const NOTIFICATION_TYPES = {
  RC: 'Ricevuta di Consegna',
  NS: 'Notifica di Scarto',
  MC: 'Mancata Consegna',
  NE: 'Notifica Esito',
  DT: 'Decorrenza Termini',
  AT: 'Attestazione di Trasmissione',
} as const;

ESITO_TYPES

Tipi di esito committente.

const ESITO_TYPES = {
  EC01: 'Accettazione',
  EC02: 'Rifiuto',
} as const;

COMMUNICATION_TYPES

Tipi di comunicazioni finanziarie per AdE.

const COMMUNICATION_TYPES = {
  LI: 'Comunicazione liquidazioni periodiche IVA',
  DTE: 'Dati fatture emesse',
  DTR: 'Dati fatture ricevute',
  ANN: 'Annullamento',
} as const;

TRANSMISSION_RESULTS

Codici di stato trasmissione comunicazioni.

const TRANSMISSION_RESULTS = {
  SF01: 'File ricevuto',
  SF02: 'File in elaborazione',
  SF03: 'File elaborato',
} as const;

ELABORATED_RESULTS

Risultati finali elaborazione comunicazioni.

const ELABORATED_RESULTS = {
  ES01: 'File accettato',
  ES02: 'File accettato con segnalazioni',
  ES03: 'File scartato',
} as const;