Il package @fatturazione-elettronica-aruba/communications fornisce metodi per inviare e gestire comunicazioni finanziarie all'Agenzia delle Entrate.
pnpm add @fatturazione-elettronica-aruba/communications
import { CommunicationsClient } from '@fatturazione-elettronica-aruba/communications';
const communications = new CommunicationsClient({
httpClient: client.http,
});
Opzioni:
| Nome | Tipo | Richiesto | Descrizione |
|---|---|---|---|
httpClient | HttpClient | Sì | Istanza HTTP client da ArubaClient |
Invia una comunicazione finanziaria all'Agenzia delle Entrate.
async createTransmission(request: CreateTransmissionRequest): Promise<CreateTransmissionResponse>
Parametri:
| Nome | Tipo | Richiesto | Descrizione |
|---|---|---|---|
comunicationType | CommunicationType | Sì | Tipo di comunicazione (LI, DTE, DTR, ANN) |
dataFile | string | Sì | File XML codificato Base64 |
userId | string | No | Identificativo utente (per multi-azienda) |
Ritorna:
interface CreateTransmissionResponse {
requestId: string; // Usa questo per controllare lo stato
}
Esempio:
import { encodeBase64 } from '@fatturazione-elettronica-aruba/utils';
import fs from 'node:fs';
const xmlContent = fs.readFileSync('liquidazione-iva.xml', 'utf-8');
const response = await communications.createTransmission({
comunicationType: 'LI',
dataFile: encodeBase64(xmlContent),
});
console.log('Request ID:', response.requestId);
Recupera lo stato e i dettagli di una trasmissione.
async getTransmissionInfo(requestId: string): Promise<TransmissionInfo>
Parametri:
| Nome | Tipo | Richiesto | Descrizione |
|---|---|---|---|
requestId | string | Sì | Request ID da createTransmission |
Ritorna:
interface TransmissionInfo {
result: ResultCode; // SF01, SF02, SF03
notifyResult: string; // Dettagli notifica
elaboratedResult: ElaboratedResult | string; // ES01, ES02, ES03
receiptTimestamp: string; // Data ricezione
fileId: string; // Identificativo file
fileName: string; // Nome file originale
status: string; // Stato corrente
pddAvailable: boolean; // Se PDD è disponibile
}
Esempio:
const info = await communications.getTransmissionInfo(requestId);
console.log('Stato:', info.result);
console.log('Risultato elaborazione:', info.elaboratedResult);
if (info.elaboratedResult === 'ES03') {
console.log('File scartato');
}
Scarica il documento PDD (Prova di Deposito).
async getPdd(requestId: string): Promise<ArrayBuffer>
Parametri:
| Nome | Tipo | Richiesto | Descrizione |
|---|---|---|---|
requestId | string | Sì | Request ID da createTransmission |
Ritorna: Contenuto binario del file PDD
Esempio:
const info = await communications.getTransmissionInfo(requestId);
if (info.pddAvailable) {
const pdd = await communications.getPdd(requestId);
fs.writeFileSync('pdd.pdf', Buffer.from(pdd));
}
Tipi di comunicazioni finanziarie:
| Codice | Nome | Descrizione |
|---|---|---|
LI | Liquidazioni IVA | Comunicazioni liquidazioni periodiche IVA |
DTE | Dati Fatture Emesse | Dati delle fatture emesse |
DTR | Dati Fatture Ricevute | Dati delle fatture ricevute |
ANN | Annullamento | Annullamento di comunicazione precedente |
type CommunicationType = 'LI' | 'DTE' | 'DTR' | 'ANN';
Codici stato trasmissione:
| Codice | Descrizione |
|---|---|
SF01 | File ricevuto |
SF02 | File in elaborazione |
SF03 | File elaborato |
type ResultCode = 'SF01' | 'SF02' | 'SF03';
Codici risultato elaborazione finale:
| Codice | Descrizione |
|---|---|
ES01 | File accettato |
ES02 | File accettato con segnalazioni |
ES03 | File scartato |
type ElaboratedResult = 'ES01' | 'ES02' | 'ES03';
interface CreateTransmissionRequest {
userId?: string; // User ID opzionale
comunicationType: CommunicationType; // LI, DTE, DTR, ANN
dataFile: string; // XML codificato Base64
}
interface TransmissionInfo {
result: ResultCode;
notifyResult: string;
elaboratedResult: ElaboratedResult | string;
receiptTimestamp: string;
fileId: string;
fileName: string;
status: string;
pddAvailable: boolean;
}
import { ArubaClient } from '@fatturazione-elettronica-aruba/core';
import { CommunicationsClient } from '@fatturazione-elettronica-aruba/communications';
import { encodeBase64 } from '@fatturazione-elettronica-aruba/utils';
import fs from 'node:fs';
const client = new ArubaClient({ environment: 'production' });
await client.auth.signIn(username, password);
const communications = new CommunicationsClient({ httpClient: client.http });
// 1. Invia liquidazione IVA
const xmlContent = fs.readFileSync('liquidazione-q1-2024.xml', 'utf-8');
const { requestId } = await communications.createTransmission({
comunicationType: 'LI',
dataFile: encodeBase64(xmlContent),
});
// 2. Polling per il risultato
let info;
do {
await new Promise((r) => setTimeout(r, 5000));
info = await communications.getTransmissionInfo(requestId);
console.log('Stato:', info.result);
} while (info.result !== 'SF03');
// 3. Controlla risultato finale
if (info.elaboratedResult === 'ES01') {
console.log('Comunicazione accettata!');
// 4. Scarica prova di deposito
if (info.pddAvailable) {
const pdd = await communications.getPdd(requestId);
fs.writeFileSync(`pdd-${requestId}.pdf`, Buffer.from(pdd));
}
} else if (info.elaboratedResult === 'ES03') {
console.error('Comunicazione scartata:', info.notifyResult);
}