Le API di Fattura24 sono un’interfaccia software che ti permetterà di creare le tue fatture tramite semplici chiamate HTTPS.
Gli sviluppatori che utilizzano le nostre API potranno integrare facilmente il loro CRM o il loro e-commerce per automatizzare al 100% la creazione dei loro documenti.
Di solito le API dei servizi di fatturazioni sono molto complesse e ricche di opzioni, in Fattura24 abbiamo deciso di concentrarci sull’essenziale per permettere a tutti di integrarsi velocemente e senza impazzire.
Ecco cosa puoi fare con la nuova versione v.3.3 delle nostre API:
Le API di Fattura24 hanno un unico punto di accesso: https://www.app.fattura24.com/api/v0.3.
Tutte le chiamate dovranno essere cifrate tramite HTTPS ed eventuali chiamate non sicure potranno essere ignorate. A fronte di questo consigliamo di stabilire una connessione di prova con il nostro end point prima di inviare dati sensibili.
Per l’accesso alle funzionalità è necessario disporre di un’API KEY che potrà essere copiata accedendo dal proprio account al menu Configurazione > App e servizi esterni > API (nel sotto gruppo e-commerce e API).
Tutte le richieste sono caratterizzate da chiamate a servizi web con uno o più parametri passati in POST:
Questa è la chiamata che devi fare se vuoi verificare la validità dell’API KEY.
Come risultato l'API restituirà un XML simile a questo:
<root>
<returnCode>1</returnCode>
<description>Complimenti, la tua API KEY è corretta.</description>
</root>
Nota: In caso di errore, il campo returnCode conterrà -1 e la causa dell’errore sarà riportata nel campo description.
La chiamata che dovrai fare per creare un contatto cliente nella rubrica di Fattura24 avrà le seguenti caratteristiche.
<?xml version="1.0" encoding="UTF-8"?>
<Fattura24>
<Document>
<CustomerName>MARIO ROSSI</CustomerName>
<CustomerAddress>Via Alberti 8</CustomerAddress>
<CustomerPostcode>06122</CustomerPostcode>
<CustomerCity>Perugia</CustomerCity>
<CustomerProvince>PG</CustomerProvince>
<CustomerCountry></CustomerCountry>
<CustomerFiscalCode>MARROS66C44G217W</CustomerFiscalCode>
<CustomerVatCode>03912377542</CustomerVatCode>
<CustomerCellPhone>335123456789</CustomerCellPhone>
<CustomerEmail>info@rossi.i</CustomerEmail>
<FeCustomerPec>test@pec.it</FeCustomerPec>
<FeDestinationCode>0000000</FeDestinationCode>
</Document>
</Fattura24>
Le chiavi che permettono a Fattura24 di sapere se quel contatto è già presente in rubrica sono: P.IVA, codice fiscale e ragione sociale.
Alla prima chiave trovata, il sistema ignorerà le successive. In altre parole se viene trovato un contatto con la stessa P.IVA ricevuta in input, Fattura24 non verificherà le successive chiavi: codice fiscale e ragione sociale.
La chiamata che dovrai fare per creare un documento avrà le seguenti caratteristiche.
<Fattura24>
<Document>
<DocumentType>I</DocumentType>
<CustomerName>Mario Rossi</CustomerName>
<CustomerAddress>Via Alberti 8</CustomerAddress>
<CustomerPostcode>06122</CustomerPostcode>
<CustomerCity>Perugia</CustomerCity>
<CustomerProvince>PG</CustomerProvince>
<CustomerCountry></CustomerCountry>
<CustomerFiscalCode>MARROS66C44G217W</CustomerFiscalCode>
<CustomerVatCode>03912377542</CustomerVatCode>
<CustomerCellPhone>335123456789</CustomerCellPhone>
<CustomerEmail>info@rossi.it</CustomerEmail>
<DeliveryName>Mario Rossi</DeliveryName>
<DeliveryAddress>Via Alberti 8</DeliveryAddress>
<DeliveryPostcode>06122</DeliveryPostcode>
<DeliveryCity>Perugia</DeliveryCity>
<DeliveryProvince>PG</DeliveryProvince>
<DeliveryCountry></DeliveryCountry>
<Object>Oggetto del documento</Object>
<TotalWithoutTax>900.00</TotalWithoutTax>
<PaymentMethodName>Banca Popolare di.....</PaymentMethodName>
<PaymentMethodDescription>IT02L1234512345123456789012</PaymentMethodDescription>
<VatAmount>198.00</VatAmount>
<Total>1098.00</Total>
<FootNotes>Vi ringraziamo per la preferenza accordataci</FootNotes>
<SendEmail>true</SendEmail>
<F24OrderId>12345</F24OrderId>
<IdTemplate>123</IdTemplate>
<Payments>
<Payment>
<Date>2016-02-23</Date>
<Amount>2135</Amount>
<Paid>true</Paid>
</Payment>
</Payments>
<Rows>
<Row>
<Code>0001</Code>
<Description>PULIZIA NUM. DUE FINESTRE</Description>
<Qty>2</Qty>
<Um></Um>
<Price>200.00</Price>
<Discounts>0</Discounts>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
<Row>
<Code>0002</Code>
<Description>PULIZIA NUM. DUE FINESTRONI</Description>
<Qty>2</Qty>
<Um></Um>
<Price>250.00</Price>
<Discounts>0</Discounts>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
</Rows>
</Document>
</Fattura24>
Durante la creazione del documento, il sistema utilizzerà la P.IVA e/o il C.F. del cliente presente nella rubrica (aggiornato con i dati che avrai inserito nell’XML), in caso negativo verrà creato un nuovo contatto.
A salvataggio ultimato il sistema restituirà un XML con l’ID del documento creato.
<root>
<returnCode>0</returnCode>
<description>Operazione completata con successo</description>
<docId>953921</docId>
<docNumber>01/YYYY<docNumber>
</root>
Il campo docID sarà utile oltre alla creazione del documento anche per scaricare il file PDF.
Il campo docNumber conterrà il numero del documento creato.
In qualsiasi momento potrai scaricare il PDF dei tuoi documenti utilizzando il docId che il sistema ti ha restituito in fase di creazione dei documenti.
Questa è la chiamata che dovrai fare:
La chiamata che dovrai fare per creare una fattura elettronica avrà le seguenti caratteristiche.
<?xml version="1.0" encoding="UTF-8"?>
<Fattura24>
<Document>
<DocumentType>FE</DocumentType>
<CustomerName><![CDATA[Ferramenta Tal Dei Tali Srl]]></CustomerName>
<CustomerAddress><![CDATA[Via Roma n.49]]></CustomerAddress>
<CustomerPostcode>00100</CustomerPostcode>
<CustomerCity>Roma</CustomerCity>
<CustomerProvince>RM</CustomerProvince>
<CustomerCountry>IT</CustomerCountry>
<CustomerFiscalCode/>
<CustomerVatCode>01993350332</CustomerVatCode>
<CustomerCellPhone>test@test.com</CustomerCellPhone>
<CustomerEmail>test@test.it</CustomerEmail>
<Object><![CDATA[Vendita alla cassa]]></Object>
<FeCustomerPec>test@pec.it</FeCustomerPec>
<FeDestinationCode>0000000</FeDestinationCode>
<FePaymentCode>MP05</FePaymentCode>
<PaymentMethodName>UBI Banca</PaymentMethodName>
<PaymentMethodDescription>IT87A031110321</PaymentMethodDescription>
<TotalWithoutTax>220.00</TotalWithoutTax>
<VatAmount>44.00</VatAmount>
<Total>264.00</Total>
<FootNotes/>
<SendEmail>false</SendEmail>
<Rows>
<Row>
<Description><![CDATA[Prodotto A]]></Description>
<Qty>1</Qty>
<Price>100.00</Price>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
<Row>
<Description><![CDATA[Prodotto B]]></Description>
<Qty>1</Qty>
<Um/>
<Price>100.00</Price>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
<Row>
<Description><![CDATA[Spese di spedizione]]></Description>
<Qty>1</Qty>
<Price>20.00</Price>
<VatCode>0</VatCode>
<VatDescription>0%</VatDescription>
<FeVatNature>N4</FeVatNature>
</Row>
</Rows>
</Document>
</Fattura24>
PS: Le API di Fattura24 non permettono la creazione di nota di credito elettroniche.
In questo file potrai trovare un file xml di esempio per creare una semplice fattura elettronica: esempioFe.xml.
Come avrai notato l’XML è praticamente identico all’XML utilizzato per creare un documento generico o una fattura tradizionale in formato PDF.
Ci sono però 5 campi in più che devi tenere in considerazione perchè specifici per la fatturazione elettronica:
Se e solo se viene utilizzato MP05 dovrai valorizzare il tag PaymentMethodDescription con l’IBAN del venditore;
Nel precedente elenco la voce # andrà sostituita con una delle sotto codifiche previste dall’Agenzia delle Entrate (ad esempio: N2.3).
I campi FeCustomerPec e FeDestinationCode sono da considerarsi non obbligatori se il destinatario della fattura è un consumatore finale senza P.IVA, diversamente almeno uno dei due campi dovrà essere correttamente valorizzato.
La chiamata che dovrai fare per creare un corrispettivo avrà le seguenti caratteristiche:
<Fattura24>
<Document>
<DocumentType>19</DocumentType>
<Date>2021-01-01</Date>
<TotalWithoutTax>1000.00</TotalWithoutTax>
<VatAmount>222.00</VatAmount>
<Total>1222.00</Total>
<FootNotes></FootNotes>
<Rows>
<Row>
<Price>0.00</Price>
<VatCode>0</VatCode>
<VatDescription>0.0%</VatDescription>
</Row>
<Row>
<Price>1000.00</Price>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
</Rows>
<Payments>
<Payment>
<Date>2021-01-01</Date>
<Amount>1000.00</Amount>
<BillAccount>Contante</BillAccount>
<Paid>true</Paid>
</Payment>
</Payments>
</Document>
</Fattura24>
Puoi ottenere la lista dei modelli personalizzati dei documenti, facendo la seguente chiamata:
Puoi ottenere la lista dei conti, facendo la seguente chiamata:
Per associare un codice del piano dei conti al documento che si sta per creare è necessario aggiungere il tag IdPdc a ciascuna delle singole linee del documento.
In questo modo ad ogni voce nel documento sarà associato un codice del piano dei conti.
<Row>
<Code>0001</Code>
<Description>PULIZIA NUM. DUE FINESTRE A DUE ANTE</Description>
<Qty>2</Qty>
<Um></Um>
<Price>200.00</Price>
<Discounts>0</Discounts>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
<IdPdc>XXXX</IdPdc>
</Row>
Puoi ottenere la lista dei sezionali, facendo la seguente chiamata.
Puoi ottenere tutte le informazioni relative a un prodotto, facendo la seguente chiamata.
Con le API di Fattura24 puoi creare anche dei semplici crediti.
Un credito è una prestazione/prodotto che è stata già venduta/consegnata al cliente ma che vuoi fatturare manualmente in un secondo momento, ad esempio a fine mese.
La chiamata che dovrai fare per creare un credito avrà le seguenti caratteristiche.
<?xml version="1.0" encoding="UTF-8"?>
<Fattura24>
<Document>
<DocumentType>I</DocumentType>
<CustomerName>MARIO ROSSI</CustomerName>
<CustomerAddress>Via Alberti 8</CustomerAddress>
<CustomerPostcode>06122</CustomerPostcode>
<CustomerCity>Perugia</CustomerCity>
<CustomerProvince>PG</CustomerProvince>
<CustomerCountry></CustomerCountry>
<CustomerFiscalCode>MARROS66C44G217W</CustomerFiscalCode>
<CustomerVatCode>03912377542</CustomerVatCode>
<CustomerCellPhone>335123456789</CustomerCellPhone>
<CustomerEmail>info@rossi.it</CustomerEmail>
<Object>Oggetto del documento</Object>
<CustomField1></CustomField1>
<CustomField2></CustomField2>
<Rows>
<Row>
<Code>0001</Code>
<Description>PULIZIA NUM. DUE FINESTRE</Description>
<Qty>2</Qty>
<Um></Um>
<Price>200.00</Price>
<Discounts>0</Discounts>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
<Row>
<Code>0002</Code>
<Description>PULIZIA NUM. DUE FINESTRONI</Description>
<Qty>2</Qty>
<Um></Um>
<Price>250.00</Price>
<Discounts>0</Discounts>
<VatCode>22</VatCode>
<VatDescription>22%</VatDescription>
</Row>
</Rows>
</Document>
</Fattura24>
Anche in questo caso, durante la creazione del credito il sistema utilizzerà la P.IVA e/o il C.F. del cliente per cercarlo nella tua rubrica. Se la ricerca termina positivamente verrà utilizzato il tuo contatto in rubrica (aggiornato con i dati che avrai inserito nell’XML), in caso negativo verrà creato un nuovo contatto.
Come vedi l’xml è praticamente identico a quello necessario a creare la fattura tranne che per le info specifiche di una fattura.
Postman è un tool utilissimo che ti permetterà di familiarizzare velocemente le nostre API.
Per velocizzare al massimo i tuoi test abbiamo preparato un progetto Postman già pronto.
Per utilizzarlo ti basterà:
Puoi scaricare l’ultima versione del nostro progetto qui: Fattura24_API.postman_collection.json.zip.
Se non hai Postman, puoi scaricarne la versione gratuita qui: https://www.postman.com/downloads/.
Di seguito alcuni codici di esempio per integrare le API di Fattura24 utilizzando PHP e Visual Basic.
https://github.com/flaracca/fattura24-VB.NET;
https://github.com/flaracca/fattura24-PHP;
Fine, non c’è altro.
Come hai visto utilizzare le API di Fattura24 è veramente semplice e se volessi assistenza o supporto per un collaudo integrato consideraci a disposizione.