Section navigation

Riferimento API

Questa pagina è il riferimento centrale per tutti gli endpoint API di fiskaly, gli URL base, l’autenticazione e i limiti di velocità. Usala come punto di partenza per qualsiasi integrazione di prodotto.

fiskaly fornisce due architetture API. Vedi La Unified API per il confronto completo.

Unified API

La Unified API utilizza URL base condivisi e un modello di risorse comune tra i paesi. Attualmente copre SIGN FR, SIGN IT, SIGN PT, SIGN SE e SIGN CZ (anteprima).

	Dettagli
URL base TEST	`https://test.api.fiskaly.com`
URL base LIVE	`https://live.api.fiskaly.com`
Header richiesti	`X-Api-Version` (data, es. `2026-02-03`), `X-Idempotency-Key` (UUID, su POST/PATCH), `X-Scope-Identifier` (scoping risorse)
ID risorse	Generati dal server (usa `X-Idempotency-Key` per idempotenza)
Gestione org.	Integrata nell’API del prodotto (nessuna Management API separata)

Prodotto	Ultima versione API	Docs
SIGN FR	2026-06-01	Docs
SIGN IT	2026-06-01	Docs
SIGN PT	2026-06-01	Docs
SIGN SE	2026-06-01	Docs attuali
SIGN CZ (anteprima)	2026-06-01	Docs

API specializzate

Ogni API specializzata ha il proprio URL base e modello di risorse, progettata per un paese specifico. Usa la Management API per la gestione delle organizzazioni.

Prodotto	Versione API	URL base (TEST)	URL base (LIVE)	Docs
SIGN DE	v2	`kassensichv-middleware.fiskaly.com/api/v2`	`kassensichv.fiskaly.com/api/v2`	Docs interattivi
SIGN AT	v1	`rksv-middleware.fiskaly.com/api/v1`	`rksv.fiskaly.com/api/v1`	Docs
SIGN ES	v1	Contattare fiskaly per gli endpoint	Contattare fiskaly per gli endpoint	Docs
Management	v0	`dashboard.fiskaly.com/api/v0`	`dashboard.fiskaly.com/api/v0`	Docs interattivi

API prodotti complementari

Questi prodotti lavorano insieme a SIGN e non sono legati a un’architettura API specifica:

Prodotto	URL base (TEST)	URL base (LIVE)	Docs
DSFinV-K (Germania)	`dsfinvk-middleware.fiskaly.com/api/v1`	`dsfinvk.fiskaly.com/api/v1`	Docs
SUBMIT DE (Germania)	Tramite middleware SIGN DE	Tramite produzione SIGN DE	Docs
SAFE	Contattare fiskaly per gli endpoint	Contattare fiskaly per gli endpoint	Docs
E-Invoice	Contattare fiskaly per gli endpoint	Contattare fiskaly per gli endpoint	Docs
eReceipt	`receipt.fiskaly.com/api/v1`	`receipt.fiskaly.com/api/v1`	Docs interattivi

📘Disponibilità endpoint

Alcuni prodotti più recenti non hanno ancora pubblicato i loro URL base pubblicamente. Contatta il tuo account manager o sales@fiskaly.com per l’accesso agli endpoint di SIGN FR, SIGN ES, SIGN IT, SIGN PT, SIGN CZ, SAFE ed E-Invoice.

Autenticazione

Tutte le API fiskaly utilizzano lo stesso schema di autenticazione con Bearer token:

POST /auth con il tuo api_key e api_secret
Ricevi un access_token (24h) e un refresh_token (48h)
Includi il token come Authorization: Bearer <token> in tutte le richieste successive
Su 401, ri-autenticati — non riprovare con lo stesso token scaduto

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

Poi includi il token nelle richieste successive:

curl -X GET https://kassensichv-middleware.fiskaly.com/api/v2/tss \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⚠️Mantieni i tuoi secrets al sicuro

Non committare mai i secrets API nel controllo di versione né esporli nel codice lato client. Conservali in variabili di ambiente o in un secret manager.

💡Metti in cache il tuo token

L’access token è valido per 24 ore. Ri-autenticarsi ad ogni richiesta aggiunge latenza inutile. Metti in cache il token e rinnovalo solo su 401.

Ambienti

Ogni prodotto ha un ambiente TEST (sandbox) e un ambiente LIVE (produzione):

	TEST (Sandbox)	LIVE (Produzione)
Scopo	Sviluppo e test di integrazione	Transazioni reali, dati rilevanti per audit
Dati	Effimeri — sicuri per esperimenti, possono essere azzerati	Permanenti — registri legalmente vincolanti
Fatturazione	Gratuito	Per contratto
Predefinito	Tutte le nuove organizzazioni iniziano qui	Attiva tramite HUB
Prefisso URL base	Di solito include `middleware`	Dominio diretto del prodotto

⚠️TEST e LIVE sono separati

Le risorse create in TEST non esistono in LIVE. Al passaggio in produzione, devi re-provisionare tutte le risorse (TSS, client, signing unit, ecc.).

Limiti di velocità

I limiti di velocità API variano per prodotto e piano di abbonamento. Linee guida generali:

Operazione	Limite tipico	Note
Autenticazione	10 req/min	Metti in cache i token — non autenticare per transazione
Firma transazioni	200 req/min	Non dovrebbe mai essere un collo di bottiglia per il checkout normale
Generazione export	Limiti più bassi	Operazioni pesanti — usa polling asincrono
Operazioni di gestione	60 req/min	Gestione organizzazioni/API key

Header limiti di velocità

Ogni risposta API include header per aiutarti a gestire il tuo budget di richieste:

Header	Descrizione
`X-RateLimit-Limit`	Massimo di richieste consentite nella finestra corrente
`X-RateLimit-Remaining`	Richieste rimanenti nella finestra corrente
`X-RateLimit-Reset`	Timestamp Unix quando la finestra del limite si azzera
`Retry-After`	Secondi da attendere prima di riprovare (solo su risposte 429)

Se ricevi un 429 Too Many Requests, attendi con backoff esponenziale. Vedi la strategia di retry per indicazioni sull’implementazione.

Per limiti enterprise o esigenze personalizzate, contatta il tuo account manager.

Paginazione

Le API fiskaly usano due diversi pattern di paginazione a seconda dell’architettura API.

API specializzate (SIGN DE, DSFinV-K)

Le API specializzate usano la paginazione basata su offset con i parametri di query limit e offset.

Parametro	Predefinito	Massimo	Descrizione
`limit`	100	1000	Numero di elementi da restituire per pagina
`offset`	0	—	Numero di elementi da saltare dall’inizio

La risposta include count (totale elementi), data (array risultati), offset e limit.

curl -X GET "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  }
);

const { count, data, offset, limit } = await response.json();
// count: 250, data: [...50 items], offset: 100, limit: 50

Unified API (SIGN FR, SIGN IT, SIGN PT, SIGN SE, SIGN CZ)

La Unified API usa la paginazione basata su token con i parametri di query limit e token.

Parametro	Predefinito	Massimo	Descrizione
`limit`	10	100	Numero di elementi da restituire per pagina
`token`	—	—	Cursor opaco dal `pagination.token` di una risposta precedente

La risposta include results (array di risorse) e, quando esistono altre pagine, un oggetto pagination con token (cursor per la pagina successiva), next (URL pronto all’uso della pagina successiva) e limit. Sull’ultima pagina l’oggetto pagination è omesso del tutto.

# Prima pagina
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

# Pagina successiva (usa pagination.token dalla risposta precedente)
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25&token=eyJpZCI6ImFiYzEyMyJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

let token = null;
let allItems = [];

do {
  const url = new URL("https://test.api.fiskaly.com/organizations");
  url.searchParams.set("limit", "25");
  if (token) url.searchParams.set("token", token);

  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Version": "2026-06-01",
    },
  });

  const { results, pagination } = await response.json();
  allItems.push(...results);
  token = pagination?.token ?? null;
} while (token);

💡Scegli il pattern corretto

Controlla quale architettura API usa il tuo prodotto (Unificata vs. Specializzata) per determinare quale pattern di paginazione implementare. Vedi le tabelle all’inizio di questa pagina.

API SIGN

SIGN DE v2

Riferimento API interattivo — documentazione completa degli endpoint con try-it-out

SIGN AT v1

RKSV austriaco — guida all'integrazione e riferimento endpoint

SIGN FR

NF525 francese — firma, chiusure, archivi, modalità offline

SIGN ES v1

TicketBAI e Verifactu spagnoli — generazione XML, firma, invio

SIGN IT

Registratore Telematico italiano — RT cloud, lotteria scontrini

SIGN PT

SAF-T (PT) portoghese — firma di documenti certificata con ATCUD

SIGN SE (TCS)

Fiscalizzazione svedese — X.509, API XML, codici di controllo

SIGN CZ (anteprima)

EET 2.0 ceca — registrazione delle vendite in tempo reale con conferma POK

API prodotti complementari

DSFinV-K v1

Export dati fiscali tedeschi — chiusure di cassa, export di audit

SUBMIT DE v1

Invio ELSTER — registrazione contribuenti e trasmissione dichiarazioni

SAFE

Archiviazione fiscale conforme — automatizzata o tramite API

E-Invoice

Fatturazione elettronica B2B tramite Peppol — Belgio live, altri paesi in arrivo

eReceipt v1

Generazione ricevute digitali — consegna QR, email e link

Management API v0

Gestione organizzazioni, utenti e API key

SDK e strumenti

Collezioni Postman

Richieste preconfigurate per SIGN DE — esplorazione interattiva dell'API

Quick Start

Prima transazione firmata in meno di 5 minuti con esempi di codice

Codici di errore

Ogni codice di errore, la sua causa e come correggerlo

📘Nessun SDK client (ancora)

fiskaly non fornisce attualmente SDK client ufficiali. Tutte le integrazioni sono chiamate dirette all’API REST. La superficie API è abbastanza piccola da rendere un sottile wrapper HTTP nel tuo linguaggio preferito tipicamente sufficiente. Controlla il Changelog per annunci SDK.