Premessa

Le REST API 2.0 sono compatibili con qualsiasi client per API RESTful.

Se stai sviluppando in PHP, puoi scaricare la nostra libreria già pronta: https://github.com/clixclix2/Fattura-Elettronica-API-PHP-Client, corredata di esempi di utilizzo.

È possibile comprenderle e testarle online con Postman

Endpoint

Endpoint di test:

https://fattura-elettronica-api.it/ws2.0/test

Endpoint di produzione:

https://fattura-elettronica-api.it/ws2.0/prod

Gestione degli errori

Tutte le risposte API contengono una stringa JSON.

Se non ci sono errori, il codice della risposta http sarà 200 (pagina trovata e gestita senza errori)

Quando ci sono errori, il codice della risposta http sarà 400, 401 oppure 404. In caso di errore, il corpo della risposta conterrà il campo "error":

{
    "error": "messaggio di errore"
}

Paginazione

Tutte le chiamate di tipo GET hanno un limite massimo di 1000 risultati trasmessi dal server. Per le opzioni di paginazione, vedere gli approfondimenti

Autenticazione

È possibile autenticare ogni chiamata API mediante Basic Authentication, inviando negli Header della richiesta HTTP la seguente riga:

Authorization: Basic [basic-auth-string]

dove [basic-auth-string] si ottiene concatenando username, il carattere ":" e la password ed eseguendo una codifica "base64" sulla stringa ottenuta.

In alternativa, è possibile autenticare le chiamate API mediante autenticazione "Bearer". Per maggiori informazioni, vedere gli approfondimenti.

Invio di una Fattura Elettronica da XML

Se hai già generato l'XML della fattura elettronica, puoi inviare il documento così com'è.

Il sistema (FatturaElettronicaAPI) aggiungerà o modificherà la sezione relativa ai dati di trasmissione (sezione FatturaElettronicaHeader/DatiTrasmissione dell'XML), per inserire i propri riferimenti ed i propri codici sequenziali, senza i quali l'invio verrebbe scartato dal SDI.

Richiesta

POST [endpoint]/fatture

Inserire negli Header della richiesta

Content-Type: application/xml

Corpo della Richiesta

<?xml version="1.0" encoding="UTF-8"?><p:FatturaElettronica ....>...fattura xml completa...</p:FatturaElettronica>

Risposta (esempio)

{
    "id":                 [identificativo univoco numerico fattura-elettronica-api],
    "sdi_identificativo": [identificativo trasmissione fornito dal SDI, numerico, oppure null],
    "sdi_nome_file":      "[il nome del file trasmesso]",
    "sdi_fattura":        "[il documento xml effettivamente trasmesso]",
    "sdi_stato":          "[INVI|ERRO]", -- INVI=Inviato, ERRO=Errore
    "sdi_messaggio":      "[eventuale messaggio di errore]"
}

Nota: se sdi_identificativo contiene null e sdi_stato è "INVI", vuol dire che il sistema ha preso in carico la trasmissione senza riuscire a fornire subito il l'identificativo SDI, che potrà quindi essere acquisito al momento della ricezione degli aggiornamenti di spedizione

Invio di una Fattura Elettronica dai Dati

È possibile inviare una fattura elettronica specificando solo i dati strettamente necessari.

Per poter utilizzare questa modalità, nel gestionale vanno compilati tutti i campi di anagrafica dell'azienda.

Richiesta

POST [endpoint]/fatture

Inserire negli Header della richiesta

Content-Type: application/json

Corpo della Richiesta (esempio)

{
    "destinatario": {
        "CodiceSDI": "0000000",
        "PartitaIVA": "00000000000",
        "Denominazione": "Azienda di Test SpA",
        "Indirizzo": "Via di Test, 4",
        "CAP": "00100",
        "Comune": "Roma",
        "Provincia": "RM"
    },
    "documento": {
        "Data": "2023-10-03",
        "Numero": "10"
    },
    "righe": [
        {
            "Descrizione": "Servizio 1",
            "PrezzoUnitario": "100.00",
            "AliquotaIVA": 22
        }
    ]
}

Se state lavorando in una configurazione multi-azienda, dovrete aggiungere nel corpo della richiesta anche la partita iva dell'azienda che emette il documento

    "piva_mittente": "00000000000"

Per una lista completa dei valori che è possibile inserire nella fattura, vedere gli approfondimenti

La risposta sarà analoga al caso dell'Invio da XML, sopra riportato.

Ricezione delle fatture e degli aggiornamenti di trasmissione

Richiesta

GET [endpoint]/fatture

È possibile aggiungere i seguenti parametri opzionali nella querystring in GET, per filtrare i risultati desiderati

unread      -- impostare a true per ricevere solo gli aggiornamenti non ancora letti
date_from   -- data di aggiornamento iniziale, formato 'yyyy-mm-dd hh:mm:ss' oppure 'yyyy-mm-dd'
date_to     -- data di aggiornamento finale, formato 'yyyy-mm-dd hh:mm:ss' oppure 'yyyy-mm-dd'
id_from     -- ID iniziale
id_to       -- ID finale
sdi_id_from -- identificativo SDI iniziale
sdi_id_to   -- identificativo SDI finale
sdi_id      -- identificativo SDI
partita_iva -- in una configurazione multi-azienda, specifica di volere solo i documenti riguardanti un'azienda

Risposta (esempio)

[
    {
        "ricezione": 1,
        "id":                     [identificativo univoco numerico fattura-elettronica-api],
        "sdi_fattura_base64":     "[documento originale (con eventuale firma digitale del mittente) - codificato in base64]",
        "sdi_fattura_xml":        "[documento decodificato da eventuali firme digitali]",
        "sdi_identificativo":     [identificativo trasmissione del SDI, numerico],
        "sdi_data_aggiornamento": "[data ultimo aggiornamento - formato yyyy-mm-dd hh:mm:ss]",
        "sdi_messaggio":          "[eventuale messaggio dal SDI]",
        "sdi_nome_file":          "[nome del file ricevuto]",
        "dati_documento":         [dati strutturati del documento, estratti dall'XML (contiene: mittente, destinatario, documento, righe)]
    },
    ...
    {
        "ricezione": 0,
        "id":                     [identificativo univoco numerico fattura-elettronica-api],
        "sdi_identificativo":     [identificativo SDI della fattura trasmessa, numerico],
        "sdi_stato":              "INVI"|"ERRO"|"CONS"|"NONC"  per fatture inviate alla Pubblica Amministrazione: "ACCE"|"RIFI"|"DECO",
        "sdi_messaggio":          "[eventuale messaggio dal SDI]",
    },
    ...
]

Nota: questa API ritorna sia le nuove fatture ricevute (righe con ricezione=1) sia gli aggiornamenti sulla trasmissione delle fatture (righe con ricezione=0)

Legenda stati: "INVI"=Inviato, "ERRO"=Errore (vedere messaggio), "CONS"=Consegnato, "NONC"=Non Consegnato (ma il mittente ha comunque ottemperato al suo obbligo),
Solo per le fatture inviate alla Pubblica Amministrazione: "ACCE"=Accettato, "RIFI"=Rifiutato, "DECO"=Decorrenza termini, ovvero accettazione implicita

È possibile ottenere gli aggiornamenti di una singola spedizione.

Richiesta

GET [endpoint]/fatture/[ID]

Risposta

{
    "ricezione": 0,
    "id":                     [identificativo univoco numerico fattura-elettronica-api],
    "sdi_identificativo":     [identificativo SDI della fattura trasmessa, numerico],
    "sdi_stato":              "INVI"|"ERRO"|"CONS"|"NONC"|  per fatture inviate alla Pubblica Amministrazione: "ACCE"|"RIFI"|"DECO",
    "sdi_messaggio":          "[eventuale messaggio dal SDI]",
}

Ricezione delle fatture e degli aggiornamenti di trasmissione via Webhook

Configurando nel gestionale l'apposito campo Webhook (URL e Token), è possibile ottenere in modalità push lo stesso json della chiamata API "GET [endpoint]/fatture", limitato agli aggiornamenti ancora non letti.

All'arrivo di uno o più aggiornamenti dal SDI, FatturaElettronicaAPI invocherà subito il Webhook eventualmente configurato, trasmettendo in POST nel body la stringa json.

Per validare la chiamata lato webhook, FatturaElettronicaAPI trasmetterà un Header http di questo tipo: "Authorization: Bearer [token]" dove [token] sarà il valore da te inserito nel gestionale.

Se FatturaElettronicaAPI otterrà dal Webhook una risposta senza errori (codice risposta http 200), il sistema riterrà consegnati i relativi aggiornamenti.

Nel caso in cui FatturaElettronicaAPI non ricevesse un codice risposta http 200, il sistema tenterà invii successivi distanziati di 3 ore, fino ad un massimo di 3 giorni di tentativi.

Ricezione della fattura in formato PDF

È possibile ottenere una rappresentazione in PDF della fattura

Richiesta

GET [endpoint]/fatture/[ID]/pdf

In caso di successo, FatturaElettronicaAPI risponde inviando il PDF in formato binario, anteceduto dal Header http:

Content-Type: application/pdf

Ricezione degli allegati delle fatture

Il formato XML delle fatture elettroniche consente di aggiungere file allegati.

Questa API consente di ottenerli, già decodificati e decompressi

Richiesta

GET [endpoint]/fatture/[ID]/allegati

Risposta (esempio)

[
    {
        "nome_file":   "allegato.pdf",
        "descrizione": "eventuale descrizione del documento",
        "file_base64": "file codificato base64"
    },
    ...
]

Gestione multi-aziende via API

Per gli utenti abilitati alla gestione multi-azienda, è possibile gestire l'anagrafica delle aziende anche via API

POST [endpoint]/aziende

Nota: I campi obbligatori sono: ragione_sociale, piva, cfis

PUT [endpoint]/aziende/[ID]

Nota: è possibile specificare nel json inviato solo i dati da aggiornare

GET [endpoint]/aziende

GET [endpoint]/aziende/[ID]

DELETE [endpoint]/aziende/[ID]

Tutte le chiamate POST e PUT richiedono di inviare il giusto Header http:

Content-Type: application/json

In caso di successo, tutte le chiamate, ad eccezione di "GET [endpoint]/aziende" che ritorna una lista, ritornano l'oggetto in formato JSON. Esempio:

{
    "id": "12345",
    "descrizione": "", (eventuali note)
    "ragione_sociale": "Azienda di test Srl",
    "indirizzo": "",
    "cap": "",
    "citta": "",
    "provincia": "", (sigla)
    "paese": "",
    "piva": "00000000000",
    "cfis": "00000000000",
    "forma_giuridica": null, (valori: ind|ss|snc|sas|spa|sapa|srl|srlsem|srlrid|coop|altro)
    "tipo_regime_fiscale": null, (valori: come da classificazione dell'Agenzia delle Entrate. Es. RF01=Ordinario, RF02=Contribuenti minimi, etc.)
    "albo_professionale": "", (nome dell'eventuale albo professionale)
    "provincia_albo": "", (sigla della provincia dell'eventuale albo professionale)
    "numero_iscrizione_albo": "",
    "data_iscrizione_albo": null, (data nel formato aaaa-mm-gg)
    "rea_ufficio": "", (sigla della provincia dell'eventuale camera di commercio di iscrizione)
    "rea": "", (numero dell'eventuale iscrizione alla camera di commercio)
    "capitale_sociale": null, (valore in euro - es: '20000.00')
    "socio_unico": null, (0=no, 1=sì)
    "liquidazione": null, (0=no, 1=sì)
    "telefono_amministrazione": "",
    "email_amministrazione": "",
    "legale_rappresentante_nome": "",
    "legale_rappresentante_cfis": "",
    "iban": "IT99A0000000000000000",
    "data_inserimento": "2023-10-07 19:17:43"
}

Nota: nel caso in cui le fatture vengano inviate a fattura-elettronica-api già in formato XML, gli unici dati obbligatori sono: piva e cfis

Approfondimenti: Paginazione

Tutte le richieste di tipo GET che non abbiano un [ID] specificato, ritornano liste di risultati.

FatturaElettronicaAPI per default ritorna al massimo 100 risultati.

Per ottenere più risultati, è possibile inviare in querystring il parametro per_page. Esempio:

GET [endpoint]/[risorsa]?per_page=1000

dove 1000 è il massimo valore consentito.

Per ottenere le pagine successive alla prima, è possibile inviare in querystring il parametro page. Esempio:

GET [endpoint]/[risorsa]?per_page=1000&page=2

Se otteniamo una lista vuota, significa ovviamente che non ci sono altre pagine di risultati.

Un altro modo per sapere se è presente un'altra pagina di risultati è cercare negli Header della risposta http una riga di questo tipo:

Link: <https://...../?per_page=xxx&page=x>; rel="next"

È possibile prelevare tale URL ed utilizzarlo per richiedere la pagina successiva

Approfondimenti: Autenticazione

Ogni chiamata API può essere autenticata tramite Basic-Authentication HTTP.

In alternativa, è possibile autenticare le chiamate API mediante autenticazione "Bearer", inviando negli Header della richiesta HTTP la seguente riga:

Authorization: Bearer [bearer-token]

dove [bearer-token] è una stringa ottenuta invocando l'API "/authentication" con Basic Authentication.

Richiesta

POST [endpoint]/authentication

includendo gli header di basic authentication.

Esempio Risposta

{
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expires": "yyyy-mm-dd hh:mm:ss"
}

Nota: per ogni chiamata API con basic-authentication, viene ritornato negli header della risposta http anche il token per l'autenticazione Bearer, in questo formato:

X-auth-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Volendo, è dunque possibile effettuare la prima chiamata API con basic-authentication e le successive con bearer-authentication, estrapolando il token Bearer dalla risposta della prima chiamata e senza mai aver invocato esplicitamente l'API di autenticazione

Approfondimenti: Dati fattura

Quando si invia una fattura dai dati semplici, è possibile specificare molteplici dati necessari alla creazione di una fattura elettronica.

Ecco la lista completa:

{
    "piva_mittente": "11111111111", -- necessario in scenari multi-azienda
    "destinatario": {
        "CodiceSDI": "0000000",
        "PEC": "pec@pec.it",
        "PartitaIVA": "00000000000",
        "CodiceFiscale": "00000000000",
        "Denominazione": "Azienda di Test SpA",
        "Indirizzo": "Via di Test, 4",
        "CAP": "00100",
        "Comune": "Roma",
        "Provincia": "RM"
    },
    "documento": {
        "tipo": "[tipo-documento]", -- FATT|NDC - default FATT
        "Data": "2023-10-03",
        "Numero": "10",
        "Causale": "[descrizione generale causale del documento]",
        "ImportoRitenuta": "20.00",
        "AliquotaRitenuta": "20.00",
        "CausalePagamento": "[causale pagamento ritenuta]",
        "DatiBollo": {
            "BolloVirtuale": "",
            "ImportoBollo": ""
        }
    },
    "righe": [
        {
            "Descrizione": "Servizio 1",
            "PrezzoUnitario": "100.00",
            "AliquotaIVA": 22,
            "Quantita": 1,
            "ScontoMaggiorazione": {
                "Tipo": "",
                "Percentuale": "",
                "Importo": ""
            },
            "Natura": "",
            "CodiceArticolo": {
                "CodiceTipo": "",
                "CodiceValore": ""
            },
            "UnitaMisura": "",
            "EsigibilitaIVA": ""
        }
    ]
}