API Reference

Communications

API reference for the Communications package - AdE financial communications.

Communications Package

The @fatturazione-elettronica-aruba/communications package provides methods to send and manage financial communications to the Agenzia delle Entrate (Italian Revenue Agency).

Installation

pnpm add @fatturazione-elettronica-aruba/communications

CommunicationsClient

Constructor

import { CommunicationsClient } from '@fatturazione-elettronica-aruba/communications';

const communications = new CommunicationsClient({
  httpClient: client.http,
});

Options:

Name	Type	Required	Description
`httpClient`	`HttpClient`	Yes	HTTP client instance from `ArubaClient`

Methods

createTransmission

Sends a financial communication to the Revenue Agency.

async createTransmission(request: CreateTransmissionRequest): Promise<CreateTransmissionResponse>

Parameters:

Name	Type	Required	Description
`comunicationType`	`CommunicationType`	Yes	Type of communication (LI, DTE, DTR, ANN)
`dataFile`	`string`	Yes	Base64-encoded XML file
`userId`	`string`	No	User identifier (for multi-company)

Returns:

interface CreateTransmissionResponse {
  requestId: string; // Use this to check transmission status
}

Example:

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);

getTransmissionInfo

Retrieves the status and details of a transmission.

async getTransmissionInfo(requestId: string): Promise<TransmissionInfo>

Parameters:

Name	Type	Required	Description
`requestId`	`string`	Yes	Request ID from `createTransmission`

Returns:

interface TransmissionInfo {
  result: ResultCode;              // SF01, SF02, SF03
  notifyResult: string;            // Notification details
  elaboratedResult: ElaboratedResult | string; // ES01, ES02, ES03
  receiptTimestamp: string;        // When received
  fileId: string;                  // File identifier
  fileName: string;                // Original filename
  status: string;                  // Current status
  pddAvailable: boolean;           // Whether PDD is available
}

Example:

const info = await communications.getTransmissionInfo(requestId);

console.log('Status:', info.result);
console.log('Elaboration result:', info.elaboratedResult);

if (info.elaboratedResult === 'ES03') {
  console.log('File was rejected');
}

getPdd

Downloads the PDD (Prova di Deposito - Proof of Filing) document.

async getPdd(requestId: string): Promise<ArrayBuffer>

Parameters:

Name	Type	Required	Description
`requestId`	`string`	Yes	Request ID from `createTransmission`

Returns: Binary content of the PDD file

Example:

const info = await communications.getTransmissionInfo(requestId);

if (info.pddAvailable) {
  const pdd = await communications.getPdd(requestId);
  fs.writeFileSync('pdd.pdf', Buffer.from(pdd));
}

Types

CommunicationType

Types of financial communications:

Code	Name	Description
`LI`	Liquidazioni IVA	Periodic VAT settlements
`DTE`	Dati Fatture Emesse	Issued invoice data
`DTR`	Dati Fatture Ricevute	Received invoice data
`ANN`	Annullamento	Cancellation of previous communication

type CommunicationType = 'LI' | 'DTE' | 'DTR' | 'ANN';

ResultCode

Transmission status codes:

Code	Description
`SF01`	File received
`SF02`	File being processed
`SF03`	File processed

type ResultCode = 'SF01' | 'SF02' | 'SF03';

ElaboratedResult

Final elaboration result codes:

Code	Description
`ES01`	File accepted
`ES02`	File accepted with warnings
`ES03`	File rejected

type ElaboratedResult = 'ES01' | 'ES02' | 'ES03';

CreateTransmissionRequest

interface CreateTransmissionRequest {
  userId?: string;                    // Optional user ID
  comunicationType: CommunicationType; // LI, DTE, DTR, ANN
  dataFile: string;                   // Base64-encoded XML
}

TransmissionInfo

interface TransmissionInfo {
  result: ResultCode;
  notifyResult: string;
  elaboratedResult: ElaboratedResult | string;
  receiptTimestamp: string;
  fileId: string;
  fileName: string;
  status: string;
  pddAvailable: boolean;
}

Complete Example

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. Send VAT settlement
const xmlContent = fs.readFileSync('liquidazione-q1-2024.xml', 'utf-8');
const { requestId } = await communications.createTransmission({
  comunicationType: 'LI',
  dataFile: encodeBase64(xmlContent),
});

// 2. Poll for result
let info;
do {
  await new Promise((r) => setTimeout(r, 5000));
  info = await communications.getTransmissionInfo(requestId);
  console.log('Status:', info.result);
} while (info.result !== 'SF03');

// 3. Check final result
if (info.elaboratedResult === 'ES01') {
  console.log('Communication accepted!');

  // 4. Download proof of filing
  if (info.pddAvailable) {
    const pdd = await communications.getPdd(requestId);
    fs.writeFileSync(`pdd-${requestId}.pdf`, Buffer.from(pdd));
  }
} else if (info.elaboratedResult === 'ES03') {
  console.error('Communication rejected:', info.notifyResult);
}

Edit this pageorReport an issue

Notifications

API reference for the Notifications package - SDI notification management.

Nuxt Module

API reference for the Nuxt Module - composables and configuration.