Le API di Fattura24 – mai così semplici

Le API di Fattura24 sono un’interfaccia software che ti permetterà di creare le tue fatture tramite semplici chiamate HTTP.

Carlo Camusso Carlo Camusso

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.1 delle nostre API:

  • verificare la validità della tua API KEY
  • 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 della fattura creata

URL di accesso all’API e sicurezza
Le API di Fattura24 hanno un unico punto di accesso

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:

  1. disporre di un API KEY che potrà essere richiesto scrivendo a info@fattura24.com
  2. fornire a Fattura24 gli indirizzi IP o il range di indirizzi IP associati ai server che effettueranno le richieste (opzionale)

E’ 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

Come risultato l’API restituirà un XML simile a questo:

Nota: In caso di errore, il campo ‘returnCode’ conterrà ‘-1′ e la causa dell’errore sarà riportata nel campo ‘description’

Come creare un documento

La chiamata che dovrai fare per creare un documento avrà le seguenti caratteristiche.

Di seguito troverai un esempio di file XML accettato dal sistema

NOTE:

  • L’attributo ‘DocumentType’ andrà valorizzato a ‘I’ se si vuole creare una fattura, ‘R’ se si vuole creare una ricevuta o ‘C’ se vuoi creare un ordine cliente
  • 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’

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.

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 una fattura

In qualsiasi momento potrai scaricare il PDF delle tue fatture utilizzando l’idDoc che il sistema ti ha restituito in fase di creazione dei documenti
Questa è la chiamata che dovrai fare:

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.

Di seguito troverai un esempio di file XML accettato dal sistema

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.

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