Quickstart Postman

Cos'è Postman?

Postman è una piattaforma API per creare e utilizzare API. In questo quickstart, utilizzeremo Postman come comodo client API per interagire visivamente con Invoicetronic API senza dover scrivere alcun codice.

Prima di continuare, assicurati che tutti i prerequisiti sotto siano soddisfatti.

Prerequisiti

Postman è scaricato e installato sul tuo sistema.
Hai ottenuto una Chiave API attiva.
Ti sei registrato presso l'Agenzia delle Entrate (necessario per l'ambiente di produzione)

Importa la specifica OpenAPI

Apri Postman ed effettua il login con il tuo account utente se necessario. Con le versioni recenti di Postman, la creazione di un account utente gratuito è richiesta per utilizzare la funzione Import.

Apri il menu File e clicca su Import... per aprire la finestra di importazione.

Puoi copiare e incollare l'URL della specifica OpenAPI di Invoicetronic API oppure trascinarlo se lo hai già scaricato sul tuo sistema (in alternativa, puoi navigarlo).

Una volta fatto, Postman ti chiederà come importare il file di specifica:

Conferma l'opzione predefinita premendo il pulsante Import. Fatto ciò, dovresti ora vedere la Collection di Invoicetronic API nel tuo workspace Postman. Espandi la collection per vedere tutti gli endpoint disponibili.

Postman workspace — Invoicetronic API come Collection Postman.

Imposta la tua chiave API

Clicca sulla scheda Authorization. Troverai che lo schema Basic Auth è pre-selezionato, ma vogliamo impostare la nostra chiave API di test in modo da non doverla reinserire ad ogni richiesta.

Postman authorization tab — Sostituisci `ik_test_MY_API_KEY` con la tua chiave API di **test**.

Passa il mouse sopra il campo di testo Username. Apparirà un dialogo con diverse opzioni. Compila il campo "enter value" con la tua chiave API di test e clicca su Collection per impostare l'Username per l'intero scope della Collection (puoi ignorare il campo Password). La variabile {{basicAuthUsername}} diventerà blu, confermando che è stata impostata.

Postman: la chiave API di test è stata impostata — La chiave API di **test** è stata impostata per lo scope della Collection.

Ora clicca sulla scheda Variables per confermare che basicAuthUsername è impostato sulla tua chiave API di test, e baseUrl è impostato sul punto di ingresso dell'API.

Postman variables tab — Tutte le variabili sono impostate e pronte all'uso.

Ora siamo pronti per effettuare una richiesta.

Effettuare una richiesta

Espandi il ramo receive nella Collection di Invoicetronic API e seleziona l'endpoint "List of incoming invoices". Nel pannello di destra, hai l'URL della richiesta precompilato e un elenco di tutti i parametri di query.

Inclusione del Payload

Per recuperare il contenuto effettivo della fattura, assicurati di selezionare il parametro include_payload nell'elenco dei parametri di query. Senza questo parametro, il campo payload sarà null per impostazione predefinita, il che aumenta le prestazioni e riduce le dimensioni della risposta quando hai bisogno solo dei metadati.

Clicca il pulsante Send per ricevere un elenco di fatture in entrata.

Postman request — La nostra prima richiesta riuscita.

Congratulazioni, hai appena eseguito una richiesta GET con successo.

Non ricevi fatture nell'ambiente di produzione?

Assicurati che i tuoi corrispondenti utilizzino 7HD37X0 come valore del campo Codice Destinatario delle loro fatture. È così che lo SDI sa che devono essere inoltrate a Invoicetronic API.

Consultare la cronologia delle notifiche

Quando invii una fattura allo SDI, la consegna non è istantanea: lo SDI esegue una serie di controlli e poi inoltra il documento al destinatario, restituendo una sequenza di notifiche che descrivono lo stato del processo (Inviato, Consegnato, Scartato, ecc.). La risorsa send espone l'ultimo stato nei campi last_update, date_sent e identifier, ma se vuoi ricostruire l'intera cronologia delle transizioni, espandi il ramo update nella Collection e seleziona l'endpoint "List of updates".

Le query su /update sono gratuite

Le richieste a /update non vengono conteggiate sul tuo piano: puoi consultare la cronologia delle notifiche con la frequenza che preferisci.

Tra i parametri di query disponibili sono particolarmente utili:

send_id: limita le notifiche a una specifica fattura inviata (passa qui l'id restituito dalla POST su /send).
state: filtra per stato; per esempio Scartato per ottenere solo le fatture rifiutate dallo SDI.
last_update_from / last_update_to: limita la ricerca a un intervallo temporale.
sort: ordina i risultati. last_update è il default ed è quello che vorrai usare per ricostruire la cronologia.

Clicca Send per ottenere la cronologia. Otterrai una risposta JSON simile a questa:

[
  {
    "send_id": 225,
    "identifier": "234234234",
    "state": 2,
    "description": null,
    "last_update": "2025-01-23T16:56:14.111000Z",
    "date_sent": "2025-01-23T16:55:51.491271Z",
    "id": 512
  },
  {
    "send_id": 225,
    "identifier": "234234234",
    "state": 5,
    "description": null,
    "last_update": "2025-01-23T17:12:03.842000Z",
    "date_sent": "2025-01-23T16:55:51.491271Z",
    "id": 537
  }
]

Il campo state è la proprietà più importante. I valori più comuni sono:

Valore	Nome	Descrizione
2	`Inviato`	Inviata allo SDI.
5	`Consegnato`	Consegnata al destinatario.
7	`Scartato`	Rifiutata dallo SDI. In `description` trovi il motivo.

L'elenco completo dei valori è disponibile nella API Reference.

Monitora sempre lo stato delle fatture inviate

Lo stato Inviato significa solo che il documento è stato preso in carico dallo SDI, non che sia stato consegnato. Uno stato Scartato indica che la fattura non è stata accettata e potrebbe richiedere una correzione e un nuovo invio.