Guida per i nuovi clienti

Questa guida illustra il processo completo di configurazione del sistema con fiskaly SIGN DE, utilizzando una combinazione del fiskaly HUB e delle richieste API. Al termine, si disporrà di un TSS completamente funzionante con un client pronto a firmare le transazioni.

Panoramica

Prima di iniziare la configurazione, ecco cosa verrà configurato:

🏢

Organizzazione

L'entità di livello superiore in fiskaly. Le organizzazioni gestite rappresentano le singole sedi fisiche.

🔑

Chiave API e segreto

Credenziali generate nell'HUB, utilizzate per autenticare tutte le successive richieste API.

🔐

Autenticazione

Utilizzare la chiave API e il segreto per generare un token di accesso usato in tutte le chiamate API successive.

🛡️

TSS (Sistema di sicurezza tecnica)

Il componente di firma principale. Deve essere creato, configurato con un PIN amministratore e inizializzato.

💻

Client

Rappresenta un terminale punto vendita o un'applicazione che crea transazioni contro un TSS.

🧾

Transazione

Un registro fiscale firmato. Una volta che il TSS e il Client sono pronti, è possibile creare e firmare transazioni.

Guarda la nostra video guida per una spiegazione visiva del processo di configurazione.

Prerequisiti

📘Prima di iniziare

È necessario un account fiskaly e l’accesso al fiskaly HUB. Se non si dispone ancora di un account, registrarsi qui.

Sarà inoltre necessario uno strumento per effettuare richieste HTTP — ad esempio cURL (riga di comando), Postman o il proprio codice applicativo.

Configurazione passo dopo passo

Creare un'organizzazione
Quando si accede all’HUB per la prima volta, viene richiesto di creare un’organizzazione. Questa è la organizzazione principale, e tutte le organizzazioni gestite vengono create al suo interno.
In genere, ogni organizzazione gestita corrisponde a una sede fisica (es. un negozio o un ristorante).
💡Non ancora pronto per la produzione?
Per scopi di test, non è necessario compilare tutti i campi. È possibile lasciare vuoto l’indirizzo di fatturazione e completarlo in seguito.
Dopo aver creato l’organizzazione, l’HUB mostrerà la configurazione attuale — inizialmente con 0 TSS e 0 client.
Generare una chiave API e un segreto
Navigare alla sezione Chiavi API nel fiskaly HUB e creare una nuova chiave API.
Si riceverà una Chiave API e un Segreto API. Conservarli in modo sicuro — saranno necessari per tutte le successive richieste API.
⚠️Conservare le credenziali in modo sicuro
Il segreto API viene mostrato una sola volta. Assicurarsi di copiarlo e conservarlo in un luogo sicuro prima di chiudere il dialogo.
Il nostro video tutorial illustra il processo di generazione di una chiave e un segreto API.

Autenticarsi con l'API

Utilizzare la chiave e il segreto API per ottenere un token di accesso. Questo token è necessario per tutte le richieste successive.

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  }'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "your_api_key",
      api_secret: "your_api_secret",
    }),
  }
);

const { access_token } = await response.json();

Esempio di risposta (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-org-id"
  },
  "access_token_expires_in": 86400,
  "access_token_expires_at": "2026-03-02T12:00:00Z",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800,
  "refresh_token_expires_at": "2026-03-03T12:00:00Z"
}

La risposta contiene un access_token che deve essere incluso come token Bearer nell’intestazione Authorization di tutte le richieste successive.

Creare un TSS

Creare un nuovo Sistema di Sicurezza Tecnica (TSS) inviando una richiesta PUT con un ID TSS univoco (UUID).

TSS_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My first TSS"
  }'

const tssId = crypto.randomUUID();

const response = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "My first TSS",
    }),
  }
);

Esempio di risposta (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 1,
  "admin_puk": "initial-puk-from-creation",
  "state": "CREATED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Dopo la creazione, è necessario inizializzare il TSS. Ciò comporta tre sotto-passaggi:

a) Modificare il PIN amministratore

Il TSS viene creato in uno stato UNINITIALIZED. È necessario impostare un nuovo PIN amministratore prima dell’inizializzazione.

curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_puk": "initial-puk-from-creation",
    "new_admin_pin": "your-secure-admin-pin"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_puk: "initial-puk-from-creation",
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

b) Autenticarsi come amministratore

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/auth" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_pin": "your-secure-admin-pin"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin/auth`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_pin: "your-secure-admin-pin",
    }),
  }
);

c) Inizializzare il TSS

Aggiornare lo stato del TSS a INITIALIZED:

curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "INITIALIZED"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Esempio di risposta (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 2,
  "state": "INITIALIZED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Creare un client

Con il TSS inizializzato, creare un client che rappresenti il terminale punto vendita o l’applicazione.

CLIENT_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/client/${CLIENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "POS-001"
  }'

const clientId = crypto.randomUUID();

const response = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/client/${clientId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      serial_number: "POS-001",
    }),
  }
);

Esempio di risposta (200 OK)

{
  "_id": "your-client-id",
  "_type": "CLIENT",
  "_env": "TESTING",
  "_version": 1,
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Creare una transazione

Ora è possibile creare la prima transazione firmata. Le transazioni seguono un ciclo di vita: avviare la transazione, poi completarla.

a) Avviare la transazione

TX_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "ACTIVE",
    "client_id": "your-client-id"
  }'

const txId = crypto.randomUUID();

const startResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=1`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "ACTIVE",
      client_id: clientId,
    }),
  }
);

Esempio di risposta (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "_env": "TESTING",
  "_version": 1,
  "number": 1,
  "state": "ACTIVE",
  "client_id": "your-client-id",
  "client_serial_number": "POS-001",
  "tss_id": "your-tss-id",
  "tss_serial_number": "a1b2c3d4e5f6...",
  "time_start": "2026-03-01T10:00:00Z",
  "revision": 1,
  "latest_revision": 1,
  "log": {
    "operation": "START",
    "timestamp": "2026-03-01T10:00:00Z",
    "timestamp_format": "ISO8601"
  },
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:00:00Z",
    "timestamp_format": "ISO8601",
    "serial_number": "a1b2c3d4e5f6..."
  },
  "metadata": {}
}

b) Completare la transazione

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "FINISHED",
    "client_id": "your-client-id",
    "schema": {
      "standard_v1": {
        "receipt": {
          "receipt_type": "RECEIPT",
          "amounts_per_vat_rate": [
            {
              "vat_rate": "NORMAL",
              "amount": "10.00"
            }
          ],
          "amounts_per_payment_type": [
            {
              "payment_type": "CASH",
              "amount": "10.00"
            }
          ]
        }
      }
    }
  }'

const finishResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=2`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "FINISHED",
      client_id: clientId,
      schema: {
        standard_v1: {
          receipt: {
            receipt_type: "RECEIPT",
            amounts_per_vat_rate: [
              { vat_rate: "NORMAL", amount: "10.00" },
            ],
            amounts_per_payment_type: [
              { payment_type: "CASH", amount: "10.00" },
            ],
          },
        },
      },
    }),
  }
);

Esempio di risposta (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "_env": "TESTING",
  "_version": 2,
  "number": 1,
  "state": "FINISHED",
  "client_id": "your-client-id",
  "client_serial_number": "POS-001",
  "tss_id": "your-tss-id",
  "tss_serial_number": "a1b2c3d4e5f6...",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "revision": 2,
  "latest_revision": 2,
  "schema": {
    "standard_v1": {
      "receipt": {
        "receipt_type": "RECEIPT",
        "amounts_per_vat_rate": [{ "vat_rate": "NORMAL", "amount": "10.00" }],
        "amounts_per_payment_type": [
          { "payment_type": "CASH", "amount": "10.00" }
        ]
      }
    }
  },
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "log": {
    "operation": "FINISH",
    "timestamp": "2026-03-01T10:05:00Z",
    "timestamp_format": "ISO8601"
  },
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "timestamp_format": "ISO8601",
    "serial_number": "a1b2c3d4e5f6..."
  },
  "metadata": {}
}

La risposta include i dati della transazione firmata con una firma crittografica del TSS.

Disconnettere l'amministratore
Dopo aver completato la configurazione, disconnettere l’utente amministratore dal TSS.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

💡Automatizzare la configurazione

L’intera sequenza di richieste può essere integrata in una soluzione di provisioning “con un clic” che non richiede alcuna interazione manuale da parte dell’utente. I dettagli di implementazione dipendono da voi.

Raccolta Postman

È anche possibile eseguire queste richieste tramite Postman. Scaricare la raccolta e i file di ambiente per iniziare rapidamente:

Scarica la raccolta Postman

Scarica l’ambiente Postman

Consultare il tutorial Postman per istruzioni dettagliate.

Prossimi passi

Documentazione API SIGN DE

Documentazione API completa per l'endpoint KassenSichV v2 — tutte le risorse, i parametri e le risposte.

Guida all'HUB

Scopri come gestire organizzazioni, chiavi API e TSS tramite il fiskaly HUB.

Was this page helpful?

Guida per i nuovi clienti

Panoramica

Organizzazione

Chiave API e segreto

Autenticazione

TSS (Sistema di sicurezza tecnica)

Client

Transazione

Prerequisiti

Configurazione passo dopo passo

Creare un'organizzazione

Generare una chiave API e un segreto

Autenticarsi con l'API

Creare un TSS

Creare un client

Creare una transazione

Disconnettere l'amministratore

Raccolta Postman

Prossimi passi

Documentazione API SIGN DE

Guida all'HUB