Fattura elettronica in PHP

Questo tutorial crea due semplici applicazioni PHP da zero:

Receive: si connette e autentica con Invoicetronic API e scarica eventuali nuove fatture in arrivo.
Send: si connette e autentica con Invoicetronic API e invia una fattura allo SDI.

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

Prerequisiti

Presupponiamo che questi prerequisiti siano soddisfatti:

PHP 7.4+ o PHP 8.x è stato scaricato e installato
Composer è stato installato
Hai ottenuto una Chiave API attiva
Ti sei registrato presso l'Agenzia delle Entrate (necessario per l'ambiente di produzione)

Utilizziamo Composer per la gestione delle dipendenze, che è lo standard de facto per PHP moderno.

Tip

Per un'esperienza PHP ottimale, considera l'uso di VS Code con l'estensione PHP o PHPStorm per un IDE completo.

Lo sapevi?

L'SDK PHP supporta sia Guzzle che altri client HTTP compatibili con PSR-18, offrendoti flessibilità nell'implementazione.

Receive

Crea l'app

Il primo passo è creare la directory dell'applicazione:

mkdir receive && cd receive

Inizializza il progetto con Composer:

composer init --name="invoicetronic/receive-example" --type=project --no-interaction

Il comando ha creato un nuovo progetto PHP con un file composer.json nella directory corrente.

Installa l'SDK

Installa l'SDK PHP di Invoicetronic:

composer require invoicetronic/invoicetronic-sdk

Una volta completato, apri VS Code nella directory corrente:

code .

Configura l'SDK

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

Configura l'SDK

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configura l'SDK
$config = Invoicetronic\Configuration::getDefaultConfiguration()
    ->setUsername('LA TUA CHIAVE API DI TEST (inizia con ik_test_)');

$config->setHost('https://api.invoicetronic.com/v1');

Come puoi vedere, configuriamo l'SDK impostando l'host dell'API e la tua chiave API di test (non quella live). Nota come utilizziamo il metodo setUsername() 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 la Sandbox API, e l'altra è quella live dell'API. 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.

Scarica le fatture

Siamo pronti per effettuare una richiesta. Vogliamo scaricare nuove fatture dei fornitori che potrebbero essere disponibili dallo SDI. Aggiungi queste righe:

Scarica le fatture non lette

// Scarica le fatture non lette
$receiveApi = new Invoicetronic\Api\ReceiveApi(
    new GuzzleHttp\Client(),
    $config
);

try {
    $inboundInvoices = $receiveApi->receiveGet(
        null,  // page
        null,  // pageSize
        null,  // sort
        true,  // unread
        true   // includePayload
    );

    echo "Ricevute " . count($inboundInvoices) . " fatture\n";

    foreach ($inboundInvoices as $invoice) {
        if ($invoice->getEncoding() === 'Xml') {
            file_put_contents($invoice->getFileName(), $invoice->getPayload());
        } elseif ($invoice->getEncoding() === 'Base64') {
            file_put_contents($invoice->getFileName(), base64_decode($invoice->getPayload()));
        }

        echo "Scaricato {$invoice->getFileName()} da un fornitore con Partita IVA {$invoice->getPrestatore()}\n";
    }
} catch (Exception $e) {
    echo 'Errore: ' . $e->getMessage() . "\n";
}

Inclusione del Payload

Impostiamo includePayload: true per recuperare il contenuto effettivo della fattura nella proprietà payload. Senza questo parametro, il campo payload sarebbe null per impostazione predefinita, il che aumenta le prestazioni e riduce le dimensioni della risposta quando hai bisogno solo dei metadati.

Nel terminale, esegui l'applicazione:

php index.php

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 di produzione?

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

Cosa abbiamo imparato

In questo esempio, abbiamo imparato diverse cose.

Dobbiamo configurare l'SDK chiamando getDefaultConfiguration() e impostando l'username (chiave API) con setUsername() e l'host con setHost().
Dobbiamo istanziare una classe che rappresenta l'endpoint con cui vogliamo lavorare. In questo caso, sfruttiamo ReceiveApi per scaricare le fatture in arrivo, passando un client HTTP (Guzzle) e 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 metodi come getEncoding(), getFileName() e getPayload(). Quest'ultimo contiene il contenuto della fattura, come testo normale o codificato in Base64, come descritto da getEncoding().

Codice sorgente su GitHub

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

Send

Crea l'app

Il primo passo è creare la directory dell'applicazione:

mkdir send && cd send

Inizializza il progetto con Composer:

composer init --name="invoicetronic/send-example" --type=project --no-interaction

Installa l'SDK

Installa l'SDK PHP di Invoicetronic:

composer require invoicetronic/invoicetronic-sdk

Una volta completato, apri VS Code nella directory corrente:

code .

Configura l'SDK

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

Configura l'SDK

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configura l'SDK
$config = Invoicetronic\Configuration::getDefaultConfiguration()
    ->setUsername('LA TUA CHIAVE API DI TEST (inizia con ik_test_)');

$config->setHost('https://api.invoicetronic.com/v1');

Come puoi vedere, configuriamo l'SDK impostando l'host dell'API e la tua chiave API di test (non quella live). Nota come utilizziamo il metodo setUsername() 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 la Sandbox API, e l'altra è quella live dell'API. 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.

Invia una fattura

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

Invia una fattura

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

$metaData = [
    'internal_id' => '123',
    'created_with' => 'myapp',
    'some_other_custom_data' => 'value'
];

$sendApi = new Invoicetronic\Api\SendApi(
    new GuzzleHttp\Client(),
    $config
);

try {
    $sendData = new Invoicetronic\Model\Send();
    $sendData->setFileName(basename($filePath));
    $sendData->setPayload(file_get_contents($filePath));
    $sendData->setMetaData($metaData);

    $sentInvoice = $sendApi->sendPost($sendData);

    echo "La fattura è stata inviata con successo, ora ha l'Id univoco {$sentInvoice->getId()}.\n";
} catch (Exception $e) {
    echo 'Errore: ' . $e->getMessage() . "\n";
}

Nel terminale, esegui l'applicazione:

php index.php

Dovresti ottenere un output simile a questo:

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

Cosa abbiamo imparato

In questo esempio, abbiamo imparato diverse cose.

Dobbiamo configurare l'SDK chiamando getDefaultConfiguration() e impostando l'username (chiave API) con setUsername() e l'host con setHost().
Dobbiamo istanziare una classe che rappresenta l'endpoint con cui vogliamo lavorare. In questo caso, sfruttiamo SendApi per inviare fatture. Le classi endpoint come SendApi offrono metodi per interagire con la loro entità target. Chiamiamo sendPost() per inviare una fattura.
La classe Send espone metodi come setFileName(), setMetaData() e setPayload(). Quest'ultimo contiene il contenuto della fattura, mentre setMetaData() è opzionale e associa dati personalizzati al documento.

Codice sorgente su GitHub

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