Esplorazione dell'API con Postman

Il modo migliore per esplorare l’API SIGN DE V2 è utilizzare un’applicazione chiamata Postman. In alternativa è possibile utilizzare lo strumento da riga di comando Linux/Unix curl.

Questa guida utilizza Postman per fornire esempi di tutte le operazioni necessarie per configurare un TSS con i relativi client e transazioni. È possibile controllare i dettagli di ogni richiesta e risposta, e testare facilmente diversi scenari.

Cos’è Postman?

Postman è un’applicazione software gratuita che facilita l’esplorazione delle API.

Una raccolta Postman e un ambiente Postman forniscono un sistema di test che include tutta la configurazione necessaria per una particolare API. Basta caricare questi due file in Postman e si è pronti per iniziare a esplorare e testare.

📘Ambiente di test

Si raccomanda (ma non è obbligatorio) di utilizzare questa guida insieme al fiskaly HUB.

Si noti che questo è un ambiente di test, per test e valutazione. La sua persistenza non è garantita. Tutti i dati dell’ambiente di test vengono cancellati periodicamente senza preavviso.

📘Clienti V1 esistenti

Questa è una dimostrazione per l’ambiente di test, per la quale sarà necessario creare nuovi account temporanei utilizzati solo per test e valutazione.

Se si è un cliente con un account V1, le proprie organizzazioni e chiavi API sono ancora valide per V2. Non è necessario cambiare nulla in produzione!

---

Configurazione

1. Scaricare Postman

   Scaricare la versione gratuita di Postman da postman.com/downloads.

   È disponibile per tutte e tre le principali piattaforme: Linux, macOS e Windows. In alternativa, è disponibile anche una versione web di Postman.

2. Creare una chiave API

   Prima di iniziare con Postman, è necessario creare una chiave e un segreto API tramite il fiskaly HUB.

   

3. Scaricare il proprio ambiente personalizzato

   Andare alla pagina di avvio rapido dell’API V2 e inserire la propria chiave e il segreto API per ottenere il proprio ambiente Postman personalizzato.

   

---

Importazione dell’ambiente API V2

Per esplorare l’API SIGN DE V2 usando Postman, è necessario prima importare i file di configurazione.

1. Aprire la finestra di importazione di Postman

   Avviare Postman e, dalla finestra di importazione, selezionare Carica file.

   

2. Selezionare i file di raccolta e ambiente

   Selezionare i file di raccolta e ambiente scaricati in precedenza.

   

3. Verificare il proprio spazio di lavoro

   Ora dovrebbe essere possibile vedere 1 Raccolta e 1 Ambiente nell’area di lavoro di Postman.

   

4. Selezionare l'ambiente

   Selezionare l’ambiente SIGN DE API V2 dal menu a discesa degli ambienti.

   

💡Tip

Per assicurarsi di utilizzare la versione più aggiornata dell’API di produzione, scaricare gli ultimi file di raccolta e ambiente dalla pagina di avvio rapido dell’API V2.

---

Esecuzione della demo

La Raccolta Postman API V2 include esempi completi di ogni richiesta coinvolta nella configurazione di un ambiente TSS, dall’autenticazione iniziale fino alle esportazioni di dati.

È possibile eseguire queste richieste utilizzando il Runner di raccolta di Postman.

1. Aprire il Runner di raccolta

   Selezionare Raccolte, poi Scenario standard, quindi fare clic sul pulsante Esegui.

   

2. Eseguire la raccolta

   Postman elenca il set di richieste da eseguire. Fare clic sul pulsante Esegui SIGN DE API V2.

   

3. Controllare i risultati

   Si dovrebbe vedere un codice di stato 200 dal server per ogni richiesta, il che indica che la richiesta è andata a buon fine.

   

   Altre possibili risposte includono 400 (problema con la richiesta) o 500 (problema con il server).

La demo mostra l’ordine delle richieste per:

• Autenticazione iniziale dell’amministratore
• Creazione e gestione di un TSS
• Creazione e gestione di client
• Transazioni
• Esportazione di dati dal TSS

Le sezioni seguenti esaminano queste richieste in modo più dettagliato.

---

Comprensione delle variabili

Postman memorizza importanti valori API in variabili. Le variabili possono essere riutilizzate in diverse richieste. Se si modifica il valore di una variabile, il nuovo valore viene utilizzato in tutte quelle richieste.

Quando si importa per la prima volta l’ambiente SIGN DE API V2, contiene solo tre variabili:

Variabile	Descrizione
baseUrl	L’URL base dell’API
api_key	La propria chiave API
api_secret	Il proprio segreto API

È possibile vedere come viene utilizzata una variabile in una richiesta di autenticazione. Postman sostituisce la variabile {{baseUrl}} con il valore memorizzato nell’ambiente SIGN DE API V2:

https://kassensichv-middleware.fiskaly.com/api/v2

Quindi una richiesta di autenticazione viene effettivamente inviata tramite POST a:

https://kassensichv-middleware.fiskaly.com/api/v2/auth

---

Effettuare richieste

Facciamo una richiesta di autenticazione. È una richiesta POST inviata a {{baseUrl}}/auth.

Il corpo della richiesta utilizza variabili di ambiente:

{
  "api_key": "{{api_key}}",
  "api_secret": "{{api_secret}}"
}

Postman riceve la seguente risposta dal server (il 200 OK in verde indica il successo):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "0bd118a1-eed7-4065-9e6b-710ab3aaf445"
  },
  "access_token_expires_in": 600,
  "access_token_expires_at": 1626678863,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token_expires_in": 600,
  "refresh_token_expires_at": 1626678863
}

Si ottiene un token di accesso e un token di aggiornamento. Postman memorizza i nuovi valori nelle variabili, che vengono poi utilizzate nelle richieste successive.

📘Note

Il token di accesso scade in 600 secondi nell’ambiente di test, dopodiché la richiesta di autenticazione deve essere eseguita di nuovo. In produzione, questo è di circa 24 ore.

Allo stesso modo è possibile vedere l’intestazione e il corpo, e controllare la risposta del server, per tutte le altre richieste in questa raccolta.

---

Generazione di codice

Postman può generare il codice pertinente per effettuare richieste in una varietà di linguaggi di programmazione.

In questo esempio, genereremo la richiesta di autenticazione appropriata per curl.

1. Eseguire la richiesta di autenticazione

   Rieseguire la richiesta di autenticazione dalla raccolta.

   

2. Aprire la barra laterale dei frammenti di codice

   Fare clic sull’icona Codice nella barra laterale destra.

   

3. Selezionare il proprio linguaggio

   Appare la barra laterale dei frammenti di codice. curl dovrebbe essere selezionato per impostazione predefinita; in caso contrario, utilizzare il menu a discesa per selezionarlo.

   

4. Copiare e utilizzare il codice generato

   Ora è possibile vedere i comandi curl che corrispondono a questa richiesta Postman. Eseguirli in un terminale per autenticarsi.

   

💡Tip

La generazione di codice è preziosa per gli script bash, dove è possibile memorizzare i valori dei token in variabili. Tuttavia, Postman lo fa automaticamente, il che lo rende uno strumento conveniente per investigare le API.

---

Riferimento incrociato con l’HUB

Le richieste di gestione TSS e Client effettuate da Postman possono essere visualizzate nel fiskaly HUB.

Immediatamente dopo la creazione di una nuova organizzazione, l’HUB indica che non ci sono Client, TSS, Transazioni o Esportazioni.

Dopo aver inviato una richiesta di autenticazione seguita da una richiesta di Creazione TSS dalla raccolta Postman, aggiornare la vista HUB e si vedrà il nuovo TSS elencato.

Ulteriori operazioni Postman per gestire TSS e Client si riflettono anche nell’HUB. Il fiskaly HUB fornisce una panoramica più semplice della propria organizzazione e può gestire direttamente TSS e Client.

💡Tip

Utilizzare l’HUB insieme a Postman per verificare che le proprie richieste API abbiano l’effetto atteso sulle risorse della propria organizzazione.

---

Pagine correlate

Guida per i nuovi clienti

Guida completa alla configurazione dell'API

Manuale HUB

Gestione di organizzazioni, TSS e client

Gestione degli errori

Best practice per timeout e recupero degli errori