Autenticazione

Tutte le API fiskaly utilizzano l’autenticazione basata su JWT. Questa guida copre i diversi schemi di autenticazione tra i prodotti.

Flusso di autenticazione

Chiave API + Segreto  →  POST /auth (o /tokens)  →  access_token + refresh_token
                                                          │
                                                          ├─ Usa nell'header Authorization
                                                          │
                                                          └─ Su 401 → aggiorna o ri-autenticati

SIGN DE, SIGN AT, DSFINVK DE, RECEIPT

Questi prodotti usano un endpoint di autenticazione diretto:

cURLJavaScriptPython

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"},
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]

Risposta

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

Campo	Descrizione
access_token	Token JWT valido 24 ore — includere come Authorization: Bearer <token>
refresh_token	Token valido 48 ore — usare per ottenere un nuovo access token

SIGN ES

SIGN ES include la richiesta di autenticazione in un envelope content:

cURLJavaScriptPython

curl -X POST https://test.es.sign.fiskaly.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET"
    }
  }'

const response = await fetch(
  "https://test.es.sign.fiskaly.com/api/v1/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: {
        api_key: "YOUR_API_KEY",
        api_secret: "YOUR_API_SECRET",
      },
    }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://test.es.sign.fiskaly.com/api/v1/auth",
    json={"content": {"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"}},
)
access_token = response.json()["access_token"]

SIGN IT, SIGN FR, E-Invoice

Queste API più recenti usano /tokens con il discriminatore content.type e richiedono header aggiuntivi:

cURLJavaScriptPython

curl -X POST https://test.api.fiskaly.com/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{
    "content": {
      "type": "API_KEY",
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/tokens",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        key: "YOUR_API_KEY",
        secret: "YOUR_API_SECRET",
      },
    }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://test.api.fiskaly.com/tokens",
    headers={"X-Api-Version": "2026-02-03"},
    json={"content": {"type": "API_KEY", "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET"}},
)
access_token = response.json()["access_token"]

Autenticazione con scope

Per limitare le richieste a una specifica UNIT organizzativa, includi l’header X-Scope-Identifier:

Authorization: Bearer <access_token>
X-Api-Version: 2026-02-03
X-Scope-Identifier: <organization_unit_id>

Aggiornamento del token

Quando l’access token scade, usa il refresh token invece di ri-autenticarti con le credenziali:

cURLJavaScriptPython

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

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

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={"refresh_token": refresh_token},
)
access_token = response.json()["access_token"]

Best practice

💡Metti in cache i token

Gli access token sono validi per 24 ore. Metti in cache il token e aggiornalo solo in caso di risposta 401. Ri-autenticarsi ad ogni richiesta spreca ~100ms per chiamata.

⚠️Non esporre mai i segreti

• Conserva i segreti API in variabili d’ambiente o in un gestore di segreti - Non committare mai i segreti nel codice sorgente - Non includere mai i segreti nel codice lato client - Ruota le chiavi API se un segreto è compromesso

Strategia consigliata per i token

1. Autenticati una volta all’avvio dell’applicazione
2. Conserva access_token e refresh_token in memoria
3. In caso di risposta 401, tenta di aggiornare usando il refresh_token
4. Se l’aggiornamento fallisce (token scaduto), ri-autenticati con chiave API + segreto
5. Se la ri-autenticazione fallisce, mostra l’errore all’operatore

Correlati

URL di base e ambienti

Tutti gli endpoint API e i dettagli degli ambienti

Codici di errore

Codici di errore di autenticazione e risoluzione dei problemi

Concetti fondamentali

Organizzazioni, ambienti e modello di risorse