PHPackages                             simplyit/fattura24-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. simplyit/fattura24-sdk

ActiveLibrary[API Development](/categories/api)

simplyit/fattura24-sdk
======================

PHP SDK for Fattura24.com API - Italian electronic invoicing

2.1.4(2mo ago)10MITPHPPHP ^8.1CI failing

Since Feb 15Pushed 2mo agoCompare

[ Source](https://github.com/davidakis/fattura24-sdk)[ Packagist](https://packagist.org/packages/simplyit/fattura24-sdk)[ RSS](/packages/simplyit-fattura24-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (10)Versions (9)Used By (0)

Fattura24 PHP SDK
=================

[](#fattura24-php-sdk)

PHP SDK tipizzato e testato per l'integrazione con le API di [Fattura24](https://www.fattura24.com/api/introduzione/).

Progettato per applicazioni personalizzate, plugin WordPress, moduli e-commerce e sistemi gestionali - senza accoppiamento a framework o piattaforme specifiche.

[![PHP Version](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565)](https://www.php.net)[![Latest Version](https://camo.githubusercontent.com/d1f104b620658266e77719884f68b923f5a43f1cdcec68643e0f2096a09c84a4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6461766964616b69732f6661747475726132342d73646b)](https://packagist.org/packages/davidakis/fattura24-sdk)[![Total Downloads](https://camo.githubusercontent.com/d4db0529be9da430426cbf2409d1f74a51c9291b05038a76404704db0aac9951/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6461766964616b69732f6661747475726132342d73646b)](https://packagist.org/packages/davidakis/fattura24-sdk)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)

---

v2.1 Miglioramenti
------------------

[](#v21-miglioramenti)

**InvoiceBuilder**: interfaccia elastica opzionale per codice più conciso **Documentazione**: aggiunta esempi di uso

v2.0 Cambiamenti di rottura
---------------------------

[](#v20-cambiamenti-di-rottura)

**v2.0** è una riscrittura completa con oggetti di risposta tipizzati

**Stai aggiornando da v1.x?** Leggi [UPGRADE.md](UPGRADE.md)

---

Caratteristiche
---------------

[](#caratteristiche)

✅ **PHP 8.1+** con proprietà nominate ✅ **Oggetti di risposta tipizzati**

✅ **Validazione automatica** dati fiscali italiani (CF, P.IVA, PEC, SDI)
✅ **Generazione XML automatica** conforme alle specifiche Fattura24
✅ **Framework-agnostic** — nessun accoppiamento a WordPress, Laravel, Symfony, etc.
✅ **100% copertura di test** con PHPUnit
✅ **PHPStan Level 6** — analisi staticacompleta

---

Requisiti
---------

[](#requisiti)

MinimoPHP8.1ext-curlqualsiasiext-domqualsiasiext-simplexmlqualsiasiaccount Fattura24 on chiave API---

Installazione
-------------

[](#installazione)

### Con Composer (consigliato)

[](#con-composer-consigliato)

```
composer require davidakis/fattura24-sdk
```

### Senza Composer

[](#senza-composer)

1. Scarica l'[ultima versione](https://github.com/davidakis/fattura24-sdk/releases/latest) dal repository GitHub
2. Estrai la cartella `src/` all'interno del tuo progetto
3. Includi un semplice autoloader PSR-4 oppure utilizza il tuo autoloader esistente

Esempio di autoloader minimale:

```
spl_autoload_register(function ($class) {
    $prefix = 'Davidakis\\Fattura24SDK\\';
    $baseDir = __DIR__ . '/src/';
    $len = strlen($prefix);

    if (strncmp($prefix, $class, $len) !== 0) {
        return;
    }

    $relativeClass = substr($class, $len);
    $file = $baseDir . str_replace('\\', '/', $relativeClass) . '.php';

    if (file_exists($file)) {
        require $file;
    }
});
```

Assicurati che le estensioni richieste (`ext-curl`, `ext-dom`, `ext-simplexml`) siano abilitate nel tuo `php.ini`.

---

🚀 Guida rapida
--------------

[](#-guida-rapida)

```
use Davidakis\Fattura24SDK\Fattura24Client;
use Davidakis\Fattura24SDK\Data\{DocumentData, DocumentType, CustomerData, RowData, InvoiceData};

// 1. Crea il client
$client = new Fattura24Client([
    'apiKey' => 'your-api-key',
    'source' => 'MyApp',  // opzionale
    'pdfDir' => '/var/www/fatture', // opzionale: salva PDF qui
]);

// 2. Prepara i dati
$document = new DocumentData(
    documentType: DocumentType::FatturaElettronica,
    total: 122.00,
);
$document->totalWithoutTax = 100.00;
$document->vatAmount = 22.00;

// Optional: override default payment (default is MP08 - Pagamento con carta)
$document->setPayment('MP05', 'Bonifico bancario');

$customer = new CustomerData('Mario Rossi');
$customer->customerCountry = 'IT';
$customer->setCustomerFiscalCode('RSSMRA80A01H501U'); // Auto-validato per clienti IT
$customer->customerEmail = 'mario@email.it';

$row = new RowData('Consulenza', 1, 100.00, 22);

$invoice = new InvoiceData($document, $customer, [$row]);

// 3. Invia la fattura
$response = $client->saveDocument($invoice);

echo "Fattura #{$response->docNumber} creata con ID {$response->docId}\n";
```

---

Uso di InvoiceBuilder
---------------------

[](#uso-di-invoicebuilder)

```
use Davidakis\Fattura24SDK\Builder\InvoiceBuilder;

$invoice = InvoiceBuilder::create()
    ->customer('Mario Rossi', 'IT', 'mario.example.com')
    ->fiscalCode('RSSMRA80A01F205C')
    ->totals(122.00, 100.00, 22.00)
    ->payment('MP05', 'Bonifico bancario')
    ->row('Consulenza tecnica', 1, 100.00, 22)
    ->build();

$response = $client->saveDocument($invoice);
echo "Invoice created: {$response->docNumber}\n";
```

Documentazione
--------------

[](#documentazione)

- [Guida Upgrade v1→v2](UPGRADE.md)
- [Changelog Completo](CHANGELOG.md)

Esempi
------

[](#esempi)

Uso: copia config.php.example in config.php e inserisci la tua chiave API di Fattura24; per eseguire gli esempi apri una finestra di terminale e vai nella cartella examples. Poi digita (esempio):

> php 01-basic-invoice.php

- [01-basic-invoice.php](examples/01-basic-invoice.php) - Fattura semplice
- [02-invoice-exempt-vat.php](examples/02-invoice-vat-exempt.php) - Fattura con alquota 0% e codice natura
- [03-invoice-multiple-vat-rates.php](examples/03-invoice-multiple-vat-rates.php) - Fattura con diverse aliquote IVA
- [04-invoice-with-discount.php](examples/04-invoice-with-discount.php) - Fattura con sconto
- [05-download-pdf.php](examples/05-download-pdf.php) - Gestione del file PDF
- [06-get-templates.php](examples/06-get-templates.php) - Modelli di documento e numeratori
- [07-bulk-invoicing.php](examples/07-bulk-invoicing.php) - Creazione massiva
- [08-error-handling.php](examples/08-error-handling.php) - Gestione degli errori

---

Caratteristiche
---------------

[](#caratteristiche-1)

### Oggetti di risposta tipizzati

[](#oggetti-di-risposta-tipizzati)

```
// SaveDocumentResponse
$response = $client->saveDocument($invoice);
echo $response->docId;      // string - IDE autocomplete
echo $response->docNumber;  // string - Type-safe
$response->isSuccess();     // bool - Helper method

// GetFileResponse con metadati
$file = $client->getFile($docId);
echo $file->filename;       // "invoice_123.pdf"
echo $file->contentType;    // "application/pdf"
echo $file->getHumanSize(); // "1.5 MB"

if ($file->isPdf()) {
    file_put_contents('/tmp/invoice.pdf', $file->content);
}

// GetTemplatesResponse
$templates = $client->getTemplates();
foreach ($templates->invoice as $id => $name) {
    echo "{$name}";
}

// GetNumeratorsResponse con helper
$numerators = $client->getNumerators();
$defaultId = $numerators->getDefaultId('invoice');
$document->idNumerator = $defaultId;

// GetChartOfAccountsResponse con search
$pdc = $client->getChartOfAccounts();
$filtered = $pdc->search('prodotto'); // Case-insensitive
foreach ($filtered as $id => $desc) {
    echo "{$id}: {$desc}\n";
}
```

---

### Validazione Automatica (solo Italia)

[](#validazione-automatica-solo-italia)

```
$customer = new CustomerData('Rossi SRL');
$customer->customerCountry = 'IT';

// ✓ OK: 11 cifre
$customer->setCustomerVatCode('12345678901');

// ✗ Exception: formato non valido
$customer->setCustomerVatCode('ABC');
// InvalidArgumentException: P.IVA italiana deve essere 11 cifre numeriche

// ✓ OK: validazione solo per IT
$customer->customerCountry = 'FR';
$customer->setCustomerVatCode('FR123');  // Non validato (cliente estero)
```

**Campi validati (solo per customerCountry = 'IT'):**

- `customerFiscalCode` — 16 caratteri alfanumerici
- `customerVatCode` — 11 cifre numeriche
- `feCustomerPec` — formato email valido
- `feDestinationCode` — 6 o 7 caratteri alfanumerici

**Sanitizzazione automatica:**

```
$customer->setCustomerFiscalCode(' rssmra80a01h501u ');
// Salvato come: 'RSSMRA80A01H501U' (trim + uppercase)
```

---

### Gestione PDF flessibile

[](#gestione-pdf-flessibile)

**Salva su file:**

```
$client->setPdfDirectory('/var/www/fatture');
$filepath = $client->downloadPdf($docId);
// Returns: /var/www/fatture/invoice_123.pdf
```

**Trasmissione al browser:**

```
$client->setPdfDirectory(null);
$result = $client->downloadPdf($docId);
// PDF trasmesso direttamente (usando readfile())
// Returns: null (PDF già inviato)
```

**Link temporaneo (framework-agnostic):**

```
$pdfManager = $client->getPdfManager();

// WordPress
$pdfManager->setUrlGenerator(fn($id) => home_url("/pdf/{$id}"));

// Laravel
$pdfManager->setUrlGenerator(fn($id) => route('pdf.download', ['id' => $id]));

// Symfony
$pdfManager->setUrlGenerator(fn($id) => $router->generate('pdf_download', ['id' => $id]));

// Vanilla PHP
$pdfManager->setUrlGenerator(fn($id) => "https://example.com/download.php?id={$id}");
```

---

### Parametri nominati(PHP 8.1)

[](#parametri-nominatiphp-81)

```
// Compatto (posizionali)
$row = new RowData('Servizio', 1, 100.00, 22);

// Esplicito (parametri nominati) - raccomandato
$row = new RowData(
    description: 'Servizio di consulenza',
    qty: 1,
    price: 100.00,
    vatCode: 22,
);

// DocumentData semplificato (solo 2 params obbligatori)
$document = new DocumentData(
    documentType: DocumentType::FatturaElettronica,
    total: 122.00,
);
// Pagamento predefinito: MP08 (Pagamento con carta)
```

---

### Interfaccia elastica

[](#interfaccia-elastica)

```
$invoice = (new InvoiceData($document, $customer, [$row]))
    ->withDelivery($delivery)
    ->withPayments([$payment]);

$document->setPayment('MP05', 'Bonifico bancario', 'IBAN: IT...');
```

---

Esempi Completi
---------------

[](#esempi-completi)

### Fattura con IVA 0% (esente)

[](#fattura-con-iva-0-esente)

```
$document = new DocumentData(
    documentType: DocumentType::FatturaElettronica,
    total: 100.00,
);
$document->totalWithoutTax = 100.00;
$document->vatAmount = 0.00;

$customer = new CustomerData('Studio Medico Bianchi');
$customer->customerCountry = 'IT';
$customer->setCustomerVatCode('12345678901');
$customer->feDestinationCode = '0000000';
$customer->feCustomerPec = 'studio@pec.it';

$row = new RowData('Visita specialistica', 1, 100.00, 0);
$row->feVatNature = 'N4'; // Esente art. 10

$invoice = new InvoiceData($document, $customer, [$row]);
$response = $client->saveDocument($invoice);
```

---

### Fattura con sconto

[](#fattura-con-sconto)

```
$document = new DocumentData(
    documentType: DocumentType::FatturaELettronica,
    total: 109.80,
);
$document->totalWithoutTax = 90.00;
$document->vatAmount = 19.80;

$row = new RowData('Prodotto', 1, 100.00, 22);
$row->discount = 10; // Sconto 10%

$invoice = new InvoiceData($document, $customer, [$row]);
```

---

### Fattura con prodotti multipli e IVA miste

[](#fattura-con-prodotti-multipli-e-iva-miste)

```
$rows = [
    new RowData('Bene essenziale', 1, 100.00, 10),  // IVA 10%
    new RowData('Servizio standard', 1, 100.00, 22), // IVA 22%
];

$document->total = 132.00;
$document->totalWithoutTax = 110.00;
$document->vatAmount = 22.00; // 10 + 22

$invoice = new InvoiceData($document, $customer, $rows);
```

---

### Test connessione

[](#test-connessione)

```
$result = $client->testKey();
// ['returnCode' => 0, 'message' => 'OK']
```

---

Aggiornamento da v1.x
---------------------

[](#aggiornamento-da-v1x)

### Cambiamento di rottura: risposta tipizzata

[](#cambiamento-di-rottura-risposta-tipizzata)

**v1.x (array):**

```
$result = $client->saveDocument($invoice);
$docId = $result['docId'];
$docNumber = $result['docNumber'];
```

**v2.0 (oggetti tipizzati):**

```
$response = $client->saveDocument($invoice);
$docId = $response->docId;
$docNumber = $response->docNumber;
```

### Migrazione

[](#migrazione)

```
// Funzione di retrocompatibilità (se necessario)
function saveDocumentLegacy($client, $invoice) {
    $response = $client->saveDocument($invoice);
    return [
        'docId' => $response->docId,
        'docNumber' => $response->docNumber,
        'docType' => $response->docType,
    ];
}
```

**Guida completa:** [UPGRADE.md](UPGRADE.md)

---

Test manuale
------------

[](#test-manuale)

La SDK include uno script per testare con API reale di Fattura24.

### Setup

[](#setup)

```
# 1. Copia il file example
cp test-manual.php.example test-manual.php

# 2. Modifica test-manual.php e inserisci la tua API key
nano test-manual.php
# Sostituisci: $API_KEY = 'YOUR_API_KEY_HERE';

# 3. Esegui i test
php test-manual.php
```

### Cosa testa

[](#cosa-testa)

Lo script esegue test end-to-end:

- ✅ Verifica API key
- ✅ Crea fattura di test (REALE!)
- ✅ Testa validazione dati
- ✅ Download PDF
- ✅ Lista modelli
- ✅ Lista numeratori
- ✅ Lista piano dei conti

### Importante

[](#importante)

- Lo script crea fatture **REALI** nel tuo account Fattura24
- Ricordati di **cancellare** le fatture di test dal cruscotto di Fattura24
- Il file `test-manual.php` è nel `.gitignore` (non verrà committato)

---

🧪 Sviluppo
----------

[](#-sviluppo)

```
# Setup
composer install

# Run all checks (cs-fix, stan, phpunit)
composer test

# Code style
composer cs-fix      # Fix issues
composer cs-check    # Check only

# Static analysis
composer stan
```

---

🎯 Perché PHP 8.1+?
------------------

[](#-perché-php-81)

Questa SDK sfrutta le moderne caratteristiche di PHP per una migliore developer experience:

FeatureBeneficio**Parametri nominati**Codice auto-documentante, niente errori di posizione**Proprietà in sola lettura**Dati immutabili, codice più sicuro**Enums**Costanti sicure (DocumentType, etc.)---

💖 Supporta il progetto
----------------------

[](#-supporta-il-progetto)

Se questa SDK ti fa risparmiare tempo e semplifica il tuo lavoro:

[![Donate with PayPal](https://camo.githubusercontent.com/648ad6f048733f167bf65e11a4fd759eef14da88db61ad078bbd5ddea5d57133/68747470733a2f2f7777772e70617970616c6f626a656374732e636f6d2f656e5f55532f692f62746e2f62746e5f646f6e6174655f4c472e676966)](https://www.paypal.com/donate?hosted_button_id=H87RNJQ2VJTGY)

Il tuo supporto aiuta a mantenere e migliorare questo progetto. Grazie! ❤️

---

Licenza
-------

[](#licenza)

MIT License. Vedi [LICENSE](LICENSE) per dettagli.

---

Credits
-------

[](#credits)

- **Fattura24** per le API
- **Sviluppatore:** [Simply IT](https://github.com/davidakis)
- **Contributori:** [Tutti i contributors](https://github.com/davidakis/fattura24-sdk/graphs/contributors)

---

Supporto
--------

[](#supporto)

- [Segnala malfunzionamenti](https://github.com/davidakis/fattura24-sdk/issues)
- [Discussioni](https://github.com/davidakis/fattura24-sdk/discussions)

---

Avviso
------

[](#avviso)

**Non affiliato a Fattura24.**
Questa è una SDK mantenuta dalla community per le API di Fattura24.

Per supporto ufficiale Fattura24, visita [www.fattura24.com](https://www.fattura24.com)

---

**Maintenuto da Simply IT**
*L'informatica, semplicemente*

[![Simply IT](https://camo.githubusercontent.com/ba0558db934743273421551e48bec019609f5e0302f71e42c25bb9fff0792e8e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53696d706c792d49542d626c7565)](https://github.com/davidakis)

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance83

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

7

Last Release

87d ago

Major Versions

1.0.0 → 2.0.02026-03-02

PHP version history (2 changes)1.0.0PHP >=8.1

2.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/a74a9418842b17cc715f93268542c2f75f6b7563f1f429285c2d19bc60317354?d=identicon)[davidakis](/maintainers/davidakis)

---

Top Contributors

[![davidakis](https://avatars.githubusercontent.com/u/39307124?v=4)](https://github.com/davidakis "davidakis (40 commits)")

---

Tags

electronic invoiceitalyfattura elettronicasdifattura24

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/simplyit-fattura24-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/simplyit-fattura24-sdk/health.svg)](https://phpackages.com/packages/simplyit-fattura24-sdk)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k16](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)