Fattura elettronica in Ruby

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

Ruby 2.7+ è stato installato
Bundler è stato installato (gem install bundler)
Hai ottenuto una API Key attiva
Ti sei registrato con l'Agenzia delle Entrate (necessario per l'ambiente live)

Tip

Per un'esperienza Ruby ottimale, considera l'uso di rbenv o RVM per la gestione delle versioni Ruby.

Lo sapevi?

Il Ruby SDK è compatibile con Rails, Sinatra e tutte le moderne applicazioni Ruby.

Receive

Creare l'applicazione

Il primo passo è creare la directory dell'applicazione:

mkdir receive && cd receive

Installare l'SDK

Crea un file Gemfile con il seguente contenuto:

Gemfile

source 'https://rubygems.org'

gem 'invoicetronic_sdk', '~> 1.1.7'

Poi installa le dipendenze:

bundle install

Configurare l'SDK

Crea il file receive.rb:

Configurare l'SDK

require 'invoicetronic_sdk'

# Configura l'SDK
InvoicetronicSdk.configure do |config|
  config.host = 'https://api.invoicetronic.com/v1'
  config.username = 'LA TUA CHIAVE API DI TEST (inizia con ik_test_)'
  config.password = ''
end

Come puoi vedere, configuriamo l'SDK impostando l'host e l'autenticazione HTTP Basic con la tua chiave API di test (non quella live). Nota come usiamo username per la chiave API e password vuoto.

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 nel file:

Scaricare le fatture non lette

require 'base64'

# Scarica le fatture non lette
api_instance = InvoicetronicSdk::ReceiveApi.new

begin
  inbound_invoices = api_instance.receive_get(
    nil,    # company_id
    nil,    # identifier
    true,   # unread
    nil,    # committente
    nil,    # prestatore
    nil,    # file_name
    nil,    # last_update_from
    nil,    # last_update_to
    nil,    # date_sent_from
    nil,    # date_sent_to
    nil,    # document_date_from
    nil,    # document_date_to
    nil,    # document_number
    true,   # include_payload
    nil,    # page
    nil,    # page_size
    nil     # sort
  )

  puts "Ricevute #{inbound_invoices.length} fatture"

  inbound_invoices.each do |invoice|
    if invoice.encoding == 'Xml'
      File.write(invoice.file_name, invoice.payload)
    elsif invoice.encoding == 'Base64'
      File.write(invoice.file_name, Base64.decode64(invoice.payload))
    end

    puts "Scaricato #{invoice.file_name} da un fornitore con Partita IVA #{invoice.prestatore}"
  end
rescue InvoicetronicSdk::ApiError => e
  puts "Errore: #{e}"
end

Inclusione del Payload

Impostiamo include_payload a 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.

Esegui l'applicazione:

ruby receive.rb

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 usando InvoicetronicSdk.configure, impostando l'host e configurando l'autenticazione HTTP Basic con username (chiave API) e password vuota.
Dobbiamo istanziare una classe che rappresenta l'endpoint con cui vogliamo lavorare. In questo caso, utilizziamo ReceiveApi per scaricare le fatture in arrivo.
Le classi endpoint come ReceiveApi offrono metodi per interagire con la loro entità target. Chiamiamo receive_get per recuperare le fatture. Poiché vogliamo solo fatture nuove e non lette, passiamo true per il parametro unread. Passiamo anche true per include_payload per recuperare il contenuto effettivo della fattura.
Gli oggetti fattura espongono proprietà come encoding, file_name e payload. L'ultimo contiene il contenuto della fattura, come testo semplice o codificato in Base64, come descritto da encoding che ha i valori 'Xml' o 'Base64'.

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

Installare l'SDK

Crea un file Gemfile con il seguente contenuto:

Gemfile

source 'https://rubygems.org'

gem 'invoicetronic_sdk', '~> 1.1.7'

Poi installa le dipendenze:

bundle install

Configurare l'SDK

Crea il file send.rb:

Configurare l'SDK

require 'invoicetronic_sdk'

# Configura l'SDK
InvoicetronicSdk.configure do |config|
  config.host = 'https://api.invoicetronic.com/v1'
  config.username = 'LA TUA CHIAVE API DI TEST (inizia con ik_test_)'
  config.password = ''
end

Come puoi vedere, configuriamo l'SDK impostando l'host 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 nel file:

Inviare una fattura

# Invia una fattura
file_path = '/qualche/percorso/file/nomefile.xml'

meta_data = {
  'internal_id' => '123',
  'created_with' => 'myapp',
  'some_other_custom_data' => 'value'
}

api_instance = InvoicetronicSdk::SendApi.new

begin
  payload = File.read(file_path)

  send_data = InvoicetronicSdk::Send.new(
    file_name: File.basename(file_path),
    payload: payload,
    meta_data: meta_data
  )

  sent_invoice = api_instance.send_post(send_data)

  puts "La fattura è stata inviata con successo, ora ha l'Id univoco #{sent_invoice.id}."
rescue InvoicetronicSdk::ApiError => e
  puts "Errore: #{e}"
end

Esegui l'applicazione:

ruby send.rb

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 usando InvoicetronicSdk.configure, impostando l'host e configurando l'autenticazione HTTP Basic.
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 send_post per inviare una fattura.
Il modello Send accetta parametri nel costruttore: file_name, payload e meta_data. Il payload 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.