Fattura elettronica in TypeScript

Questo tutorial crea due semplici applicazioni TypeScript da zero:

Receive: si connette e autentica con l'API Invoicetronic e scarica le nuove fatture passive in arrivo.
Send: si connette e autentica con l'API Invoicetronic e invia una fattura al SDI.

Prima di continuare, assicurati che tutti i prerequisiti siano soddisfatti.

Prerequisiti

Assumiamo che questi prerequisiti siano soddisfatti:

Node.js 14+ è stato scaricato e installato
npm o yarn è installato (viene fornito con Node.js)
TypeScript è installato (verrà installato come dipendenza del progetto)
Hai ottenuto una API Key attiva
Ti sei registrato con l'Agenzia delle Entrate (necessario per l'ambiente live)

Usiamo npm per la gestione delle dipendenze, ma puoi usare anche yarn se preferisci.

Tip

Per un'esperienza TypeScript ottimale, considera l'uso di VS Code con estensioni TypeScript o WebStorm per un IDE completo.

Lo sapevi?

L'SDK TypeScript offre type safety completo, autocomplete nell'IDE e rilevamento degli errori a compile-time, rendendo l'integrazione più sicura e veloce.

Receive

Creare l'applicazione

Il primo passo è creare la directory dell'applicazione:

mkdir receive && cd receive

Inizializza il progetto con npm:

npm init -y

Il comando ha creato un nuovo progetto Node.js con un file package.json nella directory corrente.

Installare l'SDK

Installa l'SDK TypeScript di Invoicetronic e TypeScript:

npm install @invoicetronic/ts-sdk typescript @types/node --save-dev

Una volta fatto, apri VS Code nella directory corrente:

code .

Configurare TypeScript

Crea un file tsconfig.json con la seguente configurazione:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["*.ts"],
  "exclude": ["node_modules"]
}

Configurare l'SDK

Crea un nuovo file chiamato index.ts e aggiungi il seguente codice:

Configurare l'SDK

import { Configuration, ReceiveApi } from '@invoicetronic/ts-sdk';

// Configura l'SDK
const config = new Configuration({
  username: 'LA TUA CHIAVE API DI TEST (inizia con ik_test_)',
  basePath: 'https://api.invoicetronic.com/v1'
});

Come puoi vedere, configuriamo l'SDK passando la tua chiave API di test (non quella live) e l'host dell'API. Nota come usiamo il campo username per impostare la chiave API.

Le chiavi API vengono fornite in coppia

Quando crei il tuo account, ottieni una coppia di chiavi API. Una è la chiave di test per l'API Sandbox, e l'altra è quella live. Puoi distinguerle perché la prima inizia con ik_test_, mentre la seconda inizia con ik_live_. In questo tutorial, usa sempre la chiave di test.

Scaricare le fatture

Siamo pronti per effettuare una richiesta. Vogliamo scaricare le nuove fatture passive che potrebbero essere disponibili dall'SDI. Aggiungi queste righe:

Scaricare le fatture non lette

import * as fs from 'fs';

// Scarica le fatture non lette
const receiveApi = new ReceiveApi(config);

async function downloadInvoices() {
  try {
    const inboundInvoices = await receiveApi.receiveGet(
      undefined,  // companyId
      undefined,  // identifier
      true,       // unread
      undefined,  // committente
      undefined,  // prestatore
      undefined,  // fileName
      undefined,  // lastUpdateFrom
      undefined,  // lastUpdateTo
      undefined,  // dateSentFrom
      undefined,  // dateSentTo
      undefined,  // documentDateFrom
      undefined,  // documentDateTo
      undefined,  // documentNumber
      true        // includePayload
    );

    console.log(`Ricevute ${inboundInvoices.data.length} fatture`);

    for (const invoice of inboundInvoices.data) {
      if (invoice.encoding === 'Xml') {
        fs.writeFileSync(invoice.file_name!, invoice.payload!, 'utf8');
      } else if (invoice.encoding === 'Base64') {
        const buffer = Buffer.from(invoice.payload!, 'base64');
        fs.writeFileSync(invoice.file_name!, buffer);
      }

      console.log(`Scaricato ${invoice.file_name} da un fornitore con Partita IVA ${invoice.prestatore}`);
    }
  } catch (error: any) {
    console.error('Errore:', error.message);
    if (error.response) {
      console.error('Dettagli:', error.response.data);
    }
  }
}

downloadInvoices();

Inclusione del Payload

Impostiamo includePayload: true per recuperare il contenuto effettivo della fattura nella proprietà payload. Senza questo parametro, il campo payload sarebbe null di default, il che migliora le prestazioni e riduce la dimensione della risposta quando hai bisogno solo dei metadati.

Aggiungi uno script di build nel package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Nel terminale, compila ed esegui l'applicazione:

npm run build && npm start

Dovresti ottenere un output simile a questo:

Ricevute 3 fatture
Scaricato file1.xml da un fornitore con Partita IVA IT06157670966
Scaricato file2.xml.p7m da un fornitore con Partita IVA IT01280270057
Scaricato file3.xml.p7m da un fornitore con Partita IVA IT01280270057

I file sono nella directory corrente, pronti per essere ispezionati.

Non ricevi fatture nell'ambiente live?

Assicurati di esserti registrato con l'Agenzia delle Entrate, che è un requisito per l'ambiente live.

Cosa abbiamo imparato

In questo esempio, abbiamo imparato diverse cose.

Dobbiamo configurare l'SDK creando un'istanza di Configuration e passando username (chiave API) e basePath (URL dell'API).
Dobbiamo istanziare una classe che rappresenta l'endpoint con cui vogliamo lavorare. In questo caso, utilizziamo ReceiveApi per scaricare le fatture in arrivo, passando la configurazione.
Le classi endpoint come ReceiveApi offrono metodi per interagire con la loro entità target. Chiamiamo receiveGet() per recuperare le fatture. Poiché vogliamo solo fatture nuove e non lette, passiamo true per il parametro unread. Passiamo anche true per includePayload per recuperare il contenuto effettivo della fattura.
Gli oggetti fattura espongono proprietà come encoding, file_name e payload. L'ultima contiene il contenuto della fattura, come testo semplice o codificato in Base64, come descritto da encoding.

Codice sorgente su GitHub

Il codice sorgente per questo Quickstart è disponibile anche su GitHub.

Send

Creare l'applicazione

Il primo passo è creare la directory dell'applicazione:

mkdir send && cd send

Inizializza il progetto con npm:

npm init -y

Installare l'SDK

Installa l'SDK TypeScript di Invoicetronic e TypeScript:

npm install @invoicetronic/ts-sdk typescript @types/node --save-dev

Una volta fatto, apri VS Code nella directory corrente:

code .

Configurare TypeScript

Crea un file tsconfig.json con la seguente configurazione:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["*.ts"],
  "exclude": ["node_modules"]
}

Configurare l'SDK

Crea un nuovo file chiamato index.ts e aggiungi il seguente codice:

Configurare l'SDK

import { Configuration, SendApi, Send } from '@invoicetronic/ts-sdk';

// Configura l'SDK
const config = new Configuration({
  username: 'LA TUA CHIAVE API DI TEST (inizia con ik_test_)',
  basePath: 'https://api.invoicetronic.com/v1'
});

Come puoi vedere, configuriamo l'SDK passando la tua chiave API di test (non quella live) e l'host dell'API. Nota come usiamo il campo username per impostare la chiave API.

Le chiavi API vengono fornite in coppia

Quando crei il tuo account, ottieni una coppia di chiavi API. Una è la chiave di test per l'API Sandbox, e l'altra è quella live. Puoi distinguerle perché la prima inizia con ik_test_, mentre la seconda inizia con ik_live_. In questo tutorial, usa sempre la chiave di test.

Inviare una fattura

Siamo pronti per effettuare una richiesta. Vogliamo inviare una fattura all'SDI. Aggiungi il seguente codice:

Inviare una fattura

import * as fs from 'fs';
import * as path from 'path';

// Invia una fattura
const filePath = '/qualche/percorso/file/nomefile.xml';

const metaData: { [key: string]: string } = {
  'internal_id': '123',
  'created_with': 'myapp',
  'some_other_custom_data': 'value'
};

const sendApi = new SendApi(config);

async function sendInvoice() {
  try {
    const sendData: Send = {
      file_name: path.basename(filePath),
      payload: fs.readFileSync(filePath, 'utf8'),
      meta_data: metaData
    };

    const sentInvoice = await sendApi.sendPost(sendData);

    console.log(`La fattura è stata inviata con successo, ora ha l'Id univoco ${sentInvoice.data.id}.`);
  } catch (error: any) {
    console.error('Errore:', error.message);
    if (error.response) {
      console.error('Dettagli:', error.response.data);
    }
  }
}

sendInvoice();

Aggiungi uno script di build nel package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Nel terminale, compila ed esegui l'applicazione:

npm run build && npm start

Dovresti ottenere un output simile a questo:

La fattura è stata inviata con successo, ora ha l'Id univoco 123.

Cosa abbiamo imparato

In questo esempio, abbiamo imparato diverse cose.

Dobbiamo configurare l'SDK creando un'istanza di Configuration e passando username (chiave API) e basePath (URL dell'API).
Dobbiamo istanziare una classe che rappresenta l'endpoint con cui vogliamo lavorare. In questo caso, utilizziamo SendApi per inviare fatture. Le classi endpoint come SendApi offrono metodi per interagire con la loro entità target. Chiamiamo sendPost() per inviare una fattura.
L'interfaccia Send espone proprietà come file_name, meta_data e payload. L'ultima contiene il contenuto della fattura, mentre meta_data è opzionale e lega dati personalizzati al documento.

Codice sorgente su GitHub

Il codice sorgente per questo Quickstart è disponibile anche su GitHub.