Vai al contenuto

Fattura elettronica da command-line con invoice

Non è necessario imparare l'API o alcun linguaggio di programmazione per inviare e ricevere fatture. Abbiamo creato il comando invoice per scambiare in modo rapido e intuitivo file di fatture con il Servizio di Interscambio (SDI) dalla riga di comando.

In questo quickstart utilizzeremo lo strumento da riga di comando invoice per:

  1. Inviare file di fatture allo SDI
  2. Ricevere fatture dallo SDI
  3. Configurare lo strumento per un utilizzo ottimale

Per la consultazione della cronologia delle notifiche restituite dallo SDI per le fatture inviate (endpoint /update), il CLI invoice non espone un comando dedicato: dai un'occhiata al quickstart curl o a uno dei quickstart degli SDK.

Prerequisiti

Presupponiamo che questi prerequisiti siano soddisfatti:

Warning

In tutti gli esempi, ricorda di sostituire la chiave di esempio con la tua chiave API di test. Non usare la chiave live, altrimenti i documenti verranno inviati allo SDI per la consegna effettiva.

Send

Il comando send consente di caricare file di fatture verso lo SDI. Ad esempio:

invoice send file1.xml --apikey ik_test_YOUR_API_KEY

Carica file1.xml nella Sandbox per scopi di test.

Puoi elencare più file:

invoice send file1.xml file2.xml path/to/another/file3.xml.p7m --apikey ik_test_YOUR_API_KEY

Il comando sopra carica file1.xml e file2.xml dalla directory corrente, e il file firmato digitalmente file3.xml.p7m da un percorso diverso.

I caricamenti in blocco sono probabilmente gestiti meglio con i caratteri jolly:

invoice send outbound/*.xml --apikey ik_test_YOUR_API_KEY

Carica tutti i file di fatture xml dalla directory outbound.

Elimina dopo il caricamento

Potresti voler eliminare i file locali una volta caricati. Questo si ottiene con l'opzione --delete:

invoice send file1.xml --delete --apikey ik_test_YOUR_API_KEY

Si comporta come il comando precedente, ma i file locali verranno rimossi in caso di caricamenti riusciti.

Validazione preliminare

Se non sei sicuro che le fatture siano valide per lo SDI, puoi richiedere una validazione preliminare con l'opzione --validate:

invoice send file1.xml --validate --apikey ik_test_YOUR_API_KEY

Il file verrà rifiutato in caso di errore nella validazione.

Richiedere aiuto

invoice send --help

Elenca tutte le opzioni disponibili e mostra come utilizzarle.

Receive

Il comando receive consente di scaricare le fatture dallo SDI.

invoice receive --apikey ik_test_YOUR_API_KEY

Non ricevi fatture nell'ambiente di produzione?

Assicurati che i tuoi corrispondenti utilizzino 7HD37X0 come valore del campo Codice Destinatario delle loro fatture. È così che lo SDI sa che devono essere inoltrate a Invoicetronic API.

Solo fatture non lette

Scarica tutti i file di fatture disponibili. Tuttavia, questo potrebbe scaricare file precedentemente scaricati. Se sei interessato solo alle fatture nuove, usa l'opzione --unread:

invoice receive --unread --apikey ik_test_YOUR_API_KEY

Ora verranno scaricate solo le fatture precedentemente non lette. Se vuoi mantenere solo le fatture nuove sull'API, puoi utilizzare l'opzione --delete:

Elimina una volta scaricate

invoice receive --delete --apikey ik_test_YOUR_API_KEY

Con il comando sopra, una volta che una fattura è stata scaricata e salvata su disco, verrà rimossa dal remoto.

Come JSON

Per impostazione predefinita, le fatture scaricate vengono salvate come file in base al valore del loro campo file_name. Se hai bisogno di elaborare immediatamente il documento, possibilmente con una pipeline Linux, potresti preferire un output JSON su stdout:

invoice receive --json --apikey ik_test_YOUR_API_KEY | more

Il comando sopra visualizzerà la fattura sulla console, mettendo in pausa quando lo schermo è pieno.

Configure

Dover ripetere la chiave API per ogni comando è tedioso. Puoi usare il comando config per salvare la chiave in un file di configurazione:

invoice config apikey ik_test_YOUR_API_KEY

Ora puoi omettere la chiave quando esegui un comando send o receive:

invoice receive --unread

or:

invoice send file.xml

Eccetera. Il file di configurazione è memorizzato nella home directory dell'utente con il nome .invoice.yaml (è nascosto sui sistemi Unix/Linux). Ci sono più opzioni di configurazione, per vederle tutte basta usare l'opzione --list (-l):

invoice config --list

Configuration file: /Users/johndoe/.invoice.yaml
apikey: ik_test_YOUR_API_KEY
host: https://api.invoicetronic.com
verbose: false

Puoi anche modificare la configurazione tutta in una volta con invoice config --edit (o -e).

Come puoi vedere, puoi passare alla modalità verbosa (invoice config verbose true), impostare un host diverso (attualmente non molto utile), vedere dove è conservata la configurazione.

Variabili d'ambiente

Quando salvi la chiave API nella tua configurazione, viene memorizzata in chiaro. Se la sicurezza è una preoccupazione (dovrebbe esserlo), dovresti invece usare le variabili d'ambiente:

INVOICE_APIKEY=ik_test_MY_SUPER_SECRET_KEY invoice config -l

Configuration file: /Users/johndoe/.invoice.yaml
apikey: ik_test_MY_SUPER_SECRET_KEY     # stiamo eseguendo con la chiave dalla variabile d'ambiente
host: https://api.invoicetronic.com
verbose: false

Anteponendo INVOICE_ a qualsiasi impostazione di configurazione, puoi passarla come variabile d'ambiente, senza mai memorizzare i dati sensibili sul tuo sistema. Un esempio più utile:

INVOICE_APIKEY=ik_test_MY_SUPER_SECRET_KEY invoice send file1.xml

In un ambiente di integrazione continua, il valore della variabile d'ambiente dovrebbe provenire da un segreto di qualche tipo (GitHub Secrets, ecc.)