Integrazione passo dopo passo

Questa guida illustra il processo completo di configurazione del sistema con fiskaly SIGN DE, utilizzando una combinazione del fiskaly HUB, della Management API e dell’API SIGN DE. Al termine, si disporrà di un’organizzazione gestita completamente provisioned con un TSS e un client pronti a firmare le transazioni.

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

🏢

Account e Gruppo

Il proprio Account è l'entità di livello superiore creata alla registrazione sull'HUB — rappresenta la propria azienda come fornitore POS o rivenditore. Un Gruppo è uno strato intermedio all'interno dell'Account utilizzato per raggruppare le organizzazioni gestite in modo logico (es. un Gruppo per paese).

🔑

Chiave API e Token

Credenziali generate nell'HUB e token ottenuti dalla Management API e da SIGN DE, utilizzati per autenticare tutte le richieste successive.

🏬

Organizzazione gestita

Rappresenta un'unica sede fisica (es. un negozio o ristorante), denominata Unit nell'HUB. Creata tramite la Management API e collegata a un Gruppo all'interno del proprio Account.

🛡️

TSS (Sistema di sicurezza tecnica)

Il componente di firma principale. Deve essere creato, configurato con un PIN amministratore e inizializzato prima di poter firmare le transazioni.

💻

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 avviare e completare le transazioni per generare firme crittografiche.

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, Postman o il proprio codice applicativo.

Flusso di lavoro di integrazione

Il diagramma seguente mostra tutti i dieci passaggi dell’integrazione SIGN DE. Fare clic su qualsiasi riquadro per passare al corrispondente passaggio di configurazione.

Configurazione passo dopo passo

Registrarsi sull'HUB
Andare su hub.fiskaly.com e creare il proprio account fiskaly. Si riceverà un’email di conferma — fare clic sul link per verificare il proprio indirizzo e attivare l’account.
Creare Account e Gruppo
Quando si accede all’HUB per la prima volta, viene richiesto di configurare il proprio Account — l’entità di livello superiore che rappresenta la propria azienda (fornitore POS o rivenditore). L’HUB guiderà anche nella creazione di un Gruppo, uno strato intermedio all’interno dell’Account per raggruppare le organizzazioni gestite in modo logico (ad esempio, un Gruppo per paese).
💡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 completato la configurazione, l’HUB mostrerà la panoramica attuale — inizialmente con 0 TSS e 0 client.
Creare chiave API
Navigare alla sezione Chiavi API nel fiskaly HUB e creare una nuova chiave API per il proprio Account.
Si riceverà una Chiave API e un Segreto API. Conservarli in modo sicuro — saranno necessari per tutte le richieste API successive.
⚠️Conservare le credenziali in modo sicuro
Il Segreto API viene mostrato solo una volta. Assicurarsi di copiarlo e conservarlo in un luogo sicuro prima di chiudere il dialogo.

Creare token (Management API)

Utilizzare la Chiave API e il Segreto del passaggio precedente per ottenere un token di accesso alla Management API.

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

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/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": "TEST",
    "organization_id": "00000000-0000-0000-0000-000000000000"
  },
  "access_token_expires_in": 300,
  "access_token_expires_at": 1577833200,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 300,
  "refresh_token_expires_at": 1577833200
}

Utilizzare il access_token come token Bearer nell’intestazione Authorization per tutte le richieste Management API.

Creare organizzazione/i gestita/e

Creare una o più organizzazioni gestite (denominate anche Unit nell’HUB) nel proprio Gruppo. Ogni Unit rappresenta tipicamente un’unica sede fisica come un negozio o un ristorante.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store Berlin",
    "managed_by_organization_id": "your-group-id",
    "address_line1": "Unter den Linden 1",
    "zip": "10117",
    "town": "Berlin",
    "country_code": "DEU"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/organizations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My Store Berlin",
      managed_by_organization_id: "your-group-id",
      address_line1: "Unter den Linden 1",
      zip: "10117",
      town: "Berlin",
      country_code: "DEU",
    }),
  }
);

const { _id: orgId } = await response.json();

Esempio di risposta (200 OK)

{
  "_id": "your-managed-org-id",
  "_type": "ORGANIZATION",
  "name": "My Store Berlin",
  "managed_by_organization_id": "your-group-id",
  "address_line1": "Unter den Linden 1",
  "zip": "10117",
  "town": "Berlin",
  "country_code": "DEU",
  "state": "active",
  "time_creation": "2026-03-01T10:00:00Z"
}

Annotare il _id dalla risposta — questo è l’ID dell’organizzazione gestita, necessario per il passaggio successivo.

💡Dove trovare il proprio ID Gruppo

Il proprio ID Gruppo (managed_by_organization_id) è visibile nel fiskaly HUB sotto Impostazioni → Organizzazione, oppure è possibile recuperarlo dal campo organization_id nella risposta del token della Management API (POST /api/v0/auth).

Creare chiave API (organizzazione gestita)

Generare una chiave API dedicata per l’organizzazione gestita. Questa chiave verrà utilizzata per autenticare le richieste API SIGN DE limitate a tale organizzazione.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations/${ORG_ID}/api-keys" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sign-de-key",
    "status": "enabled",
    "managed_by_organization_id": "your-group-id"
  }'

const response = await fetch(
  `https://dashboard.fiskaly.com/api/v0/organizations/${orgId}/api-keys`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "sign-de-key",
      status: "enabled",
      managed_by_organization_id: "your-group-id",
    }),
  }
);

const { key: apiKey, secret: apiSecret } = await response.json();

⚠️Salvare queste credenziali

Il secret per la chiave API dell’organizzazione gestita viene mostrato solo una volta. Conservarlo in modo sicuro prima di procedere.

Esempio di risposta (200 OK)

{
  "_id": "your-api-key-id",
  "_type": "MANAGED_API_KEY",
  "_envs": ["TEST"],
  "name": "sign-de-key",
  "key": "your-api-key",
  "secret": "your-api-secret",
  "status": "enabled",
  "managed_by_organization_id": "your-group-id",
  "created_at": 1577833200
}

Creare token (SIGN DE)

Utilizzare la chiave e il segreto API dell’organizzazione gestita per ottenere un token di accesso SIGN DE.

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "managed_org_api_key",
    "api_secret": "managed_org_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: "managed_org_api_key",
      api_secret: "managed_org_api_secret",
    }),
  }
);

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

Esempio di risposta (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-managed-org-id"
  },
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800
}

Utilizzare questo access_token come token Bearer per tutte le successive richieste API SIGN DE.

Creare TSS
Creare un nuovo Sistema di Sicurezza Tecnica (TSS) inviando una richiesta PUT con un ID TSS univoco (UUID). Il TSS deve poi essere inizializzato prima di poter firmare le transazioni.
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 '{"metadata": {}}'
Esempio di risposta (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "_env": "TEST", "_version": "2.2.2", "admin_puk": "initial-puk-from-creation", "state": "CREATED", "serial_number": "a1b2c3d4e5f6...", "public_key": "MFkwEwYH...", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "signature_algorithm": "ECDSA", "signature_timestamp_format": "unixTime", "transaction_data_encoding": "UTF-8", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": 1577833200, "metadata": {} }
⚠️Utilizzare un timeout generoso
La creazione e la personalizzazione del TSS possono richiedere fino a 30 secondi. Impostare un timeout di richiesta di almeno 30 secondi per entrambe le chiamate per evitare errori prematuri.
Dopo la creazione, inizializzare il TSS in quattro sotto-passaggi:
a) Personalizzare il TSS
Spostare il TSS dallo stato CREATED allo stato UNINITIALIZED prima di modificare il PIN amministratore:
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": "UNINITIALIZED"}'
b) Modificare il PIN amministratore
Il TSS viene creato in uno stato UNINITIALIZED. È necessario impostare un nuovo PIN amministratore utilizzando il admin_puk dalla risposta di creazione.
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": "puk-from-creation-response", "new_admin_pin": "your-secure-admin-pin" }'
c) 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" }'
d) 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" }'
Esempio di risposta (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "state": "INITIALIZED", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "serial_number": "a1b2c3d4e5f6...", "signature_algorithm": "ECDSA", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": "2026-03-01T10:00:00Z" }
💡Disconnettere l'amministratore al termine
Una volta inizializzato il TSS, disconnettere l’utente amministratore come best practice di sicurezza — richiesto prima dell’uso in produzione.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

Creare 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",
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z"
}

⚠️serial_number è permanente

Il serial_number assegnato a un client non può essere modificato dopo la creazione. Scegliere un identificatore stabile e univoco per ogni terminale POS (es. un numero di serie hardware o un UUID stabile sotto il proprio controllo).

💡Automatizzare la configurazione

L’intera sequenza di provisioning (Passi 1–9) può essere integrata in un flusso di lavoro completamente automatizzato. Una volta implementata, l’onboarding di una nuova sede non richiede alcuna interazione manuale.

Operazioni quotidiane: Creare transazione

Ora che il TSS e il Client sono provisioned, si è pronti per le operazioni quotidiane. Le transazioni seguono un ciclo di vita in due fasi che corrisponde al flusso reale della cassa:

Avviare la transazione (aprire la cassa) — inviare solo state: "ACTIVE" e client_id. In questo momento non è richiesto alcuno schema di ricevuta.
Completare la transazione (dopo il pagamento) — inviare lo schema di ricevuta completo con gli importi e il tipo di pagamento per generare la firma crittografica.

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,
    }),
  }
);

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",
  "state": "FINISHED",
  "client_id": "your-client-id",
  "tss_id": "your-tss-id",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "serial_number": "a1b2c3d4e5f6..."
  }
}

La risposta include la transazione firmata con una stringa qr_code_data per il codice QR della ricevuta e una signature crittografica del TSS.

Prossimi passi

Riferimento API SIGN DE

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

Guida per i nuovi clienti

Guida dettagliata del processo di configurazione con download di raccolte Postman e video tutorial.

Manuale utente HUB

Scopri come gestire organizzazioni, chiavi API e TSS tramite l'interfaccia del fiskaly HUB.

Convalida del codice QR

Comprendi il formato dei dati del codice QR sulle ricevute e come convalidare le transazioni firmate.

Was this page helpful?

Integrazione passo dopo passo

Account e Gruppo

Chiave API e Token

Organizzazione gestita

TSS (Sistema di sicurezza tecnica)

Client

Transazione

Prerequisiti

Flusso di lavoro di integrazione

Configurazione passo dopo passo

Registrarsi sull'HUB

Creare Account e Gruppo

Creare chiave API

Creare token (Management API)

Creare organizzazione/i gestita/e

Creare chiave API (organizzazione gestita)

Creare token (SIGN DE)

Creare TSS

Creare client

Operazioni quotidiane: Creare transazione

Prossimi passi

Riferimento API SIGN DE

Guida per i nuovi clienti

Manuale utente HUB

Convalida del codice QR