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
Sezione intitolata “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.
Group
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 PT, 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
Sezione intitolata “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 |
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
Sezione intitolata “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 |
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 PT, SIGN IT, SIGN FR, E-Invoice)
Sezione intitolata “Autenticazione con scope (SIGN PT, 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
Sezione intitolata “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 (Branch / Head Office) └── System (Dispositivo fiscale / POS) └── Record / Transaction (Record / Transazione)Ciclo di vita delle risorse
Sezione intitolata “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
Sezione intitolata “Risorse specifiche per paese”| Concetto | Germania (SIGN DE) | Austria (SIGN AT) | Spagna (SIGN ES) | Italia (SIGN IT) | Portogallo (SIGN PT) | Francia (SIGN FR) |
|---|---|---|---|---|---|---|
| Unità di firma | TSS | SCU | Signer | System | System | System |
| Terminale POS | Client | Cash Register | Client | System | System | System |
| Registro fiscale | Transaction | Receipt | Invoice | Record | Record | Record |
| Autorità fiscale | BSI / BZSt | FinanzOnline | AEAT / DFAs Basche | AdE (Agenzia delle Entrate) | AT (Autoridade Tributária e Aduaneira) | DGFiP |
URL di base
Sezione intitolata “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 |