Esplorando pagoPA: Gestione Posizioni Debitorie e integrazione sincrona Archivio Centralizzato Avvisi (ACA)
In questa sessione esploreremo come un aderente (Intermediari Tecnologici, Partner Tecnologici o Enti Creditori) possa procedere al conferimento delle posizioni debitorie sull’Archivio Centralizzato Avvisi (ACA) utilizzando le API di Gestione Posizioni Debitorie.
In questa sessione esploreremo la possibilità di conferire le posizioni debitorie sull’Archivio Centralizzato Avvisi (ACA), utilizzando le API di Gestione Posizioni Debitorie.
La sessione illustrerà i passaggi necessari per il conferimento delle posizioni debitorie da parte degli aderenti (Intermediari Tecnologici, Partner Tecnologici o Enti Creditori) sull’Archivio Centralizzato Avvisi (ACA). Questo è reso possibile dalle API di Gestione Posizioni Debitorie, di cui analizzeremo in particolare i seguenti aspetti:
- Panoramica sull’integrazione sincrona e sull’Archivio Centralizzato Avvisi (ACA)
- Obblighi a carico degli enti creditori
- Modalità di conferimento: singolo vs massivo
- Demo pratica sull’utilizzo delle API
- Analisi dei vantaggi e degli svantaggi delle diverse modalità di integrazione
Ospiti
Alberto Palazzo
Service Manager
Federico Ruzzier
Software Engineer
Le risposte alle vostre domande
Esistono altre condizioni di esclusione dal conferimento delle posizioni debitorie in ACA?
L'esclusione è prevista solo per i pagamenti "on the fly", ovvero quelli generati su richiesta diretta del debitore e con pagamento contestuale.
Qual è lo scopo della messa a disposizione dell'ACA
La messa a disposizione dell’ ACA Assicura le misure di continuità operativa del nodo dei pagamenti, rispondendo agli obblighi della Sorveglianza della Banca d'Italia ai sensi dell'articolo 146 del Testo Unico Bancario (T.U.B.)
Oltre al conferimento iniziale nell’ACA devo fare altro?
L'EC è obbligato a mantenere aggiornata la posizione debitoria su ACA per garantire un'adeguata gestione dell'attualizzazione dell'importo e dell'annullamento delle posizioni debitorie.
Cosa si intende per continuità operativa?A cosa serve lo stand-in?
Consente agli utenti di effettuare i pagamenti degli avvisi PagoPA anche se i sistemi dell'Ente Creditore sono temporaneamente indisponibili, purché l'avviso sia stato caricato in ACA.
Quali sono gli obblighi per chi decide di utilizzare l'integrazione tramite API sincrone?
L'Ente Creditore (EC) è obbligato a conferire all'Archivio Centralizzato Avvisi (ACA) tutte le posizioni debitorie da lui gestite.
L'ACA supporta i pagamenti con più beneficiari?
Si, supporta anche lo scenario multibeneficiario
Il censimento delle posizioni debitorie all’interno dell’ACA può avvenire sia in maniera puntuale che massiva?
Si, utilizzando le API apposite descritte nelle SANP l’ente può creare e gestire le posizioni debitorie ACA secondo le modalità da lui preferite.
Il caricamento massivo avviene istantaneamente?
No, ma è possibile consultare l’andamento delle operazioni mediante le API di observability messe a disposizione degli enti.
Nel caso di pagamento in regime di stand-in, gli avvisi presenti in ACA vengono aggiornati dei costi di SEND?
No, non è previsto l’aggiornamento dell’importo con le spese di notifica quanto il pagamento avviene in regime di stand-in.
Per posizioni pregresse valide e pagabili, fino a che data indietro siamo tenuti a conferire in ACA ?
Dal 1° aprile 2025, per le posizioni non pagate, data in cui è entrato in vigore l’obbligo di adeguamento.
L'adesione all'ACA è normata da qualche norma e quale/quali sono?
La messa a disposizione dell’ ACA assicura le misure di continuità operativa del nodo dei pagamenti, rispondendo agli obblighi della Sorveglianza della Banca d'Italia ai sensi dell'articolo 146 del Testo Unico Bancario (T.U.B.)
Se si utilizzano le v2, è necessario aggiornare la posizione debitoria per settarla a PAGATA o ciò avviene in automatico?
Fermo restando che l’onere dell’aggiornamento delle posizioni debitorie in ACA è in carico all’ente creditore, la piattaforma prevede dei processi automatici di allineamento degli stati delle posizioni debitorie.
Ogni Posizione Debitoria creata su GPD va automaticamente su ACA, ma le API di lettura sono le stesse, quindi quale db va interrogato di GPD o di ACA? Non mi è chiara la differenza tra GPD e ACA.
No, ACA e GPD sono due archivi distinti, le API di gestione sono similari, ma distinte. A seconda dell’endpoint scelto si interagirà con il servizio ACA (integrazione sincrona) https://api.platform.pagopa.it/aca/debt-positions-service o
GPD (integrazione asincrona).https://api.platform.pagopa.it/gpd/debt-positions-service
Perché si dovrebbe scegliere il conferimento in ACA se l'effort di sviluppo software e di processo (attività di creazione e aggiornamento delle PD) sono gli stessi dell'integrazione asincrona. Che differenze ci sono?
Il conferimento su ACA è obbligatorio nel caso di modalità di integrazione sincrona.
Il vantaggio dell’integrazione asincrona è quello che una volta caricate le posizioni debitorie, le fasi del pagamento:
- La Fase di verifica.
- La Fase di attivazione e pagamento
- La Fase di invio della ricevuta
Sono gestite internamente a PagoPA senza coinvolgimento dei sistemi dell’ente creditore / Partner Tecnologico
Una modalità di conferimento esclude l'altra? è possibile, a seconda dei casi, utilizzare API di conferimento massivo e di gestione singola?
No, una modalità di conferimento non esclude l’altra. A seconda della casistica è possibile usare le api puntuali o massive.
Che ruolo assumono i Partner Tecnologici e gli intermediari con l'ACA? un ente creditore potrebbe a questo punto integrarsi in modo diretto?
Nel caso in cui un Ente Creditore (EC) sia connesso direttamente al nodo, sarà quest’ultimo a occuparsi del conferimento delle posizioni debitorie in ACA. Se invece l’EC si avvale di un intermediario o partner tecnologico, sarà quest’ultimo a mettere a disposizione le modalità di conferimento.
Come avviene la gestione in ACA degli IUV per i quali è necessario un aggiornamento dell'importo?
È possibile aggiornare, in maniera puntuale o massiva, le posizioni debitorie, e relative opzioni di pagamento al loro interno, aggiornando il loro importo.
Se una PD viene pagata tramite standin cmq arrivano le sendrt?
L’EC avrà a disposizione le paSendRT prodotte dal nodo dei pagamenti a valle del pagamento una volta tornata disponibile la stazione.
L'aderente per caricare una posizione debitoria deve effettuare due chiamate, una a PagoPA e l'altra a ACA, giusto? A questo punto non è più conveniente che sia l'infrastruttura PagoPA a sincronizzarsi in automatico con ACA?
No, per il caricamento su ACA è necessaria una singola chiamata, puntuale o massiva, per il conferimento delle posizioni debitorie.
Le API da seguire sono indicate nelle SANP
Per un EC con un numero elevato di posizioni debitorie da attualizzare quotidianamente, l'aggiornamento delle posizioni debitorie è molto oneroso. In questo scenario cosa si può fare?
Si consiglia di utilizzare api di conferimento massivo
è possibile avere chiarimenti sul flag STDIN ?
Il flag stand-in permette di specificare se una posizione debitoria ACA è pagabile o meno in fase di stand-in.
Quante posizioni debitorie posso caricare con un solo caricamento massivo?
E' possibile utilizzare un file compresso di max 5MB (contenente circa 100K Posizioni Debitorie)
Sono integrato in maniera asincrona , posso utilizzare la modalità sincrona per alcuni pagamenti?
Si, tuttavia è sconsigliato avere più configurazioni.
Indicativamente qual'è il numero di transazioni giornaliere che consiglia l'utilizzo di API massive anzichè puntuali?
Dipende anche dal processo di caricamento interno dell’ente. Non è consigliabile chiaramente lanciare un processo che per periodo prolungato di tempo effettui operazioni puntuali.
Come è gestita in ACA la scadenza di pagabilità di uno IUV?
Nel caso una posizione debitoria ACA oltrepassi la data di scadenza, potrà essere pagata solamente se il campo switchToExpired sarà impostato a false.
Se nel caricamento massivo una delle posiozni del file viene scartata, viene scartato tutto il file o viene effettuato un caricamento parziale
Viene effettuato un caricamento parziale. Inoltre alla fine del caricamento massivo, consultando il report sarà possibile esaminare quali delle singole operazioni sono andate a buon fine e quali sono fallite.
La gestione dell'ACA prevede delle conoscenze tecniche specifiche ? è possibile apprendere il funzionamento in autonomia o servono delle conoscenze preliminari sulla scrittura di codici?
Si, l'integrazione richiede conoscenza tecniche per predisporre integrazione ai sistemi via API, per il dettaglio è possibile fare riferimento alla seguente documentazione: Integrazione tramite API sincrone | SANP | Piattaforma pagoPA | DevPortal
Nel caso di integrazione a pagoPa con API asincrone, è obbligatorio inviare ad ACA?
Se gli Enti Creditori e/o i loro Intermediari Tecnologici e/o Partner Tecnologici si avvalgono dell’integrazione tramite API Asincrone, tale integrazione è resa disponibile per il tramite del servizio di Gestione delle Posizioni Debitorie (GPD), il cui obiettivo è quello di offrire la gestione tecnica delle posizioni debitorie dell’Ente Creditore. EC/IT/PT si occuperà del conferimento in GPD pertanto non sarà necessario il conferimento in ACA. rif : Integrazione tramite API asincrone | SANP | Piattaforma pagoPA | DevPortal
L'aggiornamento dello stato "PAGATO" viene fatto ora dal nodo anche per l'ACA e non solo per GPD come in precedenza?
Fermo restando che l’onere dell’aggiornamento delle posizioni debitorie in ACA è in carico all’ente creditore, la piattaforma prevede dei processi automatici di allineamento degli stati delle posizioni debitorie.
Potete fornire dei casi d'uso per le posizioni debitorie rateizzate con la presenza della rata unica? Come si gestisce il pagamento o l'annullamento di una singola rata o della unica? Nel caso di utilizzo delle v2 o delle v1
Per rispondere a questa domanda si rimanda all’apposita sezione delle SANP: Casi d'uso | SANP | Piattaforma pagoPA | DevPortal
Nel caso in cui venga pagata la rata unica, la posizione viene posta nello stato PAID e dunque non sarà possibile ulteriori piani rateali. Viceversa nel caso di pagamento di singola rata è a carico dell’ente creditore/ partner procedere con eventuale annullamento/inibizione della rata unica.