SIGN IT - Come aggiungere un ulteriore livello alla tua struttura – fiskaly-support (IT)

Quale versione dell'API SIGN IT stai usando?

Da SIGN IT 2026-02-03 in poi, la struttura è: Organization::ACCOUNT → Organization::GROUP (obbligatorio) → Organization::UNIT.

Fino a SIGN IT 2025-08-12, la struttura è: Asset::TENANT → Asset::GROUP (opzionale) → Asset::UNIT.

Scorri fino alla sezione che corrisponde alla tua integrazione.

Da SIGN IT 2026-02-03 in poi

Di default, la tua integrazione richiede il tuo Organization::ACCOUNT e un Organization::GROUP (obbligatorio) — entrambi creati tramite la fiskaly HUB — e Organization::UNIT che rappresentano ciascuno dei tuoi clienti, creati tramite l'API SIGN IT.

Nella maggior parte dei casi, un singolo Group per Paese è sufficiente (ad es. se intendi supportare la fiscalizzazione in Italia e Francia, puoi creare un Organization::GROUP per l'Italia e uno per la Francia).

Tuttavia, se la tua organizzazione interna richiede un ulteriore livello di strutturazione all'interno di un Paese — ad esempio, per separare i contribuenti per brand, regione, ecc. — puoi aggiungere un livello aggiuntivo creando un sotto-gruppo (un Group annidato all'interno di un altro Group).

Account (organizzazione principale)
  |
  +-- Group ("Francia")
  |     |
  |     +-- Unit ("contribuente 1")
  |
  +-- Group ("Italia")
        |
        +-- Sub-group ("Brand A")
        |     |
        |     +-- Unit ("contribuente 2")
        |     +-- Unit ("contribuente 3")
        |
        +-- Sub-group ("Brand B")
              |
              +-- Unit ("contribuente 4")

Nota: Attualmente, i sotto-gruppi possono essere creati solo tramite API. Il supporto per crearli direttamente dalla fiskaly HUB potrebbe essere introdotto in futuri rilasci. Tuttavia, una volta creati, i sotto-gruppi sono già visibili nella HUB.

Importante: Una volta creata un'Organization, il suo posizionamento nella struttura non può più essere modificato. Ad esempio, una Unit creata direttamente sotto il Group principale non può essere spostato in un secondo momento sotto un Sub-group, e viceversa.

Guida passo-passo

Chiama createOrganization con type: GROUP, autenticandoti con il bearer token del Group principale (quello creato tramite la fiskaly HUB). L'ID del Group viene restituito in content.id
```
{
 "content": {
   "type": "GROUP",
   "name": "name-your-sub-group-here"
 }
}
```
Chiama createOrganization con type: UNIT, assicurandoti di impostare l'ID del Sub-Group (dal passaggio 1) come header X-Scope-Identifier. Questo garantisce che lo Unit venga creato direttamente sotto il Sub-group.

Nota: Se X-Scope-Identifier non viene fornito, l'Organization::UNIT viene creato direttamente sotto il Group principale (quello creato tramite la fiskaly HUB) per default, tramite il bearer token utilizzato.

Fino a SIGN IT 2025-08-12

Di default, la tua integrazione richiede solo la tua organizzazione principale (creata tramite la fiskaly dashboard) e degli Asset::UNIT che rappresentano ciascuno dei tuoi clienti (creati tramite l'API SIGN IT).

Se la tua struttura richiede maggiore flessibilità, puoi introdurre un livello intermedio opzionale, Asset::GROUP, per organizzare più Asset::UNIT in raggruppamenti logici.

Tenant (organizzazione principale)
  |
  +-- Group (livello opzionale)
  |     |
  |     +-- Unit ("contribuente 1")
  |     +-- Unit ("contribuente 2")
  |
  +-- Unit ("contribuente 3")
  |     
  +-- Unit ("contribuente 4")

Importante: Una volta creato un Asset, il suo posizionamento nella struttura non può più essere modificato. Ad esempio, una Unit creata direttamente sotto l'organizzazione principale (Tenant) non può essere spostato in un secondo momento sotto un Group, e viceversa.

Guida passo-passo

Chiama createAsset con type: GROUP, autenticandoti con il bearer token dell'organizzazione principale (quella creata tramite la fiskaly Dashboard). L'ID del Group viene restituito in content.id
```
{
 "content": {
   "type": "GROUP",
   "name": "name-your-asset-group-here"
 }
}
```
Chiama createAsset con type: UNIT, assicurandoti di impostare l'ID dell'Asset::GROUP (dal passaggio 1) come header X-Scope-Identifier. Questo garantisce che lo Unit venga creato direttamente sotto il Group.

Nota: Se X-Scope-Identifier non viene fornito, l'Asset::UNIT viene annidato direttamente sotto l'organizzazione principale (Asset::TENANT) per default, tramite il bearer token utilizzato.

Per saperne di più sulla terminologia e sui cambiamenti di struttura tra le versioni, vedi: SIGN IT: Nuova terminologia delle risorse.