Stati e Modalità di Entità e Sistema

⚠️Warning

Stai visualizzando la documentazione per la versione API 2025-08-12. La versione più recente è 2026-06-01. Le modifiche principali includono una terminologia aggiornata (Asset → Organization, Entity → Taxpayer/Location).

Questa sezione fornisce una panoramica dello state e del mode che definiscono il ciclo di vita e il comportamento operativo delle risorse Entità e Sistemi. Il diagramma seguente illustra le transizioni tra questi stati e modalità, descrivendo in dettaglio come la risorsa evolve dalla creazione al decomissionamento e come le sue modalità operative si adattano in base a eventi interni o chiamate API esterne.

Comprendere queste transizioni è essenziale per gestire le risorse in modo efficace, garantire operazioni fluide e risolvere problemi come credenziali non valide o pause temporanee.

Stati

• Acquired: Stato iniziale della risorsa alla creazione. In questo stato non è possibile eseguire operazioni.
• Commissioned: La risorsa è pronta e pienamente operativa (a condizione che la modalità sia operative).
• Decommissioned: La risorsa non è più operativa e non può eseguire alcun compito.

Modalità

• Inactive: Modalità iniziale della risorsa al momento della creazione. In questa modalità non è possibile eseguire operazioni.
• Operative: La risorsa è pienamente funzionale e opera come previsto.
• Suspended: La risorsa è temporaneamente in pausa tramite una chiamata API (PATCH) — ad es. per aggiornare le credenziali Fisconline o altre informazioni della risorsa. Una volta completato l’aggiornamento, la risorsa può essere riportata a Operative.
• Degraded (non ancora disponibile in LIVE in questa versione): La risorsa è operativa ma temporaneamente non disponibile, ad esempio a causa di credenziali non valide o errori. In TEST, questa modalità può essere attivata manualmente inviando il record TRANSACTION con l’header X-Taxpayer-Credentials-Expired: true per preparare la tua integrazione prima del rilascio in produzione. Per saperne di più, consulta l’articolo dedicato: Cos’è la modalità DEGRADED e come intervenire

📘Note

Ogni transizione è attivata da una chiamata API esterna o avviene automaticamente in base alla logica interna del sistema:

• PATCH indica che è necessaria una chiamata API esterna per avviare la transizione.
• INTERNAL indica che la transizione viene attivata automaticamente all’interno del sistema.

Le frecce bidirezionali indicano che la transizione può avvenire in entrambe le direzioni — ad esempio, una chiamata PATCH può spostare la modalità della risorsa da OPERATIVE → SUSPENDED o da SUSPENDED → OPERATIVE.

Transizioni di Stato

Tutte le transizioni di state sono irreversibili.

• Acquired → Commissioned: Richiede una chiamata API (PATCH) per attivare la risorsa. Se l’operazione ha esito positivo, la modalità corrispondente passa automaticamente da Inactive a Operative.
• Commissioned → Decommissioned: Richiede una chiamata API (PATCH) per contrassegnare la risorsa come non più in uso. Se l’operazione ha esito positivo, la modalità corrispondente passa da Operative a Inactive, segnando la fine del ciclo di vita della risorsa.

⚠️Avviso di fatturazione

La messa in servizio di un Sistema nell’ambiente LIVE segna l’inizio della fatturazione e avvia la trasmissione di fatture ufficiali alle autorità fiscali. Nell’ambiente TEST non avvengono fatturazioni né trasmissioni reali.

Transizioni di Modalità

• Inactive → Operative: Avviene automaticamente quando lo stato viene aggiornato con successo a Commissioned tramite una chiamata API (PATCH).
• Operative → Suspended: Attivata tramite una chiamata API (PATCH) — ad es. per sospendere temporaneamente le operazioni durante l’aggiornamento delle credenziali Fisconline o di altre informazioni della risorsa.
• Operative → Degraded (non ancora disponibile in LIVE in questa versione): Avviene automaticamente — ad es. a causa di errori persistenti delle credenziali Fisconline. In TEST, questa transizione può essere attivata manualmente inviando il record TRANSACTION con l’header X-Taxpayer-Credentials-Expired: true per preparare la tua integrazione prima del rilascio in produzione. Per saperne di più, consulta l’articolo dedicato: Cos’è la modalità DEGRADED e come intervenire
• Degraded → Suspended (non ancora disponibile in LIVE in questa versione): Deve essere attivata manualmente tramite una chiamata API (PATCH) per affrontare errori persistenti delle credenziali Fisconline prima di ripristinare il Taxpayer alla modalità Operative. Per saperne di più, consulta l’articolo dedicato: Cos’è la modalità DEGRADED e come intervenire
• Suspended → Operative: Attivata tramite una chiamata API (PATCH) una volta completati gli aggiornamenti necessari — ad es. le credenziali Fisconline o altre informazioni della risorsa.