Idempotenza e duplicati nelle integrazioni note spese: guida tecnica per sviluppatori e reparti IT
Ogni volta che un sistema di note spese invia dati al gestionale, al sistema contabile o all'ERP, il rischio di doppia registrazione è concreto: rete instabile, rigenerazione di un export, rettifica di una spesa già inviata. Gestire questi casi richiede scelte architetturali precise fin dalla fase di design dell'integrazione. fees è pensato per supportare questo livello di controllo.
Il problema reale: quando lo stesso costo viene registrato due volte
Una doppia registrazione nasce tipicamente in tre scenari: l'export viene rigenerato e reinviato senza filtri, una spesa viene approvata, rettificata e riapprovata senza che il sistema ricevente distingua la versione aggiornata, oppure un errore di rete causa un retry che il backend non riconosce come duplicato. In tutti i casi il danno è lo stesso: un costo registrato due volte in contabilità, con riconciliazione manuale a seguire. La soluzione non sta nel bloccare i retry, ma nel garantire che ogni operazione sia identificabile in modo stabile e univoco, indipendentemente da quante volte viene inviata.
Chiavi stabili, rettifiche e rigenerazione degli export
Un'integrazione robusta richiede che ogni record di spesa porti un identificativo stabile che non cambia tra una rigenerazione e l'altra. Quando una spesa viene rettificata, il sistema ricevente deve poter distinguere se si tratta di un aggiornamento di un record esistente o di una nuova voce. I tracciati di export contabile di fees sono configurabili in formato CSV, XML o TXT: in fase di onboarding è possibile strutturare il tracciato in modo che ogni riga includa un riferimento univoco alla spesa approvata. Questo consente al sistema di destinazione di applicare una logica upsert — inserisci se nuovo, aggiorna se già presente — eliminando alla radice il rischio di duplicato per rigenerazione.
Il problema reale: quando lo stesso costo viene registrato due volte
Tramite le API fees Can, che restituiscono dati in JSON, è possibile interrogare lo stato delle spese in modo programmatico e costruire logiche di sincronizzazione lato client più granulari. Il flusso di approvazione multilivello di fees rappresenta un gate naturale: solo le spese in stato approvato definitivo vengono esposte per l'export verso la contabilità, riducendo la finestra in cui una spesa parzialmente lavorata può essere letta in modo inconsistente. Il tagging per progetto, commessa o centro di costo consente inoltre di filtrare gli export per perimetro, utile quando si vuole sincronizzare solo un sottoinsieme di spese verso sistemi specifici. La conservazione digitale dei documenti garantisce che ogni versione del record sia tracciabile nel tempo.
Q&A
Come posso evitare che una spesa rettificata venga registrata due volte nel gestionale?
Se un export viene rigenerato per un errore di rete, come mi proteggo dalla doppia importazione?
Le API fees Can supportano una logica che mi permette di leggere solo le spese approvate e non ancora esportate?
