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

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

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.

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

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 generezaione 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

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 sessione_attiva. Da questo momento in poi, potrai utilizzare questa sessione per tutte le richieste come indicato nella quickstart guide.

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.