Introduzione
FiscoAPI semplifica l’accesso ai dati fiscali con API affidabili che integrano le informazioni delle Agenzie delle Entrate nelle tue app.
In questa pagina trovi tutte le guide pratiche all'uso. Per ulteriori dettagli, puoi consultare la documentazione completa.
Quickstart Guide
In questa guida vedremo come avviare una sessione autenticata tramite le nostre API per ottenere l’elenco delle fatture emesse associate a una partita IVA.
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Fatture e Corrispettivi di Agenzia delle Entrate, qualora non utilizzasse le API offerte da FiscoAPI.
Seguendo tutti i passaggi di questa guida, potrai replicare le stesse operazioni viste nel portale dell’Agenzia delle Entrate, ma con importanti vantaggi:
- Integrazione completa del flusso direttamente nella tua piattaforma;
- Controllo totale su ogni fase del processo, con possibilità di personalizzare dati e modalità operative;
- Nessun accesso manuale al portale dell’Agenzia delle Entrate: tutto avviene tramite API in modo trasparente e automatizzato;
Step 1 - Creazione chiave segreta e webhook
Prima di tutto, 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.
Nella stessa sezione devi anche impostare l'endpoint per ricevere gli aggiornamenti in tempo reale tramite webhook. Questo ti permetterà di non dover fare ulteriori chiamate API per vedere i cambi di stato di una sessione.
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.
Step 2 - Creazione chiave pubblica
Ora devi creare una chiave pubblica associata alla tua chiave segreta passandola nel body della richiesta /crea_chiave_api (vedi documentazione).
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/crea_chiave_api' \
--header 'Content-Type: application/json' \
--data-raw '{
"chiave_segreta": "<chiave_segreta>"
}'
Nella risposta riceverai la chiave pubblica e il refresh token.
{
"chiave_pubblica": "<chiave_pubblica>",
"refresh_token": "<refresh_token>",
}
La chiave pubblica ha validità di un'ora e può essere ricreata utilizzando il refresh token. Per tutti i dettagli vedi qui.
Step 3 - Avvio sessione
Utilizzando la chiave pubblica, avvia una sessione scegliendo il tipo di login. Per comodità nell'esempio useremo lo SPID di Poste Italiane. Per tutti gli altri metodi fai riferimento alla documentazione.
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/avvia_sessione' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"ente": "agenzia_entrate",
"tipo_login": "poste"
}'
Nella risposta riceverai un oggetto di tipo Sessione. Questo è l'oggetto di riferimento che cambierà successivamente stato. Gli aggiornamenti della sessione ti arriveranno tramite webhook o potrai richiedere di nuovo l'oggetto tramite API /sessione:id_sessione.
{
"sessione": {
"ente": "agenzia_entrate",
"tipo_login": "poste",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "creazione_form_login",
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Da qui in avanti dovrai attendere l'arrivo degli aggiornamenti sul webhook, relativi alla sessione appena avviata, fino allo stato in cui sarà richiesto il login.
Step 4 - Webhook aggiornamenti sessione
La sessione appena avviata passerà diversi stati successivi e quando lo stato sarà richiesta_accesso
dovrai scannerizzare il QR code con l'app di Poste.it che trovi nel campo qr_code in formato data URL.
Ecco l'esempio di dato che ti arriverà tramite webhook all'endpoint che hai impostato (dettagli in documentazione webhook):
{
"tipo_dato": "Sessione",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"ente": "agenzia_entrate",
"tipo_login": "poste",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "richiesta_accesso",
"qr_code": "data:image/png;base64,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",
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Attraverso il data URL potrai visualizzare il QR code al tuo utente o semplicemente aprirlo in una pagina del browser per permettere la scannerizzazione.
Step 5 - Sessione avviata
Dopo aver effettuato l'accesso, lo stato della sessione cambierà in autenticato (sempre attraverso aggiornamenti webhook)
e quando lo stato sarà sessione_attiva potrai iniziare a usare gli utenti che risultano inizializzati.
Con la Sessione in stato sessione_attiva potrai analizzare quanti servizi sono disponibili per l'utenza con cui hai effettuato l'accesso.
Attualmente i principali sono iva_servizi e cassetto_fiscale. In questi campi di
Sessione troverai indicazione sullo stato del servizio.
{
"_id": "5fa1c3d49b7e6f2a4d8e9c01",
"ente": "agenzia_entrate",
"tipo_login": "poste",
"data_creazione": 1743065844435,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "sessione_attiva",
"utente_connesso": {
"identificativo": "RSSMRA80A01H501U",
"denominazione": "ROSSI MARIO"
},
"iva_servizi": {
"stato": "disponibile",
"info": {
"utenteAutenticato": {
"nome": "MARIO",
"cognome": "ROSSI",
"cf": "RSSMRA80A01H501U",
"tipo": "FOL"
},
"utenzaLavoro": {
"cf": "10001100101",
"piva": "10001100101",
"denominazione": "MARIO ROSSI SRL",
"tipo": "INCARICO"
}
},
"lista_utenti_lavoro": {
"10001100101": {
"stato": "inizializzato"
},
"20002200202": {
"stato": "da_inizializzare"
}
}
},
"cassetto_fiscale": {
"stato": "disponibile",
"info": {
"utenzaAutenticata": {
"chiaveUtenza": "RSSMRA80A01H501U",
"codiceFiscale": "RSSMRA80A01H501U",
"codiceFiscaleUltimo": "RSSMRA80A01H501U",
"sede": "FOL",
"denominazione": "ROSSI MARIO",
"tipoUtente": "I10"
},
"utenzaDiLavoro": null
},
"lista_utenti_lavoro": {
"10001100101": {
"stato": "da_inizializzare"
},
"20002200202": {
"stato": "da_inizializzare"
},
"RSSMRA80A01H501U": {
"stato": "inizializzato"
}
}
},
"data_avvio": 1743065893276
}
Inoltre, in lista_utenti_lavoro vedrai tutta la lista di p.iva o codici fiscali associati all'utenza con cui hai effettuato l'accesso.
Ogni procedura di avvio sessione inizializza la prima partita iva o codice fiscale disponibile, se vuoi usarne altri dovrai inizializzarli come indicato
nella prossima guida.
Infatti dall'esempio sopra riportato possiamo vedere che in iva_servizi :
-
la p.iva
10001100101ha il campostato = inizializzatoed è quindi pronta all'uso; -
la p.iva
20002200202ha il campostato = da_inizializzareche richiede una procedura di inizializzazione per poter essere utilizzata;
Step 6 - Richiesta elenco fatture
Prendendo come riferimento la p.iva 10001100101 che è già disponibile per le chiamate API, puoi richiedere l'elenco fatture emesse tramite il nostro endpoint
GET https://api.fiscoapi.app/api_esterne/fatture_emesse (vedi documentazione API).
In query url dovrai inserire i seguenti campi:
-
id_sessione: il campo_iddella sessione che abbiamo appena avviato (nel nostro caso5fa1c3d49b7e6f2a4d8e9c01); -
utente_lavoro: la p.iva dell'utente inizializzato. (nel nostro caso10001100101); -
inizio: timestamp in millisecondi di inizio della ricerca; -
fine: timestamp in millisecondi di fine della ricerca;;
curl --location --request GET \
'https://api.fiscoapi.app/api_esterne/fatture_emesse?id_sessione=5fa1c3d49b7e6f2a4d8e9c01&utente_lavoro=10001100101&inizio=<inizio>&fine=<fine>' \
--header 'Authorization: Bearer <chiave_pubblica>'
Nella risposta otterremo l'elenco di fatture emesse (oggetto JSON come restituisce il sito di Agenzia delle Entrate) nel periodo tra ìnizio e fine.
{
"fatture": [
{
"variazioni": false,
"fatturePrecedenti": [],
"denominazioneEmittente": "Mario Rossi S.r.l.",
"denominazioneCliente": "Azienda Italiana S.r.l.",
"pivaCliente": "73920101527",
"dataAccoglienzaFile": "2025-03-25",
"identificativoCliente": "73920101527",
"pivaEmittente": "10001100101",
"cfEmittente": "10001100101",
"decodificaTipoInvio": "Fattura tra privati",
"fileDownload": {
"revocaDownload": 0,
"statoDiConsegna": 0,
"statoFile": "Consegnata",
"fileDownload": 1,
"idInvio": "14316399195",
"presaVisione": 0
},
"clienteFornitore": "Fornitore",
"idFattura": "14217767001",
"tipoInvio": "FPR",
"tipoDocumento": "Fattura",
"numeroFattura": "MROSSI-69078",
"dataFattura": "2025-03-25",
"imponibile": "+000000000015,00",
"imposta": "+000000000003,30",
"stato": "Emessa",
"statoVisto": 0,
"dettaglio": true,
"dataConsegna": "25/03/2025",
"testoFattureConsegnate": "Fattura consegnata il 25/03/2025",
"idPaeseCedente": "IT",
"idPaeseCessionario": "IT",
"disclaimer": false,
"disabilitato": false,
"profiloDownload": false
},
{
"variazioni": false,
"fatturePrecedenti": [],
"denominazioneEmittente": "Mario Rossi S.r.l.",
"denominazioneCliente": "Luca Bianchi",
"cfCliente": "BNCLCU90C15F205Z",
"dataAccoglienzaFile": "2025-04-01",
"identificativoCliente": "BNCLCU90C15F205Z",
"pivaEmittente": "10001100101",
"cfEmittente": "10001100101",
"decodificaTipoInvio": "Fattura tra privati",
"fileDownload": {
"revocaDownload": 0,
"statoDiConsegna": 1,
"statoFile": "Mancata consegna",
"fileDownload": 1,
"idInvio": "14362664222",
"presaVisione": 4
},
"clienteFornitore": "Fornitore",
"idFattura": "14217767002",
"tipoInvio": "FPR",
"tipoDocumento": "Fattura",
"numeroFattura": "MROSSI-69716",
"dataFattura": "2025-03-31",
"imponibile": "+000000000000,00",
"imposta": "+000000000000,00",
"stato": "Emessa",
"statoVisto": 0,
"dettaglio": true,
"testoFattureConsegnate": "Fattura non consegnata",
"idPaeseCedente": "IT",
"disclaimer": false,
"disabilitato": false,
"profiloDownload": false
},
...
]
}
Step 7 - Conclusione
Dopo aver avviato una Sessione è possibile effettuare tutte le API che FiscoAPI ti mette a disposizione, come descritto nella documentazione sugli utenti che sono inizializzati.
Se, invece, si vuole utilizzare un'altra p.iva o codice fiscale che non risulta ancora in stato inizializzato
allora sarà necessario effettuare l'inizializzazione come descritto nella prossima guida.
Accesso con Namirial
Descriviamo ora la procedura di login con il servizio Namirial come esempio di un processo di avvio Sessione che utilizza credenziali (username e password) e codice OTP inviato tramite specifica app.
Step 1 - Avvio sessione
La caratteristica principale di tutti i login che richiedono l'accesso con credenziali
è che nella richiesta di avvio Sessione vanno specificati i relativi campi username e password.
Quindi avviamo la sessione all'enpoint /api_esterne/avvia_sessione, utilizzando la chiave pubblica, il tipo login namirial e i campi
username e password (vedi documentazione).
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/avvia_sessione' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"ente": "agenzia_entrate",
"tipo_login": "namirial",
"username": "<username>"
"password": "<password>"
}'
Nella risposta riceverai un oggetto di tipo Sessione. Questo è l'oggetto di riferimento che cambierà successivamente stato. Gli aggiornamenti della sessione ti arriveranno tramite webhook o potrai richiedere di nuovo l'oggetto tramite API /sessione:id_sessione.
{
"sessione": {
"ente": "agenzia_entrate",
"tipo_login": "namirial",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "creazione_form_login",
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Step 2 - Webhook aggiornamenti sessione
Ora la sessione in esame cambierà stato successivamente e, essendo nel caso di login con Namirial, attenderai l'arrivo dello stato richiesta_app_otp,
in cui dovrai scegliere su che app far arrivare il codice OTP per l'accesso.
Ecco l'esempio di dato che ti arriverà tramite webhook all'endpoint che hai impostato (dettagli in documentazione webhook):
{
"tipo_dato": "Sessione",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"ente": "agenzia_entrate",
"tipo_login": "namirial",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "richiesta_app_otp",
"lista_app_otp": [
"189000001",
"189000002"
]
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Nel campo lista_app_otp troverai l'elenco degli ID della app di Namirial che hai installato e dovrai selezionare quella su cui vuoi autorizzare il codice OTP.
In questo caso, di esempio, abbiamo due app con ID 189000001 e 189000002.
Step 3 - Selezione app OTP
Per selezionare l'app di Namrial, dovrai effettuare una richiesta PATCH /api_esterne/scegli_app_otp specificando
_id della sessione in query url (vedi documentazione).
Nel body della richiesta specificherai l'id dell'app scelta, per esempio 189000001,
nel campo app_otp_selezionata.
curl --location --request PATCH 'https://api.fiscoapi.app/api_esterne/scegli_app_otp/5fa1c3d49b7e6f2a4d8e9c01' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_otp_selezionata": "189000001"
}'
In risposta verrà ritornato sempre un oggetto di tipo Sessione e, sempre tramite webhook,
attenderai la richiesta di inserimento codice OTP quando la sessione sarà in stato richiesta_codice_otp.
Nel frattempo sull'app di Namirial arriverà una notifica di generazione codice OTP.
Step 4 - Inserimento codice OTP
Quando la Sessione sarà in stato richiesta_codice_otp
dovrai inserire il codice fornito tramite app di Namirial.
Per invia il codice OTP, dovrai effettuare una richiesta PATCH /api_esterne/invia_codice_otp specificando
_id della sessione in query url (vedi documentazione).
Nel body della richiesta specificherai il codice OTP che ti ha fornito l'app,
nel campo codice_otp.
curl --location --request PATCH 'https://api.fiscoapi.app/api_esterne/invia_codice_otp/5fa1c3d49b7e6f2a4d8e9c01' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"codice_otp": <codice_otp>"
}'
In risposta verrà ritornato sempre un oggetto di tipo Sessione e, sempre tramite webhook,
attenderai che la sessione risulti in stato di sessione_attiva. Da questo momento in poi, potrai utilizzare questa sessione per tutte le richieste
come indicato nella quickstart guide.
Accesso con Namirial
Descriviamo ora la procedura di login con il servizio infocert come esempio di un processo di avvio Sessione che utilizza credenziali (username e password) o tramite scansione codice QR
Step 1 - Avvio sessione
La creazione della sessione con Infocert puo essere effettuata sia con le credenziali che con la scasione del codice QR, per distinguere le due modalità è sufficente utilizzare nel body della richiesta la chiave pubblica, il tipo login namirial e i campi
username e password (vedi documentazione).
Mentre se si vuole ottenere il codice QR è sufficente omettere i campi username e password
Di seguito due esempi:
Per sessione con credenziali:
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/avvia_sessione' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"ente": "agenzia_entrate",
"tipo_login": "infocert",
"username": "<username>"
"password": "<password>"
}'
Per sessione con codice QR:
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/avvia_sessione' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"ente": "agenzia_entrate",
"tipo_login": "infocert",
}'
Nella risposta riceverai un oggetto di tipo Sessione. Questo è l'oggetto di riferimento che cambierà successivamente stato. Gli aggiornamenti della sessione ti arriveranno tramite webhook o potrai richiedere di nuovo l'oggetto tramite API /sessione:id_sessione.
{
"sessione": {
"ente": "agenzia_entrate",
"tipo_login": "infocert",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "creazione_form_login",
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Step 2 - Webhook aggiornamenti sessione
Ora la sessione in esame cambierà stato successivamente e, essendo nel caso di login con Infocert, attenderai l'arrivo dello stato richiesta_codice_otp nel caso di avvio sessione con credenziali
in cui dovrai inserire il codice OTP infocert oppure richiesta_accesso in caso di avvio sessione con codice QR in cui dovrai scansionare il codice QR fornito in sessione.
Ecco l'esempio di dato che ti arriverà tramite webhook all'endpoint che hai impostato (dettagli in documentazione webhook):
{
"tipo_dato": "Sessione",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"ente": "agenzia_entrate",
"tipo_login": "infocert",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "richiesta_codice_otp",
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Step 3 - Inserimento codice OTP
Quando la Sessione sarà in stato richiesta_codice_otp
dovrai inserire il codice fornito tramite app di Infocert.
Per invia il codice OTP, dovrai effettuare una richiesta PATCH /api_esterne/invia_codice_otp specificando
_id della sessione in query url (vedi documentazione).
Nel body della richiesta specificherai il codice OTP che ti ha fornito l'app,
nel campo codice_otp.
curl --location --request PATCH 'https://api.fiscoapi.app/api_esterne/invia_codice_otp/5fa1c3d49b7e6f2a4d8e9c01' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"codice_otp": <codice_otp>"
}'
In risposta verrà ritornato sempre un oggetto di tipo Sessione e, sempre tramite webhook,
attenderai che la sessione risulti in stato di sessione_attiva. Da questo momento in poi, potrai utilizzare questa sessione per tutte le richieste
come indicato nella quickstart guide.
Inizializza utente lavoro
In questa guida verrà spiegato il processo di inizializzazione di un utente lavoro, ovvero di una p.iva o codice fiscale non ancora in stato inizializzato.
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Fatture e Corrispettivi per cambiare la p.iva (utente lavoro), qualora non utilizzasse le API offerte da FiscoAPI.
Seguendo tutti i passaggi di questa guida, potrai replicare le stesse operazioni viste nel portale dell’Agenzia delle Entrate.
Step 1 - Avvio inizializzazione
Per inizializzare un utente lavoro su un servizio della sessione attiva devi utilizzare l'API con endpoint
PATCH /inizializza_utente_lavoro (vedi documentazione).
Quindi prendendo in esame l'esempio della guida precedente e ipotizzando di voler inizializzare la p.iva 20002200202 nella nostra sessione per
iva_servizi:
{
"_id": "5fa1c3d49b7e6f2a4d8e9c01",
"ente": "agenzia_entrate",
"tipo_login": "poste",
"data_creazione": 1743065844435,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "sessione_attiva",
"utente_connesso": {
"identificativo": "RSSMRA80A01H501U",
"denominazione": "ROSSI MARIO"
},
"iva_servizi": {
"stato": "disponibile",
"info": {
"utenteAutenticato": {
"nome": "MARIO",
"cognome": "ROSSI"
"cf": "RSSMRA80A01H501U",
"tipo": "FOL"
},
"utenzaLavoro": {
"cf": "10001100101",
"piva": "10001100101",
"denominazione": "MARIO ROSSI SRL",
"tipo": "INCARICO"
}
},
"lista_utenti_lavoro": {
"10001100101": {
"stato": "inizializzato"
},
"20002200202": {
"stato": "da_inizializzare"
}
}
},
"cassetto_fiscale": {
"stato": "disponibile",
"info": {
"utenzaAutenticata": {
"chiaveUtenza": "RSSMRA80A01H501U",
"codiceFiscale": "RSSMRA80A01H501U",
"codiceFiscaleUltimo": "RSSMRA80A01H501U",
"sede": "FOL",
"denominazione": "ROSSI MARIO",
"tipoUtente": "I10"
},
"utenzaDiLavoro": null
},
"lista_utenti_lavoro": {
"10001100101": {
"stato": "da_inizializzare"
},
"20002200202": {
"stato": "da_inizializzare"
},
"RSSMRA80A01H501U": {
"stato": "inizializzato"
}
}
},
"data_avvio": 1743065893276
}
I parametri necessari per la PATCH sono:
-
id_sessione: il campo_iddella sessione che abbiamo avviato nella guida precedente (nel nostro caso5fa1c3d49b7e6f2a4d8e9c01) che va messo come parametro nell'URL; -
servizio: il nome del servizio per cui si vuole inizializzare l'utente (nel nostro casoiva_servizicome da campo di Sessione); -
utente_lavoro: partita iva o codice fiscale dell'utente lavoro che si vuole inizializzare (nel nostro caso20002200202);
curl --location --request PATCH 'https://api.fiscoapi.app/api_esterne/inizializza_utente_lavoro/<id_sessione>' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json' \
--data-raw '{
"servizio": "iva_servizi",
"utente_lavoro": "20002200202"
}'
La risposta di questa richiesta sarà il solito oggetto Sessione
con lo stato dell'utente lavoro in_inizializzazione.
Step 2 - Attesa fine inizializzazione
Sempre attraverso aggiornamento tramite webhook al tuo endpoint riceverai un update di Sessione
quando l'inizializzazione utente sarà completata. Il suo stato sarà: inizializzato.
Ecco l'esempio di dato che ti arriverà tramite webhook all'endpoint che hai impostato (dettagli in documentazione webhook):
{
"_id": "5fa1c3d49b7e6f2a4d8e9c01",
"ente": "agenzia_entrate",
"tipo_login": "poste",
"data_creazione": 1743065844435,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "sessione_attiva",
"utente_connesso": {
"identificativo": "RSSMRA80A01H501U",
"denominazione": "ROSSI MARIO"
},
"iva_servizi": {
"stato": "disponibile",
"info": {
"utenteAutenticato": {
"nome": "MARIO",
"cognome": "ROSSI",
"cf": "RSSMRA80A01H501U",
"tipo": "FOL"
},
"utenzaLavoro": {
"cf": "10001100101",
"piva": "10001100101",
"denominazione": "MARIO ROSSI SRL",
"tipo": "INCARICO"
}
},
"lista_utenti_lavoro": {
"10001100101": {
"stato": "inizializzato"
},
"20002200202": {
"stato": "inizializzato"
}
}
},
"cassetto_fiscale": {
"stato": "disponibile",
"info": {
"utenzaAutenticata": {
"chiaveUtenza": "RSSMRA80A01H501U",
"codiceFiscale": "RSSMRA80A01H501U",
"codiceFiscaleUltimo": "RSSMRA80A01H501U",
"sede": "FOL",
"denominazione": "ROSSI MARIO",
"tipoUtente": "I10"
},
"utenzaDiLavoro": null
},
"lista_utenti_lavoro": {
"10001100101": {
"stato": "da_inizializzare"
},
"20002200202": {
"stato": "da_inizializzare"
},
"RSSMRA80A01H501U": {
"stato": "inizializzato"
}
}
},
"data_avvio": 1743065893276
}
Step 3 - Conclusioni
Da qui in avanti potrai usare 20002200202 sul servizio iva_servizi nella tua sessione.
Per esempio come abbiamo fatto con 10001100101 nella ricerca fatture emesse o
in qualsiasi altra API della documentazione.
Trasmissione e monitoraggio fatture elettroniche
In questa guida verrà spiegato il processo di invio fatture elettroniche tramite file xml e monitorare lo stato di elaborazione e consegna attraverso il servizio di monitoraggio offerto dall'Agenzia delle Entrate.
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Iva e Servizi per eseguire la stessa procedura, qualora non utilizzasse le API offerte da FiscoAPI.
Seguendo tutti i passaggi di questa guida, potrai replicare le stesse operazioni viste nel portale dell’Agenzia delle Entrate.
Step 1 - Trasmissione file xml fattura
Per inviare un file .xml che descrive una fattura elettronica si utilizza l'endpoint
POST /trasmetti_xml_fattura_elettronica (vedi documentazione).
I parametri necessari nel body di questa POST sono:
-
id_sessione: il campo_iddella sessione che abbiamo avviato nella guida precedente (nel nostro caso5fa1c3d49b7e6f2a4d8e9c01); -
utente_lavoro: partita iva o codice fiscale dell'utente lavoro che si vuole inizializzare (nel nostro caso20002200202); -
nome_file: il nome del file da caricare. Ha un formato molto specifico ovvero:
<codice_paese><piva_o_codice_fiscale_trasmittente>_<numero_progressivo>.xml (nel nostro casoIT20002200202_001.xml); -
contenuto_xml: il contenuto in formato stringa del file.xmlche si vuole trasmettere;
curl --location --request POST 'https://api.fiscoapi.app//api_esterne/trasmetti_xml_fattura_elettronica' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json' \
--data-raw '{
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01"
"utente_lavoro": "20002200202",
"nome_file": "IT20002200202_001.xml"
"contenuto_xml": "<?xml version="1.0" encoding="UTF-8"?><?xml..."
}'
La risposta di questa richiesta sarà un oggetto contenente il campo identificativo_sdi
che contiene l'identificativo del file trasmesso e che può essere utile per tener traccia dello stato di elaborazione del file, nonché dello stato di consegna
come spiegheremo nei passi successivi.
Ecco l'esempio di risposta:
{
"identificativo_sdi": "111222333111"
}
Step 2 - Monitoraggio stato fattura trasmessa
In seguito alla trasmissione del file, è possibile seguire il susseguirsi di stati che ne descrivono l'elaborazione, attraverso la sezione
"Monitoraggio" di Iva e Servizi. Infatti attraverso il form dedicato, eventualmente
utilizzando l'identificativo_sdi ottenuto dopo l'invio, è possibile osservarne il flusso.
Per fare questo FiscoAPI mette a disposizione l'endpoint
GET /monitoraggio_fatture_trasmesse (vedi documentazione)
che replica le stesse funzionalità del form sopracitato.
curl --location \
'http://localhost:8084/api_esterne/monitoraggio_fatture_trasmesse?\
id_sessione=5fa1c3d49b7e6f2a4d8e9c01&\
utente_lavoro=20002200202&\
inizio=1744284465000&\
fine=1744630065000&\
identificativo_sdi=111222333111&\
cedente_prestatore=&\
concessionario_committente=&\
tipo_fattura=QUALSIASI&\
stato_fattura=QUALSIASI&\
per_pagina=10&\
num_file_inizio=1' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json'
Questo sarebbe l'esempio di risposta quando facciamo la richiesta specificando l'identificativo_sdi:
{
"totalCount": 1,
"maxCount": 500,
"elencoRisultati": [
{
"idSdi": "111222333111",
"idFattura": "TESTFISCOAPI-1",
"nomeFile": "00112233445_9249.xml",
"paeseCedente": "IT",
"idFiscaleCedente": "00112233445",
"idFiscaleCommittente": "00118833886",
"paeseTrasmittente": "IT",
"idFiscaleTrasmittente": "00112233445",
"dataInvio": "1744581600000",
"stato": "Consegnata"
}
]
}
Step 3 - Paginazione risultati monitoraggio fatture
Lo stesso endpoint GET /monitoraggio_fatture_trasmesse (vedi documentazione)
può essere interrogato per ottenere tutte le fatture trasmesse (senza specificare identificativo_sdi).
Per questo motivo è importante spiegare il tipo di paginazione che viene fatto da Agenzia delle Entrate nel caso in cui elencoRisultati
fosse più grande di quanto abbiamo specificato nel campo per_pagina.
Per esempio se specifichiamo solo un range di date con inizio e fine e:
-
per_page = 1otterremo quindi una sola fattura inelencoRisultati
curl --location \
'http://localhost:8084/api_esterne/monitoraggio_fatture_trasmesse?\
id_sessione=5fa1c3d49b7e6f2a4d8e9c01&\
utente_lavoro=20002200202&\
inizio=1744284465000&\
fine=1744630065000&\
identificativo_sdi=&\
cedente_prestatore=&\
concessionario_committente=&\
tipo_fattura=QUALSIASI&\
stato_fattura=QUALSIASI&\
per_pagina=1&\
num_file_inizio=1' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json'
Questa la possibile risposta:
{
"totalCount": 2,
"maxCount": 500,
"elencoRisultati": [
{
"idSdi": "1111111102",
"idFattura": "",
"nomeFile": "00112233445_9250.xml",
"paeseCedente": "IT",
"idFiscaleCedente": "00112233445",
"idFiscaleCommittente": "00118833886",
"paeseTrasmittente": "IT",
"idFiscaleTrasmittente": "00112233445",
"dataInvio": "1744581600000",
"stato": "Scartato",
"codErrori": [
{
"codice": "00002",
"descrizione": "Nome file duplicato",
"suggerimento": "Il sistema non accetta file con nomi duplicati. Probabilmente è già stato inviato un file con lo stesso nome. Per risolvere il problema cambiare nome al file"
}
]
}
]
}
Dove si vede che il campo totalCount = 2. Questo significa che la richiesta ci ha restituito 1 su 2 elementi disponibili.
Per ottenere la successiva fattura posso fare la stessa richiesta ma con il parametro num_file_inizio = 2, ovvero salterà il primo elemento già ritornato e restituirà il secondo elemento di cui abbiamo fatto richiesta..
curl --location \
'http://localhost:8084/api_esterne/monitoraggio_fatture_trasmesse?\
id_sessione=5fa1c3d49b7e6f2a4d8e9c01&\
utente_lavoro=20002200202&\
inizio=1744284465000&\
fine=1744630065000&\
identificativo_sdi=&\
cedente_prestatore=&\
concessionario_committente=&\
tipo_fattura=QUALSIASI&\
stato_fattura=QUALSIASI&\
per_pagina=1&\
num_file_inizio=2' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json'
Questa la risposta:
{
"totalCount": 2,
"maxCount": 500,
"elencoRisultati": [
{
"idSdi": "1111111101",
"idFattura": "TESTFISCOAPI-1",
"nomeFile": "00112233445_9249.xml",
"paeseCedente": "IT",
"idFiscaleCedente": "00112233445",
"idFiscaleCommittente": "00118833886",
"paeseTrasmittente": "IT",
"idFiscaleTrasmittente": "00112233445",
"dataInvio": "1744581600000",
"stato": "Consegnato"
}
]
}
Ovviamente una paginazione da una fattura la volta è sconsigliata ed è solo a titolo esplicativo per questa guida. Il numero massimo è per_pagina = 500.
Step 4 - Conclusioni
Abbiamo quindi visto come caricare un xml di una fattura elettronica e come verificarne lo stato di trasmissione tramite FiscoAPI. Con lo stesso funzionamento di paginazione sono disponibili anche gli endpoint:
-
GET /monitoraggio_fatture_emesse(vedi documentazione) che ti permette di vedere lo stato delle fatture emesse da servizi esterni; -
GET /monitoraggio_fatture_ricevute(vedi documentazione) che ti permette di vedere lo stato delle fatture ricevute;
Consultazione estratto conto previdenziale Inps
In questa guida verrà spiegato il processo di scaricamento degli estratti conto previdenziali in regime generale e in gestione separata da portale Inps
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Inps per eseguire la stessa procedura, qualora non utilizzasse le API offerte da FiscoAPI.
Seguendo tutti i passaggi di questa guida, potrai replicare le stesse operazioni viste nel portale dell’Inps.
Step 1 - Avvia sessione Inps
Utilizzando la chiave pubblica, avvia una sessione scegliendo il tipo di login e specificando come ente = 'inps'. Per comodità nell'esempio useremo lo SPID di Poste Italiane. Per tutti gli altri metodi fai riferimento alla documentazione.
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/avvia_sessione' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"ente": "inps",
"tipo_login": "poste"
}'
Nella risposta riceverai un oggetto di tipo Sessione. Questo è l'oggetto di riferimento che cambierà successivamente stato. Gli aggiornamenti della sessione ti arriveranno tramite webhook o potrai richiedere di nuovo l'oggetto tramite API /sessione:id_sessione.
{
"sessione": {
"ente": "inps",
"tipo_login": "poste",
"data_creazione": 1745416075138,
"stato": "creazione_form_login",
"_id": "6808ef8b2afb2df510155140"
}
}
Da qui in avanti dovrai attendere l'arrivo degli aggiornamenti sul webhook, relativi alla sessione appena avviata, fino allo stato in cui sarà richiesto il login.
Step 2 - Webhook aggiornamenti sessione
La sessione appena avviata passerà diversi stati successivi e quando lo stato sarà richiesta_accesso
dovrai scannerizzare il QR code con l'app di Poste.it che trovi nel campo qr_code in formato data URL.
Ecco l'esempio di dato che ti arriverà tramite webhook all'endpoint che hai impostato (dettagli in documentazione webhook):
{
"tipo_dato": "Sessione",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"ente": "inps",
"tipo_login": "poste",
"data_creazione": 1742983959743,
"id_organization": "643f1a2c9f8b9a1d2e3c4b5a",
"stato": "richiesta_accesso",
"qr_code": "data:image/png;base64,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",
"_id": "5fa1c3d49b7e6f2a4d8e9c01"
}
}
Attraverso il data URL potrai visualizzare il QR code al tuo utente o semplicemente aprirlo in una pagina del browser per permettere la scannerizzazione.
Step 3 - Sessione avviata
Dopo aver effettuato l'accesso, lo stato della sessione cambierà in autenticato (sempre attraverso aggiornamenti webhook)
e quando lo stato sarà sessione_attiva potrai iniziare a usare gli utenti che risultano inizializzati.
Con la Sessione in stato sessione_attiva potrai analizzare quanti servizi sono disponibili per l'utenza con cui hai effettuato l'accesso.
Attualmente i principali sono iva_servizi, cassetto_fiscale e inps. In questi campi di
Sessione troverai indicazione sullo stato del servizio.
{
"_id": "6808ef8b2afb2df510155140",
"ente": "inps",
"tipo_login": "poste",
"data_creazione": 1745416075138,
"stato": "sessione_attiva",
"utente_connesso": {
"identificativo": "RSSMRT19834U749V",
"denominazione": "ROSSI MARIO"
},
"data_avvio": 1745416092146
}
Step 4 - Richiesta consultazione estratto conto
Con l'endpoint POST /api_esterne/inps/estratto_conto/:id_sessione potri richiedere in modo asincrono la consultazione degli estratti conto previdenziali, di seguito l'esempio:
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/inps/estratto_conto/<id_sessione>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
In risposta avremo il seguente oggetto come classe estratto conto
{
"_id": "6808efb82afb2df510155144",
"data_creazione": 1745416120288,
"id_sessione": "6808ef8b2afb2df510155140",
"serizio": "inps",
"stato": "in_corso"
}Step 5 - Verifica estratto conto
Dopo aver creato una nuova richiesta di consultazione estratto conto previdenziale, sarà necessario controllarne lo stato in modo da ottenere poi gli identificativi dei file che andremo a scaricare nel prossmio step.
Abbiamo due modi per verificarne lo stato:
- Tramite webhook
- API
GET /api_esterne/inps/estratto_conto/:id_estratto_conto
Con il webhook riceverai il seguente dato:
{
"tipo_dato": "EstrattoConto",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"_id": "6808efb82afb2df510155144",
"data_creazione": 1745416120288,
"id_file": "6808efbf2afb2df510155155"
"id_sessione": "6808ef8b2afb2df510155140",
"serizio": "inps",
"stato": "caricamento_completato"
}
}
Di seguito l'esempio della chiamata API per verificare lo stato della richiesta di estratto conto:
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/inps/estratto_conto/<id_estratto_conto>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
Questa la possibile risposta:
{
"_id": "6808efb82afb2df510155144",
"data_creazione": 1745416120288,
"id_sessione": "6808ef8b2afb2df510155140",
"serizio": "inps",
"stato": "in_corso"
} Dovremo dunque controllare il campo stato, quando sarà in caricamento_completato la struttura della risposta sarà la seguente:
{
"_id": "6808efb82afb2df510155144",
"data_creazione": 1745416120288,
"id_file": "6808efbf2afb2df510155155"
"id_sessione": "6808ef8b2afb2df510155140",
"serizio": "inps",
"stato": "caricamento_completato"
}
All'interno avremo il campo id_file. Per scaricare il file xml con gli estratti conto proseguiamo al prossmio step
Step 6 - Scaricamento file xml estratto conto
Dopo aver confermato lo stato dell'estratto conto, l'id_file dovremo effettuare una chiamta all'api GET /api_esterne/files/:id_files
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/files/<id_files>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
In riposta a questa api avremo il file xml con all'interno gli estratti conto, sia il RegimeGenerale che RegimeParasubordinati. NB: è possibile scaricare il file solo 3 volte, dopo di chè non sarà più possibile scaricarlo e sarà necessario effettuare una nuova richiesta di consultazione
Consultazione certificazioni uniche Cassetto Fiscale
In questa guida verrà spiegato il processo di consultazione e scaricamento delle certificazioni uniche per uno specifico anno.
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Cassetto Fiscale per eseguire la stessa procedura, qualora non utilizzasse le API offerte da FiscoAPI.
Seguendo tutti i passaggi di questa guida, potrai replicare le stesse operazioni viste nel portale CassettoFiscale
Step 1 - Crea richiesta Certificazioni
Con l'endpoint POST /api_esterne/cassetto_fiscale/certificazione_unica/<id_sessione> potri richiedere in modo asincrono la consultazione delle certificaizoni uniche per uno specifico anno (vedi documentazione), di seguito l'esempio:
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/certificazione_unica/<id_sessione>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"anno": 2023,
"utente_lavoro": "UTNTST80S23A111A"
}'
Nella risposta riceverai un oggetto di tipo Richiesta Certificazioni uniche, questo è l'oggetto di riferimento che cambierà successivamente stato.
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747231672383,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "in_corso",
"_id": "6824a3b85f32e844ba31c57c"
}
Step 2 - Verifica richiesta certificazioni
Dopo aver creato una nuova richiesta di consultazione Certificazioni uniche, sarà necessario controllarne lo stato.
Abbiamo due modi per verificarne lo stato:
- Tramite webhook
- API
GET /api_esterne/cassetto_fiscale/certificazione_unica/<id_richiesta_certificazione>
Con il webhook riceverai il seguente dato:
{
"tipo_dato": "RichiestaCertificazioneUnica",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"_id": "6824a6705f32e844ba31c583",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747232368876,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "in_corso"
}
}
Di seguito l'esempio della chiamata API per verificare lo stato della richiesta di certificazione unica:
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/certificazione_unica/<id_richiesta_certificazione>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
Questa la possibile risposta:
{
"_id": "6824a6705f32e844ba31c583",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747232368876,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "in_corso"
} Dovremo dunque controllare il campo stato, quando sarà in caricamento_completato la struttura della risposta sarà la seguente:
{
"_id": "6824a6705f32e844ba31c583",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747232368876,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2023,
"certificazioni": [
{
"id_protocollo": "T2403151016365830400011111",
"data_emissione": "15/3/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
},
{
"id_protocollo": "T2403151016365830400022222",
"data_emissione": "18/3/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
},
{
"id_protocollo": "T2403151016365830400033333",
"data_emissione": "16/5/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
}
]
}
]
}
All'interno dell'array dettaglio_anni avremo un degli oggetti con i seguenti campi:
annoAnno di riferimento delle certificazioni.certificazioniLista di oggetti di classe Certificazione Unica che rappresentano una specifica certificazione.
Step 3 - Richiedi scaricamento certificazione
Dopo esserci assicurati che la richiesta certificazione sia nello stato caricamento_completato possiamo procedere a richidere in modo asincrono lo scaricamento del file.
Per ogni certificazione unica che vogliamo scaricare, una volta ottenuto il campo id_protocollo dovremo effettuare la seguente chiamata API POST /api_esterne/cassetto_fiscale/download_certificazione_unica/<id_protocollo> di seguito l'esempio:
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/download_certificazione_unica/<id_protocollo>' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json' \
--data-raw '{
"anno": 2023,
"utente_lavoro": "UTNTST80S23A111A",
"id_richiesta": "6824a6705f32e844ba31c583",
}'
Questa la possibile risposta:
{
"_id": "6824a6705f32e844ba31c583",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747232368876,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2023,
"certificazioni": [
{
"id_protocollo": "T2403151016365830400011111",
"data_emissione": "15/3/2024",
"anno": 2023,
"stato": "download_in_corso"
},
{
"id_protocollo": "T2403151016365830400022222",
"data_emissione": "18/3/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
},
{
"id_protocollo": "T2403151016365830400033333",
"data_emissione": "16/5/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
}
]
}
]
} Una volta terminato il processo di scaricamento della certificazione, lo stato di essa passerà in download_completato ed insieme ad esso sarà presente il campo id_file con il quale sarà possibile scaricare il PDF della certificazione, di seguito un esempio:
{
"_id": "6824a6705f32e844ba31c583",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747232368876,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2023,
"certificazioni": [
{
"id_protocollo": "T2403151016365830400011111",
"data_emissione": "15/3/2024",
"anno": 2023,
"stato": "download_completato"
"id_file": "6808c9ef4767c3fc09add119"
},
{
"id_protocollo": "T2403151016365830400022222",
"data_emissione": "18/3/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
},
{
"id_protocollo": "T2403151016365830400033333",
"data_emissione": "16/5/2024",
"anno": 2023,
"stato": "download_non_ancora_effettuato"
}
]
}
]
}Step 4 - Scarica file certificazione
Dopo aver confermato lo stato della certificazione unica, per ogni id_file dovremo effettuare una chiamta all'api GET /api_esterne/files/:id_file
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/files/<id_file>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
In riposta a questa api avremo il file PDF con la certificazione unica richiesta. NB: è possibile scaricare il file solo 3 volte, dopo di chè non sarà più possibile scaricarlo e sarà necessario effettuare una nuova richiesta di certificazioni
Consultazione e download versamenti F23/F24
In questa guida verrà spiegato il processo di consultazione e download di versamenti F23 e F24 come da servizio in Cassetto Fiscale in agenzia delle Entrate.
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Cassetto Fiscale per eseguire la stessa procedura, qualora non utilizzasse le API offerte da FiscoAPI.
Nei seguenti esempi andremo a consultare e scaricare versamenti di tipo F24, nel caso è possibile effettuarli per F23 modificando l'endpoint delle api.
Step 1 - Crea richiesta Versamento
Per poter consultare la lista di versamenti F24 è come prima cosa necessario creare una richiesta di versamenti, in questa richiesta dovremo specificare per che anno vogliamo ottenere la lista di versamenti F24.
Successivamente dovremo far riferimento alla richiesta anche per gli step di scaricamento
Per creare una nuova richiesta andremo ad utilizzare l'endpoint
POST /cassetto_fiscale/richiesta_versamenti_f24/:{id_sessione} (vedi documentazione).
I parametri necessari in questa POST sono:
-
id_sessione: il campo_iddella sessione che abbiamo avviato nella guida precedente (nel nostro caso5fa1c3d49b7e6f2a4d8e9c01); -
utente_lavoro: partita iva o codice fiscale dell'utente lavoro che si vuole inizializzare (nel nostro caso20002200202); -
anno: L'anno per il quale si vuole ottenere la lista di versamenti;
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/richiesta_versamenti_f24/5fa1c3d49b7e6f2a4d8e9c01' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json' \
--data-raw '{
"utente_lavoro": "20002200202",
"anno": "2022"
}'
La risposta di questa richiesta sarà un oggetto contenente la richiesta di versamento F24, che contiene lo stato che inzialmente sarà in_corso
successivi aggiornamenti andranno a modificare lo stato della richiesta.
Ecco l'esempio di risposta:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01",
"tipo": "F24",
"stato": "in_corso",
"_id": "681c5e43ced2b2e9bde77785"
}
Step 2 - Verifica richiesta versamento
Dopo aver creato una nuova richiesta di versamento, sarà necessario controllarne lo stato in modo da ottenere poi i versamenti richiesti.
Abbiamo due modi per verificarne lo stato:
- Tramite webhook
- API
GET /api_esterne/cassetto_fiscale/richiesta_versamenti_f24/:id_richiesta
Con il webhook riceverai il seguente dato:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01",
"tipo": "F24",
"stato": "in_corso",
"_id": "681c5e43ced2b2e9bde77785"
}
Di seguito l'esempio della chiamata API per verificare lo stato della richiesta di estratto conto:
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/richiesta_versamenti_f24/<id_richiesta_versamento>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
Questa la possibile risposta:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01",
"tipo": "F24",
"stato": "in_corso",
"_id": "681c5e43ced2b2e9bde77785"
} Dovremo dunque controllare il campo stato, quando sarà in caricamento_completato la struttura della risposta sarà la seguente:
{
"_id": "681c5f37ced2b2e9bde77788",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689847044,
"id_sessione": "681c5d4dced2b2e9bde77783",
"tipo": "F24",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2022,
"versamenti": [
{
"id": 0,
"data_versamento": "16/2/2022",
"numero_modelli_f24": "1",
"saldo": "0,00€",
"protocollo_telematico": "112331231233123/000092",
"stato": "download_non_ancora_effettuato",
"sezioni": [
{
"titolo": "Sezione ERARIO",
"linee": [
{
"tributo": "4001 IRPEF SALDO",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "0,00 €",
"credito": "959,04 €"
}
],
"totale": {
"importo_debito": "0,00 €",
"importo_credito": "959,04 €"
}
},
{
"titolo": "Sezione INPS",
"linee": [
{
"sede": "2700",
"causale": "AF",
"matricola": "12312512123",
"dal": "01/2021",
"al": "12/2021",
"debito": "959,04 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "959,04 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "0,00 €"
}
]
}
]
}
All'interno del dettaglio, nell'anno richiesto avremo un array di versamenti con un oggetto ogni versamento, il campo id sarà necessario in fase di download del versamento
Step 3 - Downlod versamento
Una volta verificata la presenza dei versamenti per l'anno richiesto nell'oggetto richiesta versamenti possiamo procedere con lo scaricamento dei file che potrebbero essere Modelli versamento o Quietanza versamento in base al tipo di versamento scelto F24 o F23
Con il campo _id del versamento per il quale vogliamo richiedere lo scaricamento dei file dovremo effettuare la seguente chiamata api
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/download_versamento_f24/<id_versamento>?anno=<anno>&utente_lavoro=<utente_lavoro>&id_sessione=<id_sessione>&id_richiesta=<id_richiesta_versamento>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
Questa la possibile risposta:
{
"_id": "681c5e43ced2b2e9bde77785",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "681c5d4dced2b2e9bde77783",
"tipo": "F24",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2022,
"versamenti": [
{
"id": 0,
"data_versamento": "16/2/2022",
"numero_modelli_f24": "1",
"saldo": "0,00€",
"protocollo_telematico": "112331231233123/000092",
"stato": "download_in_corso",
"sezioni": [
{
"titolo": "Sezione ERARIO",
"linee": [
{
"tributo": "4001 IRPEF SALDO",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "0,00 €",
"credito": "959,04 €"
}
],
"totale": {
"importo_debito": "0,00 €",
"importo_credito": "959,04 €"
}
},
{
"titolo": "Sezione INPS",
"linee": [
{
"sede": "2700",
"causale": "AF",
"matricola": "12312512123",
"dal": "01/2021",
"al": "12/2021",
"debito": "959,04 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "959,04 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "0,00 €"
}
]
}
]
} Dovremo dunque controllare il campo stato all'interno del versamento, passerà in download_in_corso e una volta compeltato in download_completato
Quando raggiunge lo stato download_completato avremo i seguenti campi aggiunti nel versamento richiesto
{
"_id": "681c5e43ced2b2e9bde77785",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "681c5d4dced2b2e9bde77783",
"tipo": "F24",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2022,
"versamenti": [
{
"id": 0,
"data_versamento": "16/2/2022",
"numero_modelli_f24": "1",
"saldo": "0,00€",
"protocollo_telematico": "112331231233123/000092",
"stato": "download_completato",
"sezioni": [
{
"titolo": "Sezione ERARIO",
"linee": [
{
"tributo": "4001 IRPEF SALDO",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "0,00 €",
"credito": "959,04 €"
}
],
"totale": {
"importo_debito": "0,00 €",
"importo_credito": "959,04 €"
}
},
{
"titolo": "Sezione INPS",
"linee": [
{
"sede": "2700",
"causale": "AF",
"matricola": "12312512123",
"dal": "01/2021",
"al": "12/2021",
"debito": "959,04 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "959,04 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "0,00 €"
"id_file_quietanza": "681dfc4efc801e5e40dd893d",
"id_file_modello": "681dfc50fc801e5e40dd893f"
}
]
}
]
}
Con i campi id_file_quietanza e id_file_modello possiamo procedere al prossimo step
Step 4 - Scarica file versamento richiesto
Dopo aver richiesto lo scaricamento dei versamenti per ogni id_file dovremo effettuare una chiamta all'api GET /api_esterne/files/:id_files
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/files/<id_files>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
In riposta a questa api avremo il file pdf con all'interno il dettaglio del versamento
Automazione consultazione e scaricamento versamenti F23/F24 multi anno
Descriviamo ora la procedura di automazione per il la richiesta di scaricamento massivo di versamenti F23/24 per più anni.
La procedura si suddivide nei seguenti step:
- 1. Inserire una richiesta di scaricamento versamenti per più anni.
- 2. Verificare lo stato delle richieste come da portale Cassetto fiscale.
- 3. Ottenere gli identificativi dei file e scaricare i versamemnti.
Step 1 - Crea richiesta Versamento
Per poter consultare la lista di versamenti F24 è come prima cosa necessario creare una richiesta di versamenti, in questa richiesta dovremo specificare gli anniper cui vogliamo ottenere la lista versamenti F24.
Successivamente dovremo far riferimento alla richiesta anche per gli step di scaricamento
Per creare una nuova richiesta andremo ad utilizzare l'endpoint
POST /automation/richieste_versamenti_f24/:{id_sessione} (vedi documentazione).
I parametri necessari in questa POST sono:
-
id_sessione: il campo_iddella sessione che abbiamo avviato nella guida precedente (nel nostro caso5fa1c3d49b7e6f2a4d8e9c01); -
utente_lavoro: partita iva o codice fiscale dell'utente lavoro che si vuole inizializzare (nel nostro caso20002200202); -
anni: Array di anni per cui ottenere i versamenti;
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/richiesta_versamenti_f24/5fa1c3d49b7e6f2a4d8e9c01' \
--header 'Authorization: Bearer <chiave_pubblica>' \
--header 'Content-Type: application/json' \
--data-raw '{
"utente_lavoro": "20002200202",
"anni": [2023, 2024]
}'
La risposta di questa richiesta sarà un oggetto contenente la richiesta di versamento F24, che contiene lo stato che inzialmente sarà in_corso
successivi aggiornamenti andranno a modificare lo stato della richiesta.
Ecco l'esempio di risposta:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01",
"tipo": "F24",
"stato": "in_corso",
"dettaglio_anni": [
{
"anno": 2019
},
{
"anno": 2023
}
],
"_id": "681c5e43ced2b2e9bde77785"
}
Step 2 - Verifica richiesta versamento
Dopo aver creato una nuova richiesta di versamento, sarà necessario controllarne lo stato in modo da ottenere poi i versamenti richiesti.
Abbiamo due modi per verificarne lo stato:
- Tramite webhook
- API
GET /api_esterne/cassetto_fiscale/richiesta_versamenti_f24/:id_richiesta
Con il webhook riceverai il seguente dato:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01",
"tipo": "F24",
"stato": "in_corso",
"dettaglio_anni": [
{
"anno": 2019
},
{
"anno": 2023
}
],
"_id": "681c5e43ced2b2e9bde77785"
}
Di seguito l'esempio della chiamata API per verificare lo stato della richiesta di estratto conto:
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/richiesta_versamenti_f24/<id_richiesta_versamento>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
Questa la possibile risposta:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1746689603206,
"id_sessione": "5fa1c3d49b7e6f2a4d8e9c01",
"tipo": "F24",
"stato": "in_corso",
"dettaglio_anni": [
{
"anno": 2019
},
{
"anno": 2023
}
],
"_id": "681c5e43ced2b2e9bde77785"
} Dovremo dunque controllare il campo stato, quando sarà in caricamento_completato la struttura della risposta sarà la seguente:
{
"_id": "682c9e75205b4a6b02aee21d",
"utente_lavoro": "UTNTST80S23A111A",
"id_sessione": "682c9e17205b4a6b02aee21c",
"data_creazione": 1747754613690,
"tipo": "F24",
"stato": "completata",
"dettaglio_anni": [
{
"anno": 2023,
"versamenti": [
{
"id": 0,
"data_versamento": "16/2/2023",
"numero_modelli_f24": "1",
"saldo": "976,44€",
"protocollo_telematico": "23021613293263421/000100",
"stato": "download_completato",
"sezioni": [
{
"titolo": "Sezione INPS",
"linee": [
{
"sede": "2700",
"causale": "AF",
"matricola": "16000441221104606",
"dal": "01/2022",
"al": "12/2022",
"debito": "976,44 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "976,44 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "976,44 €",
"id_file_modello": "682c9e8f20a6b02aee21e",
"id_file_quietanza": "682c9e205b4a6b02aee21f"
},
{
"id": 1,
"data_versamento": "16/5/2023",
"numero_modelli_f24": "1",
"saldo": "1.052,10€",
"protocollo_telematico": "23051615255451808/000105",
"stato": "download_completato",
"sezioni": [
{
"titolo": "Sezione INPS",
"linee": [
{
"sede": "2700",
"causale": "AF",
"matricola": "16000441231101665",
"dal": "01/2023",
"al": "12/2023",
"debito": "1.052,10 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "1.052,10 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "1.052,10 €",
"id_file_modello": "682c9205b4a6b02aee220",
"id_file_quietanza": "6c9e97205b4a6b02aee221"
}
]
},
{
"anno": 2024,
"versamenti": [
{
"id": 0,
"data_versamento": "16/2/2024",
"numero_modelli_f24": "1",
"saldo": "1.052,10€",
"protocollo_telematico": "24021612183250413/000106",
"stato": "download_completato",
"sezioni": [
{
"titolo": "Sezione INPS",
"linee": [
{
"sede": "2700",
"causale": "AF",
"matricola": "16000441231104699",
"dal": "01/2023",
"al": "12/2023",
"debito": "1.052,10 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "1.052,10 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "1.052,10 €",
"id_file_modello": "682c9edf4a6b02aee22b",
"id_file_quietanza": "682e1205b4a6b02aee22c"
},
{
"id": 1,
"data_versamento": "15/3/2024",
"numero_modelli_f24": "1",
"saldo": "1.026,04€",
"protocollo_telematico": "24031515232044747/000004",
"stato": "download_completato",
"sezioni": [
{
"titolo": "Sezione ERARIO",
"linee": [
{
"tributo": "4001 IRPEF SALDO",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "850,00 €",
"credito": "0,00 €"
},
{
"tributo": "1989 INTERESSI SUL RAVVEDIMENTO - IRPEF",
"rateazione": "",
"anno": "2020",
"debito": "57,53 €",
"credito": "0,00 €"
},
{
"tributo": "TF45 IRPEF - RAVVEDIMENTO SPECIALE ART. 1, COMMI 174 E SS. LEGGE 197/2022 - SANZIONI",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "42,50 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "950,03 €",
"importo_credito": "0,00 €"
}
},
{
"titolo": "Sezione REGIONI ed ENTI LOCALI\n\n\t\t\t\t - \n\t\t\t\tREGIONI",
"linee": [
{
"regione": "13",
"tributo": "3801 ADDIZIONALE REGIONALE ALL'IMPOSTA SUL REDDITO DELLE PERSONE FISICHE",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "58,00 €",
"credito": "0,00 €"
},
{
"regione": "13",
"tributo": "1994 INTERESSI SUL RAVVEDIMENTO ADDIZIONALE REGIONALE",
"rateazione": "",
"anno": "2020",
"debito": "3,93 €",
"credito": "0,00 €"
},
{
"regione": "13",
"tributo": "TF51 ADD. REG. ALL'IRPEF - RAVV. SPECIALE ART. 1, C 174 E SS L 197/2022- SANZIONI",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "2,90 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "64,83 €",
"importo_credito": "0,00 €"
}
},
{
"titolo": "Sezione ICI/IMU ed ALTRI TRIBUTI LOCALI\n\n\t\t\t\t - \n\t\t\t\tENTI LOCALI",
"linee": [
{
"regione": "I470",
"tributo": "3844 ADDIZIONALE COMUNALE ALL'IRPEF-AUTOTASSAZIONE-SALDO",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "10,00 €",
"credito": "0,00 €"
},
{
"regione": "I470",
"tributo": "1998 INTERESSI SU RAVVED. ADDIZ. COMUN. ALL'IRPEF-AUTOTASSAZIONE-ART.13,DLGS 472/97",
"rateazione": "",
"anno": "2020",
"debito": "0,68 €",
"credito": "0,00 €"
},
{
"regione": "I470",
"tributo": "TF52 ADD. COMUNALE ALL'IRPEF - RAVV. SPECIALE ART. 1, C 174 E SS L 197/2022- SANZIONI",
"rateazione": "01 / 01",
"anno": "2020",
"debito": "0,50 €",
"credito": "0,00 €"
}
],
"totale": {
"importo_debito": "11,18 €",
"importo_credito": "0,00 €"
}
}
],
"totale": "1.026,04 €",
"id_file_modello": "682c9ee3204a6b02aee22d",
"id_file_quietanza": "682c9205b4a6b02aee22e"
}
]
}
]
}
All'interno del dettaglio_anni,avremo un array di versamenti con un oggetto ogni versamento, il campo id sarà necessario in fase di download del versamento
Step 3 - Scarica versamenti
Dopo aver richiesto lo scaricamento dei versamenti per ogni id_file_modello o id_file_quietanza dovremo effettuare una chiamta all'api GET /api_esterne/files/:id_files
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/files/<id_files>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
In riposta a questa api avremo il file PDF con all'interno il dettaglio del versamento
Consultazione certificazioni uniche Cassetto Fiscale
In questa guida verrà spiegato il processo di consultazione e scaricamento delle certificazioni uniche per più anni.
A seguire, troverai una serie di immagini che mostrano gli step equivalenti che un utente dovrebbe eseguire manualmente sul portale Cassetto Fiscale per eseguire la stessa procedura, qualora non utilizzasse le API offerte da FiscoAPI.
Seguendo tutti i passaggi di questa guida, potrai replicare le stesse operazioni viste nel portale CassettoFiscale
Step 1 - Crea richiesta Certificazioni
Con l'endpoint POST /api_esterne/cassetto_fiscale/certificazione_unica/<id_sessione> potri richiedere in modo asincrono la consultazione delle certificaizoni uniche per uno specifico anno (vedi documentazione), di seguito l'esempio:
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/automation/certificazione_unica/<id_sessione>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"anno": [2022, 2023],
"utente_lavoro": "UTNTST80S23A111A"
}'
Nella risposta riceverai un oggetto di tipo Richiesta Certificazioni uniche, questo è l'oggetto di riferimento che cambierà successivamente stato.
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747231672383,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "in_corso",
"dettaglio_anni": [
{
"anno": 2022,
"certificazioni": []
},
{
"anno": 2023,
"certificazioni": []
}
],
"_id": "6824a3b85f32e844ba31c57c"
}
Step 2 - Verifica richiesta certificazioni
Dopo aver creato una nuova richiesta di consultazione Certificazioni uniche, sarà necessario controllarne lo stato.
Abbiamo due modi per verificarne lo stato:
- Tramite webhook
- API
GET /api_esterne/cassetto_fiscale/certificazione_unica/<id_richiesta_certificazione>
Con il webhook riceverai il seguente dato:
{
"tipo_dato": "RichiestaCertificazioneUnica",
"tipo_evento": "update",
"data_invio": 1742983959780,
"dato": {
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747231672383,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "in_corso",
"dettaglio_anni": [
{
"anno": 2022,
"certificazioni": []
},
{
"anno": 2023,
"certificazioni": []
}
],
"_id": "6824a3b85f32e844ba31c57c"
}
}
Di seguito l'esempio della chiamata API per verificare lo stato della richiesta di certificazione unica:
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/cassetto_fiscale/certificazione_unica/<id_richiesta_certificazione>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
Questa la possibile risposta:
{
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747231672383,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "in_corso",
"dettaglio_anni": [
{
"anno": 2022,
"certificazioni": []
},
{
"anno": 2023,
"certificazioni": []
}
],
"_id": "6824a3b85f32e844ba31c57c"
} Dovremo dunque controllare il campo stato, quando sarà in caricamento_completato la struttura della risposta sarà la seguente:
{
"_id": "6824a6705f32e844ba31c583",
"utente_lavoro": "UTNTST80S23A111A",
"servizio": "cassetto_fiscale",
"data_creazione": 1747232368876,
"id_sessione": "68249f84eabbab0badfc4aaf",
"stato": "caricamento_completato",
"dettaglio_anni": [
{
"anno": 2022,
"certificazioni": [
{
"id_protocollo": "T2403151016365830400011111",
"data_emissione": "15/3/2024",
"anno": 2022,
"stato": "download_completato",
"id_file": "682123f88a4b8a6dcefdae5ba26"
},
{
"id_protocollo": "T2403151016365830400022222",
"data_emissione": "18/3/2024",
"anno": 2022,
"stato": "download_completato",
"id_file": "682123f88a4b8a6dcefdae5ba26"
},
{
"id_protocollo": "T2403151016365830400033333",
"data_emissione": "16/5/2024",
"anno": 2022,
"stato": "download_completato",
"id_file": "682123f88a4b8a6dcefdae5ba26"
}
]
},
{
"anno": 2023,
"certificazioni": [
{
"id_protocollo": "T2403151016365830400011111",
"data_emissione": "15/3/2025",
"anno": 2023,
"stato": "download_completato",
"id_file": "682123f88a4b8a6dcefdae5ba26"
},
{
"id_protocollo": "T2403151016365830400022222",
"data_emissione": "18/3/2025",
"anno": 2023,
"stato": "download_completato",
"id_file": "682123f88a4b8a6dcefdae5ba26"
},
{
"id_protocollo": "T2403151016365830400033333",
"data_emissione": "16/5/2025",
"anno": 2023,
"stato": "download_completato",
"id_file": "682123f88a4b8a6dcefdae5ba26"
}
]
}
]
}
All'interno dell'array dettaglio_anni avremo un degli oggetti con i seguenti campi:
annoAnno di riferimento delle certificazioni.certificazioniLista di oggetti di classe Certificazione Unica che rappresentano una specifica certificazione.
Step 3 - Scarica file certificazione
Dopo aver confermato lo stato della certificazione unica, per ogni id_file dovremo effettuare una chiamta all'api GET /api_esterne/files/:id_file
curl --location --request GET 'https://api.fiscoapi.app/api_esterne/files/<id_file>' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
In riposta a questa api avremo il file PDF con la certificazione unica richiesta. NB: è possibile scaricare il file solo 3 volte, dopo di chè non sarà più possibile scaricarlo e sarà necessario effettuare una nuova richiesta di certificazioni
Creazione e funzionamento Link
In questa guida vedremo come creare un link condivisibile con un destinatario, per esempio un cliente, che permette di accorpare diverse richieste di dati in un unico punto.
Quindi il cliente/destinatario avrà un modo semplice per condividere con il richiedente i suoi dati, effettuando solo l'operazione di accesso tramite SPID/CIE e non dovendosi preoccupare
di tutti i passaggi specifici che bisogna fare per il recupero delle informazioni necessarie.
La creazione del link condivisibile può essere fatta tramite il nostro portale oppure tramite API dagli sviluppatori.
Agli sviluppatori è considenta la creazione e la lettura delle informazioni ottenute tramite il link condivisibile ma
il flusso di autorizzazione e autenticazione del destinatario è gestito interamente dal nostro sistema con la relativa pagina web a cui avrà accesso chiunque sia in possesso del URL della richiesta.
Indicazioni su creazione tramite portale FiscoAPI
Successivamente descriveremo tutti i passaggi necessari per la creazione del link condivisibile tramite API.
Step 1 - Creazione link
Per prima cosa si crea un link condivisibile (rappresentato dalla classe Link)
con l'endpoint POST /api_esterne/crea_link (vedi documentazione).
Nei parametri vanno specificati i dati del destinatario e del richiedente nei campi:
-
nome_richiedente: il nome che verrà visualizzato al destinatario per informarlo su chi sta richiedendo i suoi dati; -
tipo_destinatario: specifica se il destinatario è una persona legale con valorepersona_legaleo una persona fisica con valorepersona_fisica; -
identificativo_destinatario: la p.iva o il codice fiscale che varia a seconda se il destinatario è una persona fisica o una persona legale. (es.UTNTST80S23A111A);
Oltre a tutte le informazioni su richiedente e destinatario vanno specificate le richieste che si vogliono fare in questo link, ovvero i dati che si vogliono richiedere al destinatario.
Per esempio nel nostro caso chiederemo l'elenco F24 degli anni 2024 e 2023 e i contributi versati all'INPS, come come è visibile nel body della richiesta.
curl --location --request POST 'https://api.fiscoapi.app/api_esterne/link/crea_link/' \
--header 'Authorization: Bearer <chiave_pubblica>;' \
--header 'Content-Type: application/json' \
--data-raw '{
"nome_richiedente": "Studio Commercialisti Rossi",
"tipo_destinatario": "persona_fisica",
"identificativo_destinatario": "UTNTST80S23A111A",
"elenco_f24": {
{
"anni": [2024, 2023]
}
},
"elenco_contributi_versati_inps": {}
}'
Nella risposta riceveremo l'oggetto di classe Link che rappresenta il nostro link condivisibile.
{
"_id": "6836cf16596d655daaa3788f2",
"identificativo_destinatario": "UTNTST80S23A111A",
"tipo_destinatario": "persona_fisica",
"nome_richiedente": "Studio Commercialisti Rossi",
"agenzia_entrate": {
"richieste": {
"elenco_f24": {
"anni": [
2024,
2023
]
}
},
"stato": "attesa_accesso"
},
"inps": {
"richieste": {
"elenco_contributi_versati_inps": {}
},
"stato": "attesa_accesso"
},
"data_creazione": 1748422422263,
"link_token": "cqQmyH4aaaPT",
"url": "https://app.fiscoapi.com/link?codice=cqQmyH4kiPT"
}
Siccome nel nostro esempio abbiamo chiesto un servizio id Agenzia delle Entrate (F24) e uno dell'INPS (contributi versati)
nel link troviamo sia il campo agenzia_entrate si quello inps.
Entrambi gli oggetti sono in stato attessa_accesso. Infatti, per avviare il recupero automatico dei dati richiesti
bisogna attendere che il destinatario faccia accesso, tramite il nostro link, ad Agenzia delle Entrate e INPS.
Per permettere al destinatario di autorizzare il recupero dei dati voluti e effettuare i vari accessi, dobbiamo condividere l'URL,
del link appena creato, che si trova nel campo url della risposta.
Successivamente, navigando su questo URL, il destinatario potra seguire tutti i passaggi e il processo si avvierà. Ecco uno screen della
pagina che vedrà il destinatario:
Non appena avrà effettuato l'accesso lo stato di questi campi cambiera successivamente in accesso_in_corso
e via via tutti gli altri stati possibili come indicato in Link.
Step 2 - Attesa aggiornamenti Link
Dopo aver creato e condiviso il Link, l'avanzamento della procedura è controllabile in due modi:
- Tramite webhook (consigliato vedi documentazione webhook)
- API
GET /api_esterne/link/{id_link}
Con il webhook riceverai gli aggiornamenti nel dato che contiene la solita classe Link.
Anche tramite endpoint ricevi la classe Link relativa ma ad ogni chiamata ti viene tolta quota di utilizzo CORE.
Step 3 - Completamento Link
Attraverso i successivi aggiornamenti di Link, arriveremo alla situazione
in cui sia agenzia_entrate sia inps avranno
stato = 'richieste_effettuate'.
{
"_id": "6836cf16596d655daaa3788f2",
"identificativo_destinatario": "UTNTST80S23A111A",
"tipo_destinatario": "persona_fisica",
"nome_richiedente": "Studio Commercialisti Rossi",
"agenzia_entrate": {
"richieste": {
"elenco_f24": {
"anni": [
2024,
2023
]
}
},
"stato": "richieste_effettuate"
},
"inps": {
"richieste": {
"elenco_contributi_versati_inps": {}
},
"stato": "richieste_effettuate"
},
"data_creazione": 1748422422263,
"link_token": "cqQmyH4aaaPT",
"url": "https://app.fiscoapi.com/link?codice=cqQmyH4kiPT"
}
Quando tutti gli enti coinvolti nel Link sono in questo stato significa che le azioni del destinatario sono state tutte compiute con successo e il nostro sistema ha lanciato le varie richieste necessarie per ottenere le informazioni.
Le informazioni non saranno immediatamente fruibili in quanto molti dei dati richiesti hanno bisogno di elaborazione come nelle API singole
che abbiamo visto in queste guide.
Questo significa che il link non è altro che un'aggregazione di nostre API singole che vengono eseguite successivamente per semplificare
il processo, quando si vogliono ottenere diversi dati contemporaneamente. Velocizzando e semplificando la procedura per il cliente/destinatario
del link.
Step 4 - Attesa risposte richieste Link
Al completamento di tutti i passaggi necessari nel Link ovvero
quando tutti gli enti coinvolti saranno in stato = 'richieste_effettuate' non ci resta che attendere
che compaia il campo risposta all'interno delle varie richieste.
Per esempio nel nostro caso, in agenzia_entrate.richieste.elenco_f24.risposta.dato avremo la risposta
alla nostra specifica richiesta che è esattamente come la risposta dell'API singola con endpoint
GET https://api.fiscoapi.app/api_esterne/automation/richieste_versamenti_f24
(vedi documentazione).
{
"_id": "6836cf16596d655daaa3788f2",
"identificativo_destinatario": "UTNTST80S23A111A",
"tipo_destinatario": "persona_fisica",
"nome_richiedente": "Studio Commercialisti Rossi",
"agenzia_entrate": {
"richieste": {
"elenco_f24": {
"anni": [
2024,
2023
],
"risposta": {
"dato": {
"_id": "682c9d4efec3e759e5494aaa9d",
"utente_lavoro": "UTNTST80S23A111A",
"id_sessione": "682c9d31fec3e75sss49429b",
"data_creazione": 1747754318919,
"tipo": "F24",
"stato": "completata",
"dettaglio_anni": [
{
"anno": 2024,
"versamenti": {...}
},
{
"anno": 2023,
"versamenti": {...}
}
]
}
}
}
},
"stato": "richieste_effettuate"
},
...
}
Per esempio, ecco la lista delle principali richieste inseribili in un link con il suo riferimento
(tutti visibili in documentazione classe Link):
-
elenco_fatture_emesse: APIGET https://api.fiscoapi.app/api_esterne/iva_servizi/file_fatture_emessee(vedi documentazione) -
elenco_fatture_ricevute: APIGET https://api.fiscoapi.app/api_esterne/iva_servizi/file_fatture_ricevute(vedi documentazione) -
elenco_f24: APIPOST https://api.fiscoapi.app/api_esterne/automation/richieste_versamenti_f24/{id_sessione}(vedi documentazione) -
elenco_f23: APIPOST https://api.fiscoapi.app/api_esterne/automation/richieste_versamenti_f23/{id_sessione}(vedi documentazione) -
elenco_contributi_versati_inps: APIPOST https://api.fiscoapi.app/api_esterne/inps/estratto_conto/{id_sessione}(vedi documentazione)