Concetti fondamentali

Prima di integrare qualsiasi prodotto fiskaly, è utile comprendere i mattoni della piattaforma. Questi concetti si applicano a tutti i paesi e prodotti.

Organizzazioni

fiskaly utilizza un modello organizzativo gerarchico per rappresentare la struttura della tua azienda:

🏢

Account

La tua entità di livello superiore. Creata quando ti registri nell'HUB. Rappresenta il fornitore POS o il rivenditore.

📂

Gruppo

Un livello intermedio che consente di raggruppare più unità. Utile per organizzare per regione o brand.

🏪

Unità

Rappresenta un singolo commerciante o persona giuridica. Ogni unità ha i propri dati contribuente e risorse fiscali.

Nelle API più recenti (SIGN IT, SIGN FR, E-Invoice), questi sono chiamati tipi di organizzazione GROUP e UNIT. In SIGN DE, le organizzazioni gestite hanno lo stesso scopo.

Ambienti

Ogni account fiskaly dispone di due ambienti isolati:

Ambiente	Scopo	Dati
TEST	Sviluppo e test di integrazione	Simulati — nessuna connessione con le autorità fiscali
LIVE	Operazioni in produzione	Reali — le transazioni vengono comunicate alle autorità fiscali

⚠️LIVE è permanente

I record creati nell’ambiente LIVE hanno valore legale e vengono trasmessi alle autorità fiscali. Sviluppa e testa sempre nell’ambiente TEST prima.

Le chiavi API generate in TEST creano risorse TEST; le chiavi generate in LIVE creano risorse LIVE. I due ambienti sono completamente separati — non c’è condivisione di dati tra loro.

Autenticazione

Tutte le API fiskaly utilizzano l’autenticazione basata su JWT:

POST /auth  (o POST /tokens)
  { "api_key": "...", "api_secret": "..." }
    → { "access_token": "...", "refresh_token": "..." }

Token	Durata	Utilizzo
access_token	24 ore	Includi come Authorization: Bearer <token> in tutte le richieste API
refresh_token	48 ore	Usalo per ottenere un nuovo access token senza ri-autenticarsi

💡Metti in cache i tuoi token

Non ri-autenticarti ad ogni richiesta. Metti in cache l’access token e aggiornalo solo quando ricevi una risposta 401. Ri-autenticarsi ad ogni chiamata aggiunge latenza non necessaria al processo di checkout.

Autenticazione con scope (SIGN IT, SIGN FR, E-Invoice)

Le API più recenti utilizzano header aggiuntivi per limitare le richieste a una specifica organizzazione:

Header	Scopo
Authorization: Bearer <token>	Autenticazione
X-Api-Version: 2026-02-03	Selezione della versione API
X-Scope-Identifier: <org_id>	Limita le richieste a una specifica unità organizzativa
X-Idempotency-Key: <uuid>	Garantisce l’idempotenza delle operazioni di scrittura

Modello di risorse

Sebbene le risorse esatte varino per paese, la maggior parte dei prodotti fiskaly segue uno schema comune:

Account / Group
  └── Unit (Organizzazione)
        └── Taxpayer (Contribuente)
              └── Location (Sede / Sede principale)
                    └── System (Dispositivo fiscale / POS)
                          └── Record / Transaction (Record / Transazione)

Ciclo di vita delle risorse

La maggior parte delle risorse segue una macchina a stati:

ACQUIRED  →  COMMISSIONED  →  DECOMMISSIONED
(creata)     (attiva)          (dismessa)

• ACQUIRED: la risorsa è stata creata ma non è ancora attiva
• COMMISSIONED: la risorsa è attiva e può elaborare transazioni
• DECOMMISSIONED: la risorsa è dismessa e non accetta più nuove operazioni

In SIGN DE, gli stati equivalenti sono CREATED → INITIALIZED → DISABLED.

Risorse specifiche per paese

Concetto	Germania (SIGN DE)	Austria (SIGN AT)	Spagna (SIGN ES)	Italia (SIGN IT)	Francia (SIGN FR)
Unità di firma	TSS	SCU	Signer	System	System
Terminale POS	Client	Cash Register	Client	System	System
Registro fiscale	Transaction	Receipt	Invoice	Record	Record
Autorità fiscale	BSI / BZSt	FinanzOnline	AEAT / DFAs Basche	AdE (Agenzia delle Entrate)	DGFiP

URL di base

Ogni prodotto ha il proprio endpoint API. Consulta il riferimento URL di base e ambienti per un elenco completo.

Prodotto	Ambiente di test	Ambiente live
SIGN DE	kassensichv-middleware.fiskaly.com/api/v2	kassensichv.fiskaly.com/api/v2
SIGN AT	rksv.fiskaly.com/api/v1	rksv.fiskaly.com/api/v1
SIGN ES	test.es.sign.fiskaly.com/api/v1	live.es.sign.fiskaly.com/api/v1
SIGN IT	test.api.fiskaly.com	live.api.fiskaly.com
SIGN FR	test.api.fiskaly.com	live.api.fiskaly.com

Cosa c’è dopo?

Avvio rapido

Effettua la tua prima chiamata API in meno di 5 minuti

Riferimento Autenticazione

Guida dettagliata all'autenticazione con flussi di aggiornamento del token

Codici di errore

Comprendi e risolvi gli errori delle API