Avvio rapido

fiskaly fornisce API di conformità fiscale in tutta Europa. Scegli il tuo paese qui sotto per accedere direttamente alla guida di integrazione, oppure scorri verso il basso per una procedura pratica SIGN DE.

Scegli il tuo paese

Live

Germania(SIGN DE)

KassenSichV — TSS, Client, Transaction

Live

Austria(SIGN AT)

RKSV — SCU, Cash Register, Receipt

Live

Francia(SIGN FR)

NF 525 — Organization, System, Record

Live

Italia(SIGN IT)

Conformità RT — Taxpayer, Location, System, Record

Live

Spagna(SIGN ES)

TicketBAI e Verifactu — Taxpayer, Signer, Invoice

Live

Portugal(SIGN PT)

AT — Taxpayer, System, Document

Live

Belgio(E-Invoice)

Fatturazione elettronica B2B Peppol tramite l'API Unificata

Live

Svezia(SIGN SE)

InfraSec TCS — codici di controllo basati su certificati

💡Rollout multi-paese?

Francia, Italia e Belgio condividono l’API Unificata — un’unica integrazione copre tutti e tre. Consulta la Pianificazione dell’integrazione per stime dello sforzo e timeline di rollout.

Pratico: SIGN DE in 5 minuti

La procedura seguente usa la Germania (SIGN DE) come esempio concreto. Il flusso è: autenticarsi → creare un TSS → firmare una transazione.

📘Questa procedura usa l'API Specializzata SIGN DE

Germania, Austria e Spagna hanno ciascuna un’API Specializzata dedicata. Francia e Italia usano l’API Unificata con un modello di risorse condiviso. Scegli il tuo paese sopra per la guida corretta.

Tempo per completare: ~5 minuti con cURL, ~15 minuti se stai integrando nel codice dell’applicazione.

Prerequisiti

Hai bisogno di tre cose prima di iniziare:

Un account fiskaly — registrati gratuitamente su hub.fiskaly.com
Credenziali API — genera una chiave e un segreto API nell’HUB nella tua organizzazione
Un client HTTP — cURL, Postman o la libreria HTTP del tuo linguaggio

⚠️Il tuo segreto API viene mostrato solo una volta

Copia il segreto immediatamente quando viene generato. Se lo perdi, dovrai generare una nuova coppia di chiavi. Conserva le credenziali in variabili d’ambiente o in un gestore di segreti — mai nel codice sorgente.

Ambiente

Questa guida usa l’ambiente sandbox (TEST). Tutte le nuove organizzazioni iniziano qui. Non vengono creati dati fiscali reali e non ti verrà addebitato nulla.

	Sandbox (TEST)	Produzione (LIVE)
URL base	`https://kassensichv-middleware.fiskaly.com/api/v2`	`https://kassensichv.fiskaly.com/api/v2`
Dati	Effimeri — sicuri per sperimentare	Permanenti — rilevanti per gli audit
Fatturazione	Gratuita	Per contratto
Passaggio	Predefinito per le nuove org	Abilitato tramite HUB

Passo 1: Autenticarsi

Scambia la tua chiave e il tuo segreto API per un token Bearer.

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, refresh_token } = await response.json();

import requests

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={
        "api_key": "YOUR_API_KEY",
        "api_secret": "YOUR_API_SECRET",
    },
)

data = response.json()
access_token = data["access_token"]
refresh_token = data["refresh_token"]

HttpClient client = HttpClient.newHttpClient();
String body = """ 
    {"api_key":"YOUR_API_KEY","api_secret":"YOUR_API_SECRET"}
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://kassensichv-middleware.fiskaly.com/api/v2/auth"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
// Analizza response.body() per access_token

using var client = new HttpClient();
var payload = new {
    api_key = "YOUR_API_KEY",
    api_secret = "YOUR_API_SECRET"
};

var response = await client.PostAsJsonAsync(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    payload);

var result = await response.Content
    .ReadFromJsonAsync<JsonElement>();
var accessToken = result
    .GetProperty("access_token").GetString();

Risposta attesa (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token_expires_in": 172800
}

L’access_token è valido per 24 ore. Il refresh_token è valido per 48 ore. Includi l’access token come Authorization: Bearer <token> in tutte le richieste successive.

💡Non ri-autenticarti ad ogni richiesta

Metti in cache il token e aggiornalo solo quando ricevi una risposta 401. Ri-autenticarsi ad ogni richiesta aggiunge latenza non necessaria al tuo flusso di checkout.

Passo 2: Creare e inizializzare un TSS

Un TSS (Technical Security System) è la risorsa di firma certificata. Ne hai bisogno una per ogni sede fisica. La creazione di un TSS prevede tre sotto-passi: creare, impostare il PIN Admin e inizializzare.

a) Creare il TSS

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": "Il mio primo TSS"
  }'

const tssId = crypto.randomUUID();

const tssResponse = 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: "Il mio primo TSS",
    }),
  }
);

const tss = await tssResponse.json();
// Salva tss.admin_puk — ti serve per impostare il PIN Admin

Risposta attesa (200 OK) — nota il campo admin_puk:

{
  "_id": "a1b2c3d4-...",
  "description": "Il mio primo TSS",
  "state": "UNINITIALIZED",
  "admin_puk": "123456"
}

b) Impostare il PIN Admin (usando l’admin_puk dalla risposta precedente):

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": "123456",
    "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: tss.admin_puk,
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

c) Autenticarsi come Admin e inizializzare:

# Autenticarsi come admin
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" }'

# Inizializzare il TSS
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" }'

// Autenticarsi come admin
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" }),
  }
);

// Inizializzare il TSS
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" }),
  }
);

Dopo l’inizializzazione, il state del TSS diventa INITIALIZED. Sei pronto per creare client e firmare transazioni.

Passo 3: Creare un client

Un client rappresenta un singolo terminale POS o un’istanza di applicazione collegata al TSS.

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();

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

Passo 4: Firmare una transazione

Le transazioni hanno un ciclo di vita: avvio (stato ACTIVE) poi completamento (stato FINISHED). La risposta di completamento contiene 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();

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 (qui viene generata la firma):

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

const signedTx = await finishResponse.json();
console.log(signedTx.signature);

Risposta attesa (200 OK) — i campi chiave sono signature e qr_code_data:

{
  "_id": "tx-uuid-...",
  "state": "FINISHED",
  "number": 1,
  "time_start": 1700000000,
  "time_end": 1700000001,
  "signature": {
    "value": "dGVzdC1zaWduYXR1cmU=",
    "algorithm": "ecdsa-plain-SHA384",
    "counter": 1,
    "public_key": "BHHz..."
  },
  "qr_code_data": "V0;TSS-ID;TX-NUMBER;..."
}

La stringa qr_code_data è quella che codifichi nel QR code stampato sulla ricevuta.

Passo 5: Disconnettere l’Admin

Al termine della configurazione, disconnetti l’admin dal TSS:

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Errori comuni al primo utilizzo

Errore	Causa	Soluzione
`401 Unauthorized`	Token scaduto o non corretto	Ri-autenticati con `/auth`. Verifica di usare la chiave API corretta per questo ambiente.
`400 E_TSS_NOT_INITIALIZED`	Tentato di creare un client o una transazione su un TSS non inizializzato	Completa tutti e tre i passi di configurazione del TSS: crea, imposta il PIN Admin, inizializza.
`400` con errore “admin_puk”	PUK errato nell’impostazione del PIN Admin	Usa il valore `admin_puk` dalla risposta di creazione del TSS, non un valore scelto da te.
`409 Conflict`	Riutilizzato un UUID già esistente	Genera un nuovo UUID per ogni risorsa (TSS, client, transazione).
`422 E_TX_INVALID_STATE`	Tentato di completare una transazione che non è `ACTIVE`	Avvia prima la transazione (revisione 1 con `state: ACTIVE`), poi completala (revisione 2).

Per il riferimento completo degli errori, consulta Codici di errore.

Usare Postman invece

Se preferisci un flusso di lavoro basato su GUI, scarica la raccolta Postman preconfigurata:

Scaricare
Ottieni i file Postman Collection e Environment.
Importare
Importa entrambi i file in Postman.
Configurare
Imposta api_key e api_secret nelle variabili d’ambiente.
Eseguire
Esegui le richieste in ordine — la raccolta usa variabili per collegare automaticamente le risposte.

Consulta il Tutorial Postman per una guida dettagliata.

Cosa costruire dopo

Guida completa SIGN DE

Configurazione completa inclusa la gerarchia organizzativa, il provisioning in produzione e i QR code delle ricevute

Gestione degli errori

Strategia di timeout, logica di retry e cosa fare quando il TSS non è disponibile

Integrazione DSFinV-K

Obbligatorio per la Germania: genera esportazioni di dati fiscali conformi per gli audit

Riferimento API

Documentazione completa degli endpoint, tutti gli URL base dei prodotti e i limiti di frequenza

Espandersi in un altro paese

Cosa cambia quando aggiungi Austria, Francia, Spagna, Italia o Svezia

Pianificazione dell'integrazione (PM)

Stime dello sforzo, checklist di conformità e timeline di rollout

Was this page helpful?

Avvio rapido

Scegli il tuo paese

Germania(SIGN DE)

Austria(SIGN AT)

Francia(SIGN FR)

Italia(SIGN IT)

Spagna(SIGN ES)

Portugal(SIGN PT)

Belgio(E-Invoice)

Svezia(SIGN SE)

Pratico: SIGN DE in 5 minuti

Prerequisiti

Ambiente

Passo 1: Autenticarsi

Passo 2: Creare e inizializzare un TSS

Passo 3: Creare un client

Passo 4: Firmare una transazione

Passo 5: Disconnettere l’Admin

Errori comuni al primo utilizzo

Usare Postman invece

Scaricare

Importare

Configurare

Eseguire

Cosa costruire dopo

Guida completa SIGN DE

Gestione degli errori

Integrazione DSFinV-K

Riferimento API

Espandersi in un altro paese

Pianificazione dell'integrazione (PM)