Introduzione

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.

API Core

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.

API Link

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 sul sito dell'Agenzia delle Entrate per recuperare in modo automatico le informazioni richieste, 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.

API Automation

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.

Endpoint Api

È possibile accedere alle REST API tramite il seguente link https://api.fiscoapi.com/api_esterne/

Attivazione API

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.

Autenticazione

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:

Ha una validità di 1h, si potrà ottenere una nuova chiave utilizzando di nuovo la chiave segreta oppure il refresh token che ti serviamo insieme alla chiave pubblica in fase di creazione;
Il refresh token associato alla chiave pubblica ha una validità di 24h, successivamente dovrai per forza generare una nuova chiave pubblica con /crea_chiave_pubblica
La chiave pubblica va inserita nell'header come Bearer token delle REST API che richiedi al nostro sistema;
Se l'autenticazione fallisce, sarà restituito un JSON object di tipo Errori e con HTTP status 401.

Creazione chiave pubblica

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.

Parametri

Field	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

Field	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

HTTP Errors

Oggetto di tipo Errori:

Refresh chiave pubblica

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.

Parametri

Field	Location	Description
`refresh_token` string, required	body	Il refresh token che ti è stato fornito nella richiesta di creazione della chiave pubblica.

HTTP Request

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

HTTP Response

Field	Location	Description
`chiave_pubblica`	string	Chiave pubblica da utilizzare per autenticare tutte le chiamate HTTP

HTTP Errors

Oggetto di tipo Errori:

Limiti utilizzo

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.

Costo API

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.

Tipologie di Quote

Le quote disponibili si suddividono in due categorie distinte: Core e Inizializzazione

Come funziona il consumo

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.

Monitoraggio Consumi

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:

Evitare interruzioni di servizio per esaurimento quote
Ottimizzare le chiamate con chiamate massime o batching
Pianificare un eventuale upgrade del piano

Webhook

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:

Passo 1 Immagine 1

Passo 2 Immagine 2

Dato inviato dal webhook:

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:

Field	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

API che lanciano i webhook:

Le seguenti API avviano processi asincroni e inviano notifiche via webhook per segnalare aggiornamenti di stato, errori o completamento delle operazioni.

Avvia sessione
Inizializza utente lavoro
Scegli app OTP sessione
invia codice OTP

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

Errori

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:

Errori comuni

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

Classi

Elenco di tutte le classi utilizzate per il funzionamento delle API Core di FiscoAPI.

Sessione

Field	type	Description
`_id`	string	Identificativo univoco della sessione
`ente`	string	Nome dell'ente di autenticazione (es. agenzia_entrate).
`tipo_login`	string	Tipo di login utilizzato (es. poste).
`data_creazione`	numeric, timestmp in ms	Timestamp di creazione della sessione.
`id_organization`	string	ID dell'organizzazione collegata.
`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).
`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`	string[]	string[]	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).

Servizio

Field	type	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.

Richieste

Field	type	Description
`idRichiesta`	string	Identificativo univoco della richiesta.
`dataInserimento`	string (datetime)	Data e ora di inserimento della richiesta.
`stato`	string	Stato attuale della richiesta, può essere: `Acquisita - in elaborazione` Elaborazione in corso; `Elaborata` Richiesta elaborata;
`dataElaborazione`	string (datetime)	Data in cui la richiesta è stata elaborata (se disponibile).
`tipoRichiesta`	string	Codice del tipo di richiesta (es. "FATT").
`descrizioneTipoRichiesta`	string	Descrizione leggibile del tipo di richiesta.

Versamento

Field	type	Description
`id`	numeric, integer	Identificativo interno del versamento.
`data_versamento`	string	Data del versamento F24.
`numero_modelli_f24`	string	Numero di modelli F24 inclusi nel versamento.
`saldo`	string	Saldo complessivo del versamento.
`protocollo_telematico`	string	Protocollo identificativo del versamento telematico.
`dettaglio`	object	Dettagli delle sezioni e dei tributi versati.

Automazione

Field	type	Description
`id`	numeric, integer	Identificativo interno dell'automazione.
`id_sessione`	string	Identificativo della sessione utilizzata per generare l'automazione.
`dati_ricerca`	object	Oggetto con all'interno i dettagli della ricerca per l'automazione.
`tipo_automazione`	string	Identifica il tipo dell'automazione, puo essere `fatture_massive`.
`stato`	string	Identifica il lo stato dell'automazione, puo essere: `avviata` `caricamento_richieste_fatture_in_corso` `download_richieste_fatture_in_corso` `download_richieste_fatture_completato` `download_richieste_fatture_errore`
`data_creazione`	numeric, timestamp in ms	timestamp in ms che indica la data di creazione dell'automazione.
`dettaglio`	object	Oggetto con chiave partita IVA utente con i seguenti campi: `inizio` → timestamp in ms della data inizio ricerca `fine` →timestamp in ms della data fine ricerca `stato` → puo essere: in_errore: Errore durante il caricamento della richiesta lista fatture massive completato: Lista fatture scaricata correttamente errore_scaricamento_file: Errore durante lo scaricamento della lista fatture richiesta_creata_correttamente: Richiesta scaricamento lista fatture massive caricata correttamente `id_utente` → Identificativo della partita IVA utilizzata `id_richiesta` → Identificativo della richiesta di scaricamento fatture massive `lista_download_file` → Array di oggetti con: `nome_file` → identifica in modo univoco il file che contiene la lista di fatture specifico per la partita IVA che lo ha richiesto `stato` → puo essere file_caricato o errore_scaricamento_file `id_file` → identificativo del file, campo necessario per poter scaricare correttamente i file con l'utiilzzo dell'api automation `/api_esterne/automazione/files/:id_file`

API Core

Ecco la lista degli endpoint di tutte le funzionalità disponibili:

1 - Iva e Servizi

Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio di Agenzia delle Entrate denominato Iva e Servizi suddivisi per funzionalità principali.

1.1 - Elenco fatture

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.

1.2 - XML fattura singola

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.

1.3 - Download massivi XML fatture

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.

2 - Cassetto Fiscale

Di seguito descriviamo tutti gli endpoints delle funzionalità relative al servizio di Agenzia delle Entrate denominato Cassetto Fiscale. Ecco la lista completa: