Le API di Fattura24
Le API di Fattura24 sono un’interfaccia software che ti permetterà di creare le tue fatture tramite semplici chiamate HTTP.
Gli sviluppatori che utilizzano le nostre API potranno integrare facilmente il loro CRM o il loro eCommerce 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 v0.3.3 delle nostre API:
- verificare la validità della tua API KEY
- creare un contatto cliente in rubrica
- creare ordini cliente, ricevute e fatture
- creare uno o più crediti da fatturare in un secondo momento
- aggiornare in automatico i dati del tuo cliente in rubrica
- scaricare il PDF del documento creato
URL di accesso all’API e sicurezza
Le API di Fattura24 hanno un unico punto di accesso
1 | 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
- fornire a Fattura24 gli indirizzi IP o il range di indirizzi IP associati ai server che effettueranno le richieste (opzionale)
È anche possibile legare l’API KEY ad un range di indirizzi IP in modo da permettere al nostro servizio di accettare le chiamate solo se provengono dai vostri server.
Limiti
Non ci sono limiti al numero di richieste giornaliere. Tuttavia, un numero eccessivo di richieste in un lasso di tempo troppo breve potrebbe tradursi in una sospensione del servizio in attesa di verifiche congiunte con voi.
Formati utilizzati
Tutte le richieste sono caratterizzate da chiamate a servizi web con uno o più parametri passati in POST.
- tutti i dati inviati a Fattura24 dovranno nel formato UTF-8
- tutte le date dovranno rispettare il formato AAAA-MM-GG
- i campi booleani dovranno essere valorizzati con ‘true’ o ‘false’
- tutti i campi numerici dovranno essere espressi nel formato decimale #.00
Verificare l’API KEY tramite API
Questa è la chiamata che devi fare se vuoi verificare la validità dell’API KEY
1 2 3 4 | URL: https://www.app.fattura24.com/api/v0.3/TestKey PARAMETRI IN POST "apiKey" API KEY associata al proprio account |
Come risultato l’API restituirà un XML simile a questo:
1 2 3 4 | <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’.
Creare un contatto cliente in rubrica
La chiamata che dovrai fare per creare un contatto cliente nella rubrica di Fattura24 avrà le seguenti caratteristiche.
1 2 3 4 5 | URL: https://www.app.fattura24.com/api/v0.3/SaveCustomer PARAMETRI IN POST "apiKey" API KEY associata al proprio account "xml" una stringa in formato XML "UTF-8" contenente i dati del documento da creare |
Di seguito troverai un esempio di file XML accettato dal sistema
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | <?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.it</CustomerEmail> </Document> </Fattura24> |
IMPORTANTE: Quando si salva un contatto cliente già presente nella propria rubrica, il sistema procederà ad aggiornare i suoi dati con quelli appena ricevuti.
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.
Come creare un documento
La chiamata che dovrai fare per creare un documento avrà le seguenti caratteristiche.
1 2 3 4 5 | URL: https://www.app.fattura24.com/api/v0.3/SaveDocument PARAMETRI IN POST "apiKey" API KEY associata al proprio account "xml" una stringa in formato XML "UTF-8" contenente i dati del documento da creare |
Di seguito troverai un esempio di file XML accettato dal sistema
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | <?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> <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> <UpdateStorage>1</UpdateStorage> <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 A DUE ANTE E DUE MANI DI SMALTO ALL’ACQUA COMPRESI IMBOTTI E CASSETTONI AVVOLGIBILI</Description> <Qty>2</Qty> <Um></Um> <Price>200.00</Price> <Discounts></Discounts> <VatCode>22</VatCode> <VatDescription>22%</VatDescription> </Row> <Row> <Code>0002</Code> <Description>PULIZIA NUM. DUE FINESTRONI A DUE ANTE E DUE MANI DI SMALTO ALL’ACQUA COMPRESI IMBOTTI E CASSETTONI AVVOLGIBILI</Description> <Qty>2</Qty> <Um></Um> <Price>250.00</Price> <Discounts></Discounts> <VatCode>22</VatCode> <VatDescription>22%</VatDescription> </Row> </Rows> </Document> </Fattura24> |
NOTE:
- L’attributo ‘DocumentType’ andrà valorizzato a ‘I’ se si vuole creare una Fattura, ‘R’ se si vuole creare una Ricevuta, ‘C’ se vuoi creare un Ordine Cliente o ‘N’ se vuoi creare una Nota di credito
- Se vuoi indicare tu il numero del documento dovrai aggiungere il tag <Number>XXXXX</Number>
- Se vuoi indicare tu la data del documento dovrai aggiungere il tag <Date>YYYY-MM-DD</Date>
- In assenza della partita IVA sul cliente, il sistema opterà per la creazione di una ricevuta anziché la fattura. Per forzare la creazione di una fattura sarà necessario valorizzare l’attributo ‘DocumentType’ con ‘I-force’
- Gli attributi ‘Price’ e ‘Total’ di ‘Row’ andranno valorizzati con gli importi al netto dell’IVA
- Se vuoi che il documento creato venga automaticamente inviato al cliente tramite email, dovrai valorizzare a ‘true’ il campo ‘SendEmail’, altrimenti a ‘false’
- Se il parametro ‘Paid’ presente in ‘Payment’ viene valorizzato a ‘true’, il pagamento verrà automaticamente reso disponibile anche nella Prima Nota di Fattura24
- Se vuoi che alla creazione del documento il magazzino non venga movimentato, valorizza a ‘0’ il campo ‘UpdateStorage’. Altrimenti la creazione di ordine impegna la merce, mentre la creaizone di una ricevuta/fattura la scarica dal magazzino
- Per annullare la movimentazione causata da un ordine, valorizza il campo ‘F24OrderId’ con l’Id dell’ordine
IMPORTANTE: prima di lanciare la chiamata alle nostre API effettua un URL Encoding dell’XML, altrimenti la chiamata andrà in errore.
Durante la creazione del documento, 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.
A salvataggio ultimato il sistema ti restituirà l’ID del documento creato.
1 2 3 4 5 6 | <root> <returnCode>0</returnCode> <description>Operazione completata con successo</description> <docId>953921</docId> <docNumber>01/YYYY<docNumber> </root> |
Il campo docID ti sarà utile se oltre alla creazione del documento volessi anche scaricare il relativo file PDF.
Il campo docNumber conterrà il numero del documento che è stato creato.
Come scaricare il PDF di un documento
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:
1 2 3 4 5 | URL: https://www.app.fattura24.com/api/v0.3/GetFile PARAMETRI IN POST "apiKey" API KEY associata al proprio account "docId" l'ID del documento del quale vuoi il PDF |
Come creare una fattura elettronica
La chiamata che dovrai fare per creare una fattura elettronica avrà le seguenti caratteristiche.
1 2 3 4 5 | URL: https://www.app.fattura24.com/api/v0.3/SaveDocument PARAMETRI IN POST "apiKey" API KEY associata al proprio account "xml" una stringa in formato XML "UTF-8" contenente i dati della fattura elettronica da creare |
Di seguito troverai un esempio di file XML accettato dal sistema
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | <?xml version="1.0" encoding="UTF-8"?> <?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>FZLUBAI</FeDestinationCode> <FePaymentCode>MP05</FePaymentCode> <PaymentMethodName>UBI Banca</PaymentMethodName> <PaymentMethodDescription>IT87A031110321000000000999999</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> |
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ò 4 campi in più che devi tenere in considerazione perchè specifici per la fatturazione elettronica:
- VatType andrà aggiunto se è necessario indicare l’Esigibilità IVA (I: immediata, S: Split payment)
- FeCustomerPec andrà valorizzato con l’indirizzo PEC (se disponibile) del cliente al quale si sta emettendo fattura
- FeDestinationCode andrà valorizzato con il codice destinatario del cliente (se disponibile)
- FePaymentCode andrà valorizzato con uno di questi valori:
- ‘MP01’ per i pagamenti in contanti
- ‘MP05’ per i pagamenti tramite bonifico
- ‘MP08’ per i pagamenti tramite carta di credito
- ‘MP12’ per i pagamenti tramite Riba
se e solo se viene utilizzato ‘MP05’ dovrai valorizzare il tag ‘PaymentMethodDescription’ con l’IBAN del venditore
- FeVatNature andrà aggiunto nello ‘row’ di dettaglio dei prodotti/servici se e solo se l’aliquota di riferimento è allo 0%. Il campo serve per indicare all’Agenzia delle Entrate la tipologia di aliquota e andrà valorizzato con uno di questi valori:
- ‘N1’ escluse ex art. 15
- ‘N2’ non soggette
- ‘N3’ non imponibili
- ‘N4’ esenti
- ‘N5’ regime del margine
- ‘N6’ inversione contabile (reverse charge)
IMPORTANTE: 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.
ATTENZIONE: la fatturazione elettronica è un’innovazione enorme per il nostro paese, dovremo abituarci noi che emettiamo fatture ma anche i nostri clienti che le ricevono.
Quest’ultimi, come saprete, non sempre forniscono i dati corretti per l’emissione delle fatture e questo ci obbliga ad essere molto cauti nell’attivare i nostri automatismi.
A fronte di questo l’invio automatico delle fatture all’Agenzia delle Entrate sarà per i primi mesi del 2019 disabilitato, sarà quindi vostra cura entrare in Fattura24, aprire le fatture create tramite API, verificare che i dati dei vostri clienti siano corretti e quindi inviare la fattura all’Agenzia delle Entrate cliccando sull’apposito pulsante ‘Invio’.
Come ottenere la lista dei modelli dei documenti
Puoi ottenere la lista dei modelli personalizzati dei documenti, facendo la seguente chiamata:
1 2 3 4 | URL: https://www.app.fattura24.com/api/v0.3/GetTemplate PARAMETRI IN POST "apiKey" API KEY associata al proprio account |
Come ottenere il Piano dei conti
Puoi ottenere la lista dei conti, facendo la seguente chiamata:
1 2 3 4 | URL: https://www.app.fattura24.com/api/v0.3/GetPdc PARAMETRI IN POST "apiKey" API KEY associata al proprio account |
Come ottenere la lista dei sezionali
Puoi ottenere la lista dei sezionali, facendo la seguente chiamata:
1 2 3 4 | URL: https://www.app.fattura24.com/api/v0.3/GetNumerator PARAMETRI IN POST "apiKey" API KEY associata al proprio account |
Come ottenere informazioni su una prestazione/prodotto
Puoi ottenere tutte le informazioni relative a un prodotto, facendo la seguente chiamata:
1 2 3 4 5 6 | URL: https://www.app.fattura24.com/api/v0.3/GetProduct PARAMETRI IN POST "apiKey" API KEY associata al proprio account "code" codice del prodotto "category" categoria del prodotto |
Come creare un credito
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.
1 2 3 4 5 | URL: https://www.app.fattura24.com/api/v0.3/SaveItem PARAMETRI IN POST "apiKey" API KEY associata al proprio account "xml" una stringa in formato XML "UTF-8" contenente i dati dei cediti da creare |
Di seguito troverai un esempio di file XML accettato dal sistema
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | <?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 A DUE ANTE E DUE MANI DI SMALTO ALL’ACQUA COMPRESI IMBOTTI E CASSETTONI AVVOLGIBILI</Description> <Qty>2</Qty> <Um></Um> <Price>200.00</Price> <Discounts></Discounts> <VatCode>22</VatCode> <VatDescription>22%</VatDescription> </Row> <Row> <Code>0002</Code> <Description>PULIZIA NUM. DUE FINESTRONI A DUE ANTE E DUE MANI DI SMALTO ALL’ACQUA COMPRESI IMBOTTI E CASSETTONI AVVOLGIBILI</Description> <Qty>2</Qty> <Um></Um> <Price>250.00</Price> <Discounts></Discounts> <VatCode>22</VatCode> <VatDescription>22%</VatDescription> </Row> </Rows> </Document> </Fattura24> |
IMPORTANTE: prima di lanciare la chiamata alle nostre API effettua un URL Encoding dell’XML altrimenti la chiamata andrà in errore.
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.
PHP e Visual Basic: esempio per integrare le API
Di seguito alcuni codici di esempio per integrare le API di Fattura24 utilizzando PHP e Visual Basic.
IMPORTANTE: questi moduli sono stati realizzati da uno sviluppatore indipendente. Per qualsiasi chiarimento vi invitiamo a contattare direttamente
l’autore: qui il suo account GitHub.
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.
Questa funzionalità potrebbe essere utile ad altri? Aiutaci a farla conoscere
