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.

Passo 1 Immagine 1

Passo 2 Immagine 1

Passo 3 Immagine 1

Passo 4 Immagine 1

Passo 5 Immagine 1

Passo 6 Immagine 1

Passo 7 Immagine 2

Passo 8 Immagine 3

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.

Impostazioni utente Immagine 1

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.

Esempio visualizzazione QR Code Immagine 1

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 10001100101 ha il campo stato = inizializzato ed è quindi pronta all'uso;
la p.iva 20002200202 ha il campo stato = da_inizializzare che 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 _id della sessione che abbiamo appena avviato (nel nostro caso 5fa1c3d49b7e6f2a4d8e9c01);
utente_lavoro: la p.iva dell'utente inizializzato. (nel nostro caso 10001100101);
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": "poste",
    "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.

Immagine che descrive in che punto ti trovi rispetto all'accesso Namirial direttamente su Agenzia delle Entrate Immagine 1

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.

Immagine che descrive in che punto ti trovi rispetto all'accesso Namirial direttamente su Agenzia delle Entrate Immagine 1

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.

Passo 1 Immagine 1

Passo 2 Immagine 1

Passo 3 Immagine 1

Passo 4 Immagine 1

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 _id della sessione che abbiamo avviato nella guida precedente (nel nostro caso 5fa1c3d49b7e6f2a4d8e9c01) che va messo come parametro nell'URL;
servizio: il nome del servizio per cui si vuole inizializzare l'utente (nel nostro caso iva_servizi come da campo di Sessione);
utente_lavoro: partita iva o codice fiscale dell'utente lavoro che si vuole inizializzare (nel nostro caso 20002200202);

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.

Passo 1 Immagine 1

Passo 2 Immagine 1

Passo 3 Immagine 1

Passo 4 Immagine 1

Passo 5 Immagine 1

Passo 6 Immagine 1

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 _id della sessione che abbiamo avviato nella guida precedente (nel nostro caso 5fa1c3d49b7e6f2a4d8e9c01);
utente_lavoro: partita iva o codice fiscale dell'utente lavoro che si vuole inizializzare (nel nostro caso 20002200202);
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 caso IT20002200202_001.xml);
contenuto_xml: il contenuto in formato stringa del file .xml che 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 = 1 otterremo quindi una sola fattura in elencoRisultati

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;

Introduzione

Quickstart Guide

Step 1 - Creazione chiave segreta e webhook

Step 2 - Creazione chiave pubblica

Step 3 - Avvio sessione

Step 4 - Webhook aggiornamenti sessione

Step 5 - Sessione avviata

Step 6 - Richiesta elenco fatture

Step 7 - Conclusione

Accesso con Namirial

Step 1 - Avvio sessione

Step 2 - Webhook aggiornamenti sessione

Step 3 - Selezione app OTP

Step 4 - Inserimento codice OTP

Inizializza utente lavoro

Step 1 - Avvio inizializzazione

Step 2 - Attesa fine inizializzazione

Step 3 - Conclusioni

Trasmissione e monitoraggio fatture elettroniche

Step 1 - Trasmissione file xml fattura

Step 2 - Monitoraggio stato fattura trasmessa

Step 3 - Paginazione risultati monitoraggio fatture

Step 4 - Conclusioni