FiscoAPI è un servizio offerto dalla Wi-Tek Group srl per l'utilizzo automatizzato tramite REST API dei dati messi a disposizione del sito delle Agenzia delle Entrate.
Le API di tipo CORE consentono di replicare le operazioni disponibili sul sito dell'Agenzia delle Entrate, come la consultazione dell'elenco delle fatture emesse e ricevute, il download del file XML di una singola fattura e il download massivo di fatture. Queste funzionalità sono accessibili attraverso l'invocazione di servizi REST che simulano un client web, garantendo un'integrazione fluida con i sistemi aziendali. L'utilizzo di queste API migliora l'efficienza nella gestione fiscale e assicura una maggiore automazione dei processi contabili. Inoltre, l'accesso diretto ai dati tramite API riduce la necessità di interazioni manuali con il portale dell'Agenzia, minimizzando possibili errori e risparmiando tempo prezioso per le imprese.
Con questa funzionalità sarà possibile generare una richiesta (ad esempio, scaricamento fatture, reperimento pagamenti F24, ecc.) tramite un link condivisibile. L'utente che accederà alla pagina web del link potrà autenticarsi tramite SPID/CIE e le informazioni richieste verranno recuperare in modo automatico, senza necessità di interventi manuali. Ad esempio, questo servizio può risultare particolarmente utile per i commercialisti, che potranno inviare ai propri clienti richieste di scaricamento automatico delle fatture elettroniche, ottimizzando i tempi di gestione e riducendo il rischio di errori.
Le API di tipo AUTOMATION offrono la possibilità di eseguire in un'unica chiamata più operazioni precedentemente disponibili tramite le API CORE, come il download massivo di fatture elettroniche per diverse partite IVA contemporaneamente. Questa funzionalità consente di automatizzare processi complessi, riducendo significativamente il tempo necessario per l'elaborazione manuale di ciascuna richiesta individuale. Grazie all'integrazione di più servizi in un'unica API, si potrà aumentare l'efficienza operativa nella gestione fiscale e contabile, garantendo al contempo l'accuratezza dei dati e la conformità alle normative vigenti. L'utilizzo delle API AUTOMATION facilita l'accesso centralizzato alle informazioni fiscali, ottimizzando le risorse interne e riducendo il rischio di errori associati a operazioni manuali ripetitive.
È possibile accedere alle REST API tramite il seguente link https://api.fiscoapi.com/api_esterne/
Per attivare il servizio di REST API di FiscoAPI bisogna andare sulle impostazioni del proprio profilo utente in FiscoAPI.
Dove sarà possibile abilitare/disabilitare il servizio REST API e ottenere la chiave segreta da usare per l'autenticazione.
Per attivare la chiave API, accedi al portale di FiscoAPI e nella sezione "Impostazioni", genera una chiave segreta che dovrai utilizzare per creare le chiavi pubbliche usate per l'autenticazione delle API.
Vedi la nostra quickstart guide per maggiori informazioni.
Dopo aver attivato il servizio API dal portale, si potrà utilizzare la chiave_segreta del tuo account per generare una chiave pubblica.
La chiave segreta non deve essere condivisa con nessuno ma utilizzata solamente dal tuo server, diversamente potrebbe essere utilizzata da altri consumando le tue quote e limiti di utilizzo.
La chiave pubblica ha le seguenti caratteristiche:
/crea_chiave_pubblica
Bearer token
delle REST API che richiedi al nostro sistema;
L’endpoint /crea_chiave_api
si occupa della generazione della chiave pubblica.
NB: Qualsiasi aggiornamento della chiave segreta invaliderà tutti i token precedentemente rilasciati. Il client dovrà quindi ottenere nuovi token tramite il processo di autenticazione o refresh.
Campo | Location | Description |
---|---|---|
chiave_segreta string, required |
body | La chiave segreta associata al tuo account, che trovi nella impostazioni del nostro portale |
Questa richiesta non necessita di autenticazione, la sicurezza è garantita dalla presenza della chiave segreta.
POST https://api.fiscoapi.com/api_esterne/crea_chiave_api
Campo | Location | Description |
---|---|---|
chiave_pubblica |
string | Chiave pubblica da utilizzare per autenticare tutte le chiamate HTTP |
refresh_token |
string | Refresh token da utilizzare per creare una nuova chiave pubblica in caso di scadenza |
Oggetto di tipo Errori:
L’endpoint /refresh_chiave_api
permette di ottenere una nuova chiave_pubblica quando quella attuale è scaduta, senza passare di nuovo dalla richiesta di creazione chiave pubblica.
Quindi si può usare il refresh_token
per ottenere una nuova chiave senza dover esporre la chiave segreta.
Es. Il sito del tuo cliente richiede tramite api verso il tuo server una chiave pubblica, e poi quando dopo 1h scade, può evitare di fare di nuovo una chiamata al tuo server utilizzando il refresh_token direttamente dal tuo sito.
NB: Qualsiasi aggiornamento della chiave segreta invaliderà tutti i token precedentemente rilasciati. Il client dovrà quindi ottenere nuovi token tramite il processo di autenticazione o refresh.
Campo | Location | Description |
---|---|---|
refresh_token string, required |
body | Il refresh token che ti è stato fornito nella richiesta di creazione della chiave pubblica. |
Questa richiesta non necessita di autenticazione, la sicurezza è garantita dalla presenza del refresh token stesso.
POST https://api.fiscoapi.com/api_esterne/refresh_chiave_api
Campo | Location | Description |
---|---|---|
chiave_pubblica |
string | Chiave pubblica da utilizzare per autenticare tutte le chiamate HTTP |
Oggetto di tipo Errori:
Per garantire la stabilità del servizio, le API implementano un meccanismo di rate limiting.
Ad ogni richiesta viene incrementato un contatore associato all'organizzazione.
Se questo contatore supera il valore 3 all'interno di uno slot temporale di 10 secondi, il sistema restituisce un errore HTTP 429 con il messaggio “Troppe chiamate contemporanee, attendi X secondi”, dove X indica il tempo rimanente prima che il contatore venga resettato. Una volta trascorsi i 10 secondi, il contatore viene azzerato, permettendo nuove richieste.
Come descritto nella pagina prezzi, ogni chiamata API effettuata tramite FiscoAPI comporta un consumo di quote mensili, che varia in base al tipo di operazione richiesta e al piano di abbonamento attivo.
Le quote disponibili si suddividono in due categorie distinte: Core e Inizializzazione
Ogni API ha un costo indicato nella documentazione della singola richiesta.
Le quote si rinnovano ogni mese e il quantitativo disponibile dipende dal piano selezionato.
All’interno della dashboard utente puoi tenere traccia del consumo in tempo reale e stimare l’utilizzo residuo in base alle tue integrazioni. In questo modo puoi:
Ricevi gli eventi FiscoAPI nell'endpoint del tuo webhook.
Dopo aver registrato un endpoint del webhook, FiscoAPI può inviare i dati degli eventi in tempo reale tramite chiamata POST
all'endpoint della tua applicazione quando si verificano eventi (es modifica sessione).
Il formato dell’URL per registrare un endpoint del webhook deve essere: https://<tuo-sito>/<endpoint>
Puoi configurare l'endopoint del tuo webhook sul portale FiscoAPI seguendo questi passi:
Quando un evento si verifica, FiscoAPI invia una richiesta HTTP POST al tuo endpoint webhook con un payload in formato JSON. Qui sotto trovi i campi inclusi nel corpo della richiesta:
Campo | type | Description |
---|---|---|
tipo_dato |
string | Identifica il tipo di dato |
tipo_evento |
string | Tipo dell'evento del webhook, per il momento solo update |
data_invio |
numeric, timestamp in ms | Timestamp in ms del'invio del webhook |
dato |
Object | Come classe tipo_dato , vedi classi |
Le seguenti API avviano processi asincroni e inviano notifiche via webhook per segnalare aggiornamenti di stato, errori o completamento delle operazioni.
Ogni step può generare uno o più webhook in base all’esito (successo, errore, ecc.). Assicurati che il tuo endpoint webhook sia sempre attivo e raggiungibile.
Questa API lancia un webhook, come da guida
Tutti gli errori includono un oggetto JSON con campo codice
che ne identifica il tipo e errore
che aggiunge la descrizione dell'errore.
Per ogni chiamata descritta in questa documentazione vengono forniti i codici dei relativi errori ad esclusione di quelli comuni a tutte le chiamate API, che sono:
codice | Spiegazione |
---|---|
errore_generico |
Errore interno del server |
non_autorizzato |
Autenticazione errata, token non presente in header |
chiave_api_non_valida |
Autenticazione errata, chiave API non valida o scaduta |
chiave_disabilitata |
Autenticazione errata, chiave disabilitata dall'amministratore |
troppe_chiamate_contemporanee |
Hai superato il limite massimo di richieste API, attendi e riprova |
raggiunto_limite_quota_api |
Raggiunto limite quota api |
errore_sessione |
Sessione inesistente |
sessione_scaduta |
Sessione scaduta |
errore_generico_utente |
Errore generico sull'utente lavoro scelto |
Elenco di tutte le classi utilizzate per il funzionamento di FiscoAPI.
Questa classe rappresenta l'oggetto di riferimento per l'utilizzo di FiscoAPI. Infatti incapsula le informazioni necessarie per gestire e monitorare una richiesta di accesso, descrive tutti i servizi che puoi utilizzare dopo l'accesso e tutti le partite iva o codici fiscali utilizzabili.
Campo | Description |
---|---|
_id string |
Identificativo univoco della sessione |
ente string |
Nome dell'ente di autenticazione puo essere: agenzia_entrate o inps. |
tipo_login string |
Tipo di login utilizzato, può essere:
poste → Per accesso con Poste Italianecie → Per accesso con Carta d'Identità Elettronica (CIE)lepida → Per accesso con SPID Lepidanamirial → Per accesso con SPID Namirialaruba → Per accesso con SPID Arubateamsystem → Per accesso con SPID TeamSysteminfocert → Per accesso con SPID InfoCert
|
data_creazione numeric, timestmp in ms |
Timestamp di creazione della sessione. |
stato string |
Stato corrente della sessione, puo essere:
creazione_form_login → Creazione processo di autenticazione in corso
richiesta_accesso → La sessione è in attessa delle credenziali o la scannerizzazione del qrcode
autenticato → La sessione è stata autenticata correttamente
sessione_attiva → La sessione è attiva e pronta all'uso
sessione_in_errore → La sessione è in errore, necessario crearne una nuova
sessione_scaduta → La sessione è scaduta, necessario crearne una nuova
qr_code_scaduto → Il qrcode non è stato scannerizzato in tempo, necessario crearne una nuova (nei login in cui è richiesto il qrcode)
credenziali_errate → Le credenziali sono errate, necessario crearne una nuova (nei login in cui è richiesto username e password)
richiesta_app_otp → La sessione è in attesa del codice dell'app otp sulla quale inviare il codice otp (nei login in cui è richiesto codice OTP tramite app)
scelta_app_otp_scaduta → Non è stata scelta l'app OTP in tempo, necessario crearne una nuova (nei login in cui è richiesto codice OTP tramite app)
app_otp_inesistente → l'ID dell'app OTP scelta non esiste (nei login in cui è richiesto codice OTP tramite app)
richiesta_codice_otp → La sessione è in attesa del codice otp necessario per l'autenticazione (nei login in cui è richiesto codice OTP)
attesa_codice_otp_scaduta → Non si è inserito il codice OTP in tempo, necessario crearne una nuova (nei login in cui è richiesto codice OTP)
codice_otp_errato → Il codice OTP inserito è errato; è necessario avviare una nuova sessione (per i login che richiedono l’OTP).
richiesta_accesso_manuale_inps → Necessario accesso manuale su portale INPS prima di proseguire con la sessione.
|
utente_connesso Object |
Dettaglio dell'utente connesso. |
iva_servizi Servizio |
Dettaglio del servizio Iva e Servizi della sessione, come classe Servizio |
cassetto_fiscale Servizio |
Dettaglio del servizio Cassetto fiscale della sessione, come classe Servizio |
data_avvio numeric, timestamp in ms |
Timestamp di avvio della sessione. |
lista_app_otp array |
Array di ID in formato stringa delle app OTP tra cui scegliere per l'invio di codice OTP (utile solo per le sessioni in cui il metodo di login necessita di app OTP). |
Questa classe rappresenta uno dei servizi utilizzabili in una Sessione (es: iva_servizi) e da le informazioni utili per il suo funzionamento.
Campo | Description |
---|---|
stato string |
Stato corrente dell servizio, puo essere:
disponibile → Servizio disponibile
non_disponibile → Servizio non disponibile per questo utente
in_errore → Servizio non disponibile per un errore imprevisto
|
info Object |
Oggetto con informazione su utente autenticato e utenza di lavoro della sessione. |
lista_utenti_lavoro Object |
Oggetto che identifica lo stato degli utenti di lavoro per il servizio corrente, formato da chiave p.iva o c.f utente formato dai seguenti campi:
stato → può assumere i seguenti valori:
da_inizializzare → Utente non ancora inizializzato per il seguente servizio.
in_inizializzazione → Utente in fase di inizializzazione per questo servizio.
inizializzato → Utente abilitato a utilizzare il servizio.
in_errore → Utente non utilizzabile per un errore imprevisto in fase di inizializzazione.
|
Questa classe rappresenta la richiesta di certificazione unica, ovvero l'avanzamento e lo stato finale della richiesta fatta al nostro sistema.
Campo | Description |
---|---|
_id string |
Identificativo della richiesta certificazioni |
utente_lavoro string |
partita iva o codice fiscale dell'utente lavoro per il quale richiedere le certificazioni uniche |
data_creazione numeric, timestamp ms |
Timestamp in ms delle data di creazione della richiesta certificazioni uniche |
id_sessione string |
Identificativo della sessione utilizzata. |
stato string |
Identifica lo stato della richiesta certificazioni uniche, puo essere:
in_corso → Richiesta certificazioni uniche avviata.
completata → Richiesta certificazioni uniche completata, sono quindi consultabili ed è possibile richiedere lo scaricamento dei PDF.
servizio_non_disponibile → Richiesta certificazioni uniche in errore perchè il servizio non è disponibile per l'utente lavoro (p.iva/CDF) scelto.
in_errore → Richiesta certificazioni uniche in errore.
|
dettaglio_anni array |
Lista di oggetti che rappresentano le certificazioni di uno specifico anno attraverso i seguenti campi:anno numeric, integer → Anno di riferimento delle certificazioni.certificazioni array → lista di oggetti di classe Certificazione Unica che rappresentano una specifica certificazione.in_errore boolean → Se è presente questo campo significa che il recupero delle certificazioni di questo anno è terminato con un errore. |
Questa classe rappresenta una certificazione unica che è contenuta all'interno della classe Richiesta certificazioni uniche quando viene completata.
Campo | Description |
---|---|
data_emissione string |
Data emissione certificazione unica. |
id_protocollo string |
Identificativo della certificazione unica. |
anno numeric, integer |
Anno della certificazione unica |
stato string |
Identifica lo stato dello scaricamento del file PDF della certificazione unica che viene richiesto tramite api_esterne/cassetto_fiscale/download_certificazione_unica/:id_protocollo:
download_non_ancora_effettuato → Quando non si è ancora richiesto lo scaricamento del file PDF.
download_in_corso → Il download del file è stato richiesto ed è in elaborazione.
download_completato → Il file è disponibile utilizzando il campo id_file per recuperarlo.
download_in_errore → Il download è andato in errore.
|
id_file string |
Identificativo del file, necessario per scaricare la certificazione unica con l'API /api_esterne/files/:id_file. |
Questa classe rappresenta la richiesta di versamenti effettuate a Cassetto Fiscale (es: F23/F24) e da le informazioni utili per il suo funzionamento.
Campo | Description |
---|---|
_id string |
Identificativo della richiesta di versamenti |
utente_lavoro string |
Partita iva o codice fiscale dell'utente lavoro per il quale richiedere i versamenti |
data_creazione numeric, timestamp ms |
Timestamp in ms delle data di creazione della richiesta di versamenti |
tipo string |
Identifica che tipo di versamenti sono richiesti. Possibili valori:
F24 → Richiesta versamenti F24.
F23 → Richiesta versamenti F23.
|
id_sessione string |
Identificativo della sessione utilizzata. |
stato string |
Identifica lo stato della richiesta di versamenti, puo essere:
in_corso → Richiesta versamenti avviata.
completata → Richiesta versamenti completata, sono quindi consultabili ed è possibile richiedere lo scaricamento dei file associati.
servizio_non_disponibile → Richiesta versamenti in errore perchè il servizio non è disponibile per l'utente lavoro (p.iva/CDF) scelto.
in_errore → Richiesta versamenti in errore.
|
dettaglio_anni array |
Lista di oggetti che rappresentano i versamenti di uno specifico anno attraverso i seguenti campi:anno numeric, integer → Anno di riferimento.versamenti array → lista di oggetti di classe Versamento che rappresentano uno specifico versamento.in_errore boolean → Se è presente questo campo significa che il recupero dei versamenti di questo anno è terminato con un errore. |
Questa classe rappresenta un versamento (es F23/F24) che è contenuta all'interno della classe Richiesta versamenti quando viene completata. È sostanzialmente un oggetto contenente tutti i campi ritornati da Cassetto Fiscale con l'aggiunta di alcuni campi specifici per l'utilizzo tramite il nostro sistema.
Campo | Description |
---|---|
id numeric, int |
Identificativo utile per chiedere il download dei file relativi al versamento. |
data_versamento string |
Data del versamento. |
importo string, solo per F23 |
Importo del versamento F23. |
saldo string, solo per F24 |
Saldo del versamento F24. |
totale string |
Totale del versamento. |
numero_modelli_f24 string, solo per F24 |
Numero modelli F24 disponibili solo se è un versamento di tipo F24 (vedi RichiestaVersamenti.tipo) |
stato string |
Indica lo stato di scaricamento dei file associati al versamento. Il file di modello e quietanza se è un versamento F24 che va richiesto con api_esterne/cassetto_fiscale/download_versamento_f24/:id_versamento, solo quello di modello se è un F23 che va richiesto con api_esterne/cassetto_fiscale/download_versamento_f23/:id_versamento.
I possibili valori dello stato sono: download_non_ancora_effettuato → Quando non si è ancora richiesto lo scaricamento dei file PDF.
download_in_corso → Il download dei files è stato richiesto ed è in elaborazione.
download_completato → I files sono disponibili e recuperabili utilizzando il campo id_file_modello e id_file_quietanza (solo F24).
download_in_errore → Uno o più download è andato in errore.
|
id_file_modello string |
Identificativo del file del modello, necessario per scaricare il file con l'API /api_esterne/files/:id_file. |
id_file_quietanza string, solo per F24 |
Identificativo del file della quietanza del modello, necessario per scaricare il file con l'API /api_esterne/files/:id_file. |
sezioni Array[Object] |
Lista di oggetto che descrivono ogni sezione specifica del versamento, con i seguenti campi:
titolo string → Titolo della sezione.
totale string (F23) | Object (F24) → Totale della sezione che è stringa per gli F23 mentre un Object per gli F24 come:
{ "importo_debito": "6.462,00 €", "importo_credito": "0,00 €" } linee array[Object] → Lista di linee che compongono la sezione, e dipende esattamente dalla relativa tabella di Cassetto Fiscale. Quindi visualizziamo un dato di esempio:
[ { "tributo": "1001 RITENUTE SU RETRIBUZIONI PENSIONI TRASFERTE MENSILITA' AGGIUNTIVE E RELATIVO", "rateazione": "12", "anno": "2024", "debito": "11.594,39 €", "credito": "0,00 €" } ] |
Questa classe rappresenta la richiesta di estratto conto dell'INPS con i relativi stati di scaricamento.
Campo | Description |
---|---|
id numeric, integer |
Identificativo dell'estratto conto. |
id_sessione string |
Identificativo della sessione utilizzata per generare l'automazione. |
stato string |
Identifica lo stato dello scaricamento del file con l'estratto conto:
in_corso → Il download dei files è stato richiesto ed è in elaborazione.
caricamento_completato → I files sono disponibili e scaricabili utilizzando i campi id_file contenuti in files .
caricamento_in_errore → Il download è andato in errore.
|
data_creazione numeric, timestamp in ms |
timestamp in ms che indica la data di creazione dell'estratto conto. |
id_file string |
Identificativo del file, necessario per scaricare l'estratto conto con l'API /api_esterne/files/:id_file |
Questa classe rappresenta la richiesta un Link. Un Link è una struttura che permette di richiedere molti dati diversi ad un destinatario che dovrà preoccuparsi solo di effettuare l'accesso ai servizi necessari. Successivamente il nostro sistema provvederà a recuperare in autonomia tutti i dati richiesti.
Campo | Description |
---|---|
_id string |
Identificativo del Link. |
tipo_destinatario string |
Indica la tipologia del destinatario che può avere i seguenti valori:
persona_fisica → Se i dati richiesti sono riferiti a una persona fisica, quindi per codice fiscale.
persona_legale → Se i dati richiesti sono riferiti a una persona legale, quindi per partita IVA.
|
identificativo_destinatario string |
Identificativo del destinatario da cui si recuperano i dani. Sarà una p.iva se è una persona legale o un codice fiscale se è una persona fisica. |
nome_richiedente string |
Nome/identificativo del richiedente che viene visualizzato dal destinatario della richiesta per trasparenza su chi riceverà i dati che si stanno condividendo. |
data_creazione numeric |
timestamp in ms che indica la data di creazione. |
link_token string |
Il token che viene usato per condividere il Link con il destinatario e ne permette l'interazione (viene inserito nell'URL da condividere). |
url string |
È il link da condividere con il destinatario per permettere l'avvio del recupero delle informazioni. |
agenzia_entrate object |
Questo oggetto è presente solo se nel Link ci sono delle richieste di dati da recuperare da Agenzia delle Entrate e contiene tutte le informazioni di accesso, le specifiche delle richieste e i dati effettivi.
Ecco i campi di questo oggetto:
stato
string
Indica lo stato in cui si trova la richiesta relativa ad Agenzia delle Entrate e i possibili valori sono:
attesa_accesso → Il destinatario deve ancora effettuare l'accesso per Agenzia delle Entrate.
accesso_in_corso → Il destinatario ha avviato la procedura di accesso ad Agenzia delle Entrate.
richieste_in_corso → Il destinatario ha completato con successo l'accesso e i nostri sistemi stanno avviando le richieste che compongono il link e relative ad Agenzia delle Entrate.
richieste_effettuate → Tutte le richieste nel link per Agenzia delle Entrate sono state effettuate correttamente, quindi le risposte saranno visibili nel relativo campo quando verranno completate (infatti alcune richieste non rispondono immediatamente come specificato nelle API a cui fanno riferimento).
Oggetto di Sessione che rappresenta la sessione di accesso ad Agenzia delle Entrate. Serve per gestire i vari passaggi del flusso di accesso. Quando il destinatario ha fatto l'accesso questo oggetto non ci sarà più in quanto non è più utile.
richieste
object
In questo oggetto sono contenuti campi specifici per ogni richiesta da effettuare ad Agenzia delle Entrate.
elenco_fatture_emesse
object
È presente solo se nel link è richiesto l'elenco delle fatture elettroniche emesse. Contiene le specifiche della ricerca e le informazioni di risposta.
Ecco i campi di questo oggetto:
inizio
number
timestamp in ms di inizio intervallo elenco
fine
number
timestamp in ms di fine intervallo elenco
risposta
object
Oggetto che contiene tutte le informazioni per gestire la risposta dell'elenco.
Ecco i campi interni:
errore
boolean
Se è presente ed è
true significa che la richiesta è fallita con errore
dato
object
Contiene la risposta esattamente come risposta dell'API /api_esterne/iva_servizi/fatture_emesse
elenco_fatture_ricevute
object
È presente solo se nel link è richiesto l'elenco delle fatture elettroniche ricevute. Contiene le specifiche della ricerca e le informazioni di risposta.
Ecco i campi di questo oggetto:
inizio
number
timestamp in ms di inizio intervallo elenco
fine
number
timestamp in ms di fine intervallo elenco
risposta
object
Oggetto che contiene tutte le informazioni per gestire la risposta dell'elenco.
Ecco i campi interni:
errore
boolean
Se è presente ed è
true significa che la richiesta è fallita con errore
dato
object
Contiene la risposta esattamente come risposta dell'API /api_esterne/iva_servizi/fatture_ricevute
elenco_f24
object
È presente solo se nel link è richiesto l'elenco degli F24. Contiene le specifiche della ricerca e le informazioni di risposta.
Ecco i campi di questo oggetto:
anni
array[number]
Lista di tutti gli anni di cui si vuole ottenere l'elenco (es: 2025, 2024, 2023).
risposta
object
Oggetto che contiene tutte le informazioni per gestire la risposta dell'elenco.
Ecco i campi interni:
errore
boolean
Se è presente ed è
true significa che la richiesta è fallita con errore.
dato
object
Contiene la risposta esattamente come risposta dell'API /api_esterne/automation/richieste_versamenti_f24/{id_sessione}
elenco_f23
object
È presente solo se nel link è richiesto l'elenco degli F23. Contiene le specifiche della ricerca e le informazioni di risposta.
Ecco i campi di questo oggetto:
anni
array[number]
Lista di tutti gli anni di cui si vuole ottenere l'elenco (es: 2025, 2024, 2023).
risposta
object
Oggetto che contiene tutte le informazioni per gestire la risposta dell'elenco.
Ecco i campi interni:
errore
boolean
Se è presente ed è
true significa che la richiesta è fallita con errore.
dato
object
Contiene la risposta esattamente come risposta dell'API /api_esterne/automation/richieste_versamenti_f23/{id_sessione}
|
inps object |
Questo oggetto è presente solo se nel Link ci sono delle richieste di dati da recuperare da INPS e contiene tutte le informazioni di accesso, le specifiche delle richieste e i dati effettivi.
Ecco i campi di questo oggetto:
stato
string
Indica lo stato in cui si trova la richiesta relativa ad INPS e i possibili valori sono:
attesa_accesso → Il destinatario deve ancora effettuare l'accesso per INPS.
accesso_in_corso → Il destinatario ha avviato la procedura di accesso ad INPS.
richieste_in_corso → Il destinatario ha completato con successo l'accesso e i nostri sistemi stanno avviando le richieste che compongono il link e relative ad INPS.
richieste_effettuate → Tutte le richieste nel link per INPS sono state effettuate correttamente, quindi le risposte saranno visibili nel relativo campo quando verranno completate (infatti alcune richieste non rispondono immediatamente come specificato nelle API a cui fanno riferimento).
Oggetto di Sessione che rappresenta la sessione di accesso a INPS. Serve per gestire i vari passaggi del flusso di accesso. Quando il destinatario ha fatto l'accesso questo oggetto non ci sarà più in quanto non è più utile.
richieste
object
In questo oggetto sono contenuti campi specifici per ogni richiesta da effettuare a INPS.
elenco_contributi_versati_inps
object
È presente solo se nel link è richiesto l'elenco dei versamenti INPS. Contiene le specifiche della ricerca e le informazioni di risposta.
Ecco i campi di questo oggetto:
risposta
object
Oggetto che contiene tutte le informazioni per gestire la risposta dell'elenco.
Ecco i campi interni:
errore
boolean
Se è presente ed è
true significa che la richiesta è fallita con errore
dato
object
Contiene la risposta esattamente come risposta dell'API /api_esterne/inps/estratto_conto/{id_sessione}
|
Le API di tipo CORE consentono di replicare le operazioni disponibili sul sito dell'Agenzia delle Entrate, come la consultazione dell'elenco delle fatture emesse e ricevute, il download del file XML di una singola fattura e il download massivo di fatture. Queste funzionalità sono accessibili attraverso l'invocazione di servizi REST che simulano un client web, garantendo un'integrazione fluida con i sistemi aziendali. L'utilizzo di queste API migliora l'efficienza nella gestione fiscale e assicura una maggiore automazione dei processi contabili. Inoltre, l'accesso diretto ai dati tramite API riduce la necessità di interazioni manuali con il portale dell'Agenzia, minimizzando possibili errori e risparmiando tempo prezioso per le imprese. Per tutte un esempio di utilizzo puoi consultare la nostra quickstart guide.
Ecco la lista degli endpoint di tutte le funzionalità disponibili:
Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio di Agenzia delle Entrate denominato Iva e Servizi suddivisi per funzionalità principali.
Lista di tutti gli endpoints relativi all'ottenimento dell'elenco di fatture ricevute/emesse (vedi quickstart guide). Queste API non ritornano i file xml delle fatture ma solo l'elenco con i dati principali.
Descriviamo gli endpoints utili per ottenere l'xml di fatture e dei suoi metadati partendo dal suo id che abbiamo ottenuto attraverso l'elenco fatture.
Con queste API possiamo ottenere solo un xml la volta ma si può richiedere uno scaricamento massivo con Download massivi XML fatture.
N.B: il parametro id_fattura è formato dai seguenti campi reperibil in api Elenco fatture:
-tipoInvio
-idFattura
Esempio risposta api dell'endpoint Elenco fatture
{
"fatture": [
{
"clienteFornitore": "Fornitore",
"dataAccoglienzaFile": "2025-03-11",
"dataConsegna": "11/03/2025",
"dataFattura": "2025-03-11",
"tipoInvio": "FPR",
"idFattura": "198709123",
"decodificaTipoInvio": "Fattura tra privati",
"denominazioneCliente": "1819236y10239u119273",
"denominazioneEmittente": "1819236y10239u119273",
"dettaglio": true,
"disabilitato": false,
"disclaimer": false,
"fatturePrecedenti": [],
"fileDownload": {
"fileDownload": 1,
"idInvio": "198709123",
"presaVisione": 0,
"revocaDownload": 0,
"statoDiConsegna": 0,
"statoFile": "Consegnata"
},
"idPaeseCedente": "IT",
"idPaeseCessionario": "IT",
"identificativoCliente": "198709123",
"imponibile": "+000000002868,86",
"imposta": "+000000000631,15",
"numeroFattura": "KQAD987123",
"pivaCliente": "123098123",
"pivaEmittente": "123907123",
"profiloDownload": false,
"stato": "Emessa",
"statoVisto": 0,
"testoFattureConsegnate": "Fattura consegnata il 11/03/2025",
"tipoDocumento": "Fattura",
"variazioni": false
}
]
}
In questo esempio il campo id_fattura da utilizzare nelle seguenti API sarà il seguente: FPR198709123
Descriviamo gli endpoints utili per richiedere lo scaricamento massivo di xml di fatture e dei loro metadati.
Infatti il portale Iva e Servizi permette di caricare un xml per massimizzare questo scaricamento e ottenere, a seguito dell'elaborazione da parte di
Agenzia delle Entrate, un file .zip con i file richiesti. L'operazione non è immediata e potrebbe richiedere diverso tempo per l'elaborazione da parte di Agenzia delle Entrate.
Di seguito descriviamo tutti gli endpoints delle funzionalità relative alla trasmissione e al monitoraggio dell'invio di fatture elettroniche offerto da Iva e Servizi. Ecco la lista completa:
Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio di Agenzia delle Entrate denominato Cassetto Fiscale.
Lista di tutti gli endpoints relativi all'ottenimento delle certificazioni uniche (vedi quickstart guide).
Lista di tutti gli endpoints relativi all'ottenimento dei versamenti F23 F24 (vedi quickstart guide).
Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio INPS: di seguito la lista completa di endpoint:
Le API di tipo AUTOMATION offrono la possibilità di eseguire in un'unica chiamata più operazioni precedentemente disponibili tramite le API CORE, come il download massivo di fatture elettroniche per diverse partite IVA contemporaneamente.
Questa funzionalità consente di automatizzare processi complessi, riducendo significativamente il tempo necessario per l'elaborazione manuale di ciascuna richiesta individuale.
Grazie all'integrazione di più servizi in un'unica API, le aziende possono migliorare l'efficienza operativa nella gestione fiscale e contabile, garantendo al contempo l'accuratezza dei dati e la conformità alle normative vigenti.
L'utilizzo delle API AUTOMATION facilita l'accesso centralizzato alle informazioni fiscali, ottimizzando le risorse interne e riducendo il rischio di errori associati a operazioni manuali ripetitive.
Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio di Cassetto fiscale per richiedere la lista di versamenti F23/F24 per più anni.
Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio di Cassetto fiscale per richiedere la consultazione e lo scaricamento massivo di certificazioni uniche.
Con questa funzionalità sarà possibile generare una richiesta (ad esempio, scaricamento fatture, reperimento pagamenti F24, ecc.) tramite un link condivisibile. L'utente che accederà alla pagina web del link potrà autenticarsi tramite SPID/CIE e le informazioni richieste verranno recuperare in modo automatico, senza necessità di interventi manuali. Ad esempio, questo servizio può risultare particolarmente utile per i commercialisti, che potranno inviare ai propri clienti richieste di scaricamento automatico delle fatture elettroniche, ottimizzando i tempi di gestione e riducendo il rischio di errori.
Si ricorda che lo sviluppatore può creare le richieste e leggerne i dati relativi ma il flusso di autenticazione del destinatario avviene solo tramite la nostra pagina web, ovvero utilizzando l'URL che viene generato. (vedi guida Creazione e funzionamento link).
Ecco la lista degli endpoint utili per l'utilizzo e la creazione: