Fattura elettronica in Go

Questo tutorial crea due semplici applicazioni Go 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:

Go 1.18+ è stato installato
Hai ottenuto una API Key attiva
Ti sei registrato con l'Agenzia delle Entrate (necessario per l'ambiente live)

Tip

Per un'esperienza Go ottimale, considera l'uso di Go modules per la gestione delle dipendenze.

Lo sapevi?

L'SDK Go è perfetto per microservizi, applicazioni cloud e sistemi ad alte prestazioni grazie alla sua natura compilata e alla concorrenza nativa.

Receive

Creare l'applicazione

Il primo passo è creare la directory dell'applicazione e inizializzare un modulo Go:

mkdir receive && cd receive
go mod init invoicetronic-receive-example

Installare l'SDK

Installa l'SDK Go:

go get github.com/invoicetronic/go-sdk@v1.1.7

Configurare l'SDK

Crea il file main.go:

Configurare l'SDK

package main

import (
\t"context"
\t"encoding/base64"
\t"fmt"
\t"os"

\tinvoicetronicsdk "github.com/invoicetronic/go-sdk"
)

func main() {
\t// Configura l'SDK
\tconfig := invoicetronicsdk.NewConfiguration()
\tconfig.Servers = invoicetronicsdk.ServerConfigurations{
\t\t{
\t\t\tURL: "https://api.invoicetronic.com/v1",
\t\t},
\t}

\tapiKey := "LA TUA CHIAVE API DI TEST (inizia con ik_test_)"
\tauth := apiKey + ":"
\tauthHeader := "Basic " + base64.StdEncoding.EncodeToString([]byte(auth))
\tconfig.AddDefaultHeader("Authorization", authHeader)

\tclient := invoicetronicsdk.NewAPIClient(config)
}

Come puoi vedere, configuriamo l'SDK impostando l'URL del server e l'autenticazione HTTP Basic con la tua chiave API di test (non quella live). Nota come codifichiamo in Base64 la chiave API seguita da ":" per l'header Authorization.

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 questo codice nella funzione main:

Scaricare le fatture non lette

\t// Scarica le fatture non lette
\tctx := context.Background()

\tunread := true
\tincludePayload := true

\tinboundInvoices, _, err := client.ReceiveAPI.ReceiveGet(ctx).
\t\tUnread(unread).
\t\tIncludePayload(includePayload).
\t\tExecute()

\tif err != nil {
\t\tfmt.Fprintf(os.Stderr, "Errore: %v\\n", err)
\t\treturn
\t}

\tfmt.Printf("Ricevute %d fatture\\n", len(inboundInvoices))

\tfor _, invoice := range inboundInvoices {
\t\tif invoice.Encoding != nil {
\t\t\tif *invoice.Encoding == "Xml" {
\t\t\t\terr = os.WriteFile(*invoice.FileName, []byte(*invoice.Payload), 0644)
\t\t\t} else if *invoice.Encoding == "Base64" {
\t\t\t\tdecoded, _ := base64.StdEncoding.DecodeString(*invoice.Payload)
\t\t\t\terr = os.WriteFile(*invoice.FileName, decoded, 0644)
\t\t\t}

\t\t\tif err != nil {
\t\t\t\tfmt.Fprintf(os.Stderr, "Errore nel salvataggio del file: %v\\n", err)
\t\t\t\tcontinue
\t\t\t}

\t\t\tfmt.Printf("Scaricato %s da un fornitore con Partita IVA %s\\n",
\t\t\t\t*invoice.FileName, invoice.Prestatore.Get())
\t\t}
\t}

Inclusione del Payload

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

Compila ed esegui l'applicazione:

go run main.go

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 una Configuration, impostando l'URL del server e aggiungendo l'header Authorization con HTTP Basic (API key codificata in Base64 seguita da ":").
Dobbiamo creare un client API con NewAPIClient(config) e utilizzare le API specifiche come ReceiveAPI per scaricare le fatture in arrivo.
Le chiamate API usano un pattern fluent con metodi come ReceiveGet(ctx).Unread(true).IncludePayload(true).Execute(). Poiché vogliamo solo fatture nuove e non lette, passiamo Unread(true). Passiamo anche IncludePayload(true) per recuperare il contenuto effettivo della fattura.
Gli oggetti fattura usano puntatori per i campi opzionali. Il campo Encoding può avere i valori "Xml" o "Base64", e Payload contiene il contenuto della fattura.

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 e inizializzare un modulo Go:

mkdir send && cd send
go mod init invoicetronic-send-example

Installare l'SDK

Installa l'SDK Go:

go get github.com/invoicetronic/go-sdk@v1.1.7

Configurare l'SDK

Crea il file main.go:

Configurare l'SDK

package main

import (
\t"context"
\t"encoding/base64"
\t"fmt"
\t"os"
\t"path/filepath"

\tinvoicetronicsdk "github.com/invoicetronic/go-sdk"
)

func main() {
\t// Configura l'SDK
\tconfig := invoicetronicsdk.NewConfiguration()
\tconfig.Servers = invoicetronicsdk.ServerConfigurations{
\t\t{
\t\t\tURL: "https://api.invoicetronic.com/v1",
\t\t},
\t}

\tapiKey := "LA TUA CHIAVE API DI TEST (inizia con ik_test_)"
\tauth := apiKey + ":"
\tauthHeader := "Basic " + base64.StdEncoding.EncodeToString([]byte(auth))
\tconfig.AddDefaultHeader("Authorization", authHeader)

\tclient := invoicetronicsdk.NewAPIClient(config)
}

Come puoi vedere, configuriamo l'SDK impostando l'URL del server e l'autenticazione HTTP Basic con la tua chiave API di test (non quella live).

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 questo codice nella funzione main:

Inviare una fattura

\t// Invia una fattura
\tfilePath := "/qualche/percorso/file/nomefile.xml"

\tmetaData := map[string]string{
\t\t"internal_id":             "123",
\t\t"created_with":            "myapp",
\t\t"some_other_custom_data": "value",
\t}

\tctx := context.Background()

\tpayload, err := os.ReadFile(filePath)
\tif err != nil {
\t\tfmt.Fprintf(os.Stderr, "Errore nella lettura del file: %v\\n", err)
\t\treturn
\t}

\tfileName := filepath.Base(filePath)
\tpayloadStr := string(payload)

\tsendData := *invoicetronicsdk.NewSend()
\tsendData.SetFileName(fileName)
\tsendData.SetPayload(payloadStr)
\tsendData.SetMetaData(metaData)

\tsentInvoice, _, err := client.SendAPI.SendPost(ctx).Send(sendData).Execute()

\tif err != nil {
\t\tfmt.Fprintf(os.Stderr, "Errore: %v\\n", err)
\t\treturn
\t}

\tfmt.Printf("La fattura è stata inviata con successo, ora ha l'Id univoco %s.\\n",
\t\t*sentInvoice.Id)

Compila ed esegui l'applicazione:

go run main.go

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 una Configuration, impostando l'URL del server e aggiungendo l'header Authorization con HTTP Basic.
Dobbiamo creare un client API e utilizzare SendAPI per inviare fatture. Le chiamate API usano il pattern SendPost(ctx).Send(sendData).Execute().
Il modello Send viene creato con NewSend() e configurato con setter: SetFileName(), SetPayload() e SetMetaData(). Il payload contiene il contenuto della fattura, mentre MetaData è opzionale e lega dati personalizzati al documento.

Codice sorgente su GitHub

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