Richiesta massiva delle fatture dall'Agenzia delle Entrate

Premessa

Le seguenti API consentono di scaricare massivamente dall'Agenzia delle Entrate i documenti di fattura emessi o ricevuti da aziende italiane.

I criteri generali di utilizzo di queste API (endpoint, autenticazione, gestione degli errori, paginazione) sono gli stessi già disponibili nella documentazione principale.

Il requisito per effettuare la richiesta per conto di un'azienda è che il titolare della partita IVA (o il suo delegato), abbia affettuato la seguente procedura:

  1. • Accedere al "Portale Fatture e Corrispettivi": https://ivaservizi.agenziaentrate.gov.it/
  2. • Cliccare sul link "Consultazione" > "Censimento canale per forniture massive"
  3. • Cliccare su bottone "Aggiungi provider"
  4. • Nella casella "Filtra tra i risultati" scrivere "ITALA"
  5. • Nella riga corrispondente a "Itala Tecnologia Informatica S.r.l." cliccare a destra sul bottone sotto a "Seleziona"
  6. • Selezionare "Scarico Fatture" e cliccare "Salva configurazione"

Invio di una richiesta massiva

Richiesta

POST [endpoint]/richieste-massive

Corpo della richiesta (esempio):

{
    "partita_iva":    "12345678901", <-- partita iva di una azienda che deve già essere censita nell'anagrafica aziende dell'account
    "data_da":        "2025-01-01", <-- massimo 3 anni solari indietro, incluso quello corrente
    "data_a":         "2025-03-31", <-- massimo 3 mesi di distanza da "data_da"
    "tipo_richiesta": "EMESSE|RICEVUTE", <-- selezionare uno dei due tipi
}

Risposta (esempio):

{
    "id": 1234, <-- identificativo della richiesta, da salvare
    "file_richiesta": "[stringa contenente un file xml che andrà firmato digitalmente in formato CAdES (p7m) dal titolare della partita iva o suo delegato]"
}

Nota: l'invio di una richiesta di scarico massivo ha un costo di 1 credito.

Apposizione firma digitale

Richiesta

PATCH [endpoint]/richieste-massive/[ID]

Corpo della richiesta (esempio):

{
    "file_richiesta_signed_base64": "[stringa contenente il file di richiesta precedentemente ottenuto, formato digitalmente in formato CAdES (p7m) dal titolare della partita iva o suo delegato]"
}

Nota: questo passaggio può essere eliminato con l'apposizione automatica di una firma digitale. Contattare l'assistenza per maggiori informazioni.

Verifica stato richiesta

L'Agenzia delle Entrate impiega normalmente almeno 24 ore per elaborare le richieste.

A intervalli regolari (es. ogni 30 o 60 minuti) verificare lo stato della richiesta, nel seguente modo.

Richiesta

GET [endpoint]/richieste-massive/[ID]

Risposta (esempio):

{
    "id":                      1234,
    "dt_richiesta":            "aaaa-mm-gg oo:mm:ss",
    "partita_iva":             "12345678901",
    "data_da":                 "aaaa-mm-gg",
    "data_a":                  "aaaa-mm-gg",
    "stato":                   "ERRORE|CREATO|ELABORAZIONE|PRONTO|PAGATO|ESEGUITO",
    "messaggio":               "[eventuale messaggio di errore]",
    "dt_aggiornamento":        "aaaa-mm-gg oo:mm:ss",
    "num_documenti":           [numero dei documenti/fatture da scaricare],
    "data_fine_disponibilita": "aaaa-mm-gg" <-- data oltre la quale non sarà più possibile scaricare i documenti trovati
}

Se c'è stato un errore, lo stato sarà "ERRORE" e il campo "messaggio" conterrà la descrizione del problema incontrato.

Se lo stato è "ELABORAZIONE", il download non è ancora pronto.

Se lo stato è "PRONTO", il campo "num_documenti" conterrà il numero di documenti disponibili per il download e "data_fine_disponibilita" indicherà fino a quando i file saranno disponibili per il download. Per procedere, sarà necessario effettuare il pagamento.

Elenco richieste

È possibile ottenere un elenco delle richieste massive effettuate, con i relativi stati e dettagli.

GET [endpoint]/richieste-massive

È possibile filtrare i risultati, includendo in query-string i parametri partita_iva, dt_richiesta_da, dt_richiesta_a

Pagamento e ricezione dei documenti

Se la richiesta è in stato "PRONTO", effettuando il pagamento, si richiede il download dei documenti.

Il costo dell'operazione è di 1 credito per ogni documento da scaricare. I crediti vengono addebitati sull'abbonamento o sui crediti disponibili con le ricariche effettuate.

Se i crediti non sono sufficienti, viene ritornato un errore. Nota: è possibile effettuare una ricarica tramite API, come indicato più sotto.

Richiesta

POST [endpoint]/richieste-massive/[ID]/pagamento

In assenza di messaggi di errore, il campo "stato" passerà a "PAGATO".

Entro 5 minuti lo stato sarà passato a "ESEGUITO" e le fatture saranno disponibili come nuove fatture da leggere, tramite le API o tramite Webhook come descritte nella documentazione principale

Le fatture scaricate massivamente conterranno la proprietà "origine" valorizzato a 'R' (Richiesta Massiva). Dunque, in fase di ricezione delle fatture (ad esempio via webhook) è possibile distinguere le fatture scaricate massivamente dalle altre.

Ottenere informazioni sul proprio credito

È possibile ottenere le informazioni complete sul proprio credito

Richiesta

GET [endpoint]/credito

Risposta (esempio):

{
    "cod_abbonamento":                "FEA-M50|FEA-M500|FEA-M5000|FEA-M50000", <-- codice identificativo dell'eventuale abbonamento sottoscritto
    "data_fine_abbonamento":          "aaaa-mm-gg", <-- data di scadenza dell'abbonamento
    "max_documenti_mese_abbonamento": 500, <-- numero di documenti mensili inclusi nell'abbonamento
    "credito_residuo":                1000, <-- eventuale credito ricaricato
    "data_scadenza_credito":          "aaaa-mm-gg" <-- data di scadenza del credito ricaricato
    "consumo_mese":                   500, <-- numero di crediti consumati nel mese solare corrente
}

Effettuare una ricarica

Richiesta

POST [endpoint]/credito

Corpo della richiesta (esempio):

{
    "azione":                "ricarica",
    "credito_da_ricaricare": 1000, <-- valori ammessi: 100, 1000, 10000, 100000
}

Il costo delle ricariche è indicato nel listino prezzi on-line.

In caso di esito positivo, viene ritornato l'oggetto json come sopra.