Stati e Modalità di Registrazione

⚠️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 descrive il ciclo di vita di un Record — i possibili valori di state e mode e le transizioni tra di essi, tutte attivate automaticamente dal sistema.

Stati

• Accepted: Il Record è stato ricevuto e ha superato la validazione iniziale, ma nessun esito finale è ancora stato persistito. Questo è uno stato temporaneo.
• Rejected: La Registrazione è stata ricevuta ma non ha superato i controlli di validazione interni. I dettagli sono disponibili nei messaggi di registro.
• Completed: Il Record è stato inviato con successo all’Agenzia delle Entrate ed è stato accettato. Questo è uno stato finale.
• Failed: Si è verificato un errore durante l’elaborazione. Il Record non ha superato i controlli di validazione dell’Agenzia delle Entrate, oppure un errore ha impedito al sistema di confermare l’esito della trasmissione. I dettagli sono disponibili nei messaggi di log. Questo è uno stato finale.

Modalità

• Processing: Il Record è in fase di elaborazione. Lo stato corrispondente è Accepted.
• Finished: Il Record è stato elaborato, con un esito di successo o non. Lo stato corrispondente è Rejected, Completed o Failed.

Transizioni di Stato

• POST → Accepted: La Registrazione viene creata tramite una chiamata API ed entra temporaneamente nello stato Accepted se la validazione ha esito positivo.
• POST → Rejected: Se la Registrazione non supera la validazione interna durante la creazione, transisce automaticamente allo stato Rejected, fornendo messaggi di registro aggiuntivi sull’errore.
• Accepted → Completed: Questa transizione avviene automaticamente una volta che la Registrazione è stata elaborata con successo.
• Accepted → Failed: Se si verifica un errore durante l’elaborazione, la Registrazione transisce automaticamente allo stato Failed, fornendo messaggi di registro aggiuntivi per il debug.

⚠️Importante

Lo stato finale di un record TRANSACTION viene restituito direttamente nella risposta sincrona POST — non sono necessari polling o webhook.

Transizioni di Modalità

• Processing → Finished: Una volta che la Registrazione è stata elaborata, indipendentemente dal fatto che l’esito sia positivo o negativo, transisce automaticamente alla modalità Finished.

📘Nota

Processing è la modalità predefinita per ogni INTENTION al momento della creazione. Una volta che l’INTENTION viene referenziata in una TRANSACTION, acquisisce lo stato e la modalità di quella TRANSACTION.

Per i record TRANSACTION, Processing è normalmente temporaneo e dovrebbe risolversi in modalità Finished entro pochi secondi. Se una TRANSACTION rimane in modalità Processing per più di qualche minuto, considerala una transizione bloccata e contattaci con l’ID del record in modo che possiamo investigare.