SANP 3.4.0: Archivio centralizzato avvisi

[nardil]

Necessità: pagoPA richiede la pubblicazione degli avvisi sull'archivio centralizzato (https://docs.pagopa.it/circolare-pagopa/dettaglio-interventi/archivio-centralizzato-avvisi) come archivio di fallback qualora i servizi dell'Ente non siano disponibili.

Note: Il servizio verra' specificato nelle SANP 3.4.0 non ancora pubblicate.

Presumibilmente saranno predisposte delle api per caricare gli estremi dell'avviso con cui i PSP possano effettuare la riscossione in caso di indisponibilità dei servizi dell'Ente. L'implementazione dovrà essere trasparente nei casi di caricamento nell'APA.

Nota: chiarire l'eventualità di pagamento di un importo non aggiornato.

[pintorig]

Il servizio verra' implementato utilizzando l'openapi aggiornato alla versione SANP 3.5.0.

[nardil]

Con ogni probabilità sara' necessario prevedere nella configurazione dell'intermediario la URL di erogazione del servizio. E' stato richiesto a pagoPA un chiarimento in merito per individuare le URL reali di UAT ed Esercizio

https://github.com/pagopa/pagopa-api/issues/909

[pintorig]

Scelte implementative:

• Aggiungere alla tabella versamenti la colonna inviatoAca di tipo boolean che indica se l'avviso e' stato spedito all'archivio centralizzato. Il valore da impostare per tutte le pendenze gia' presenti in archivio e' true. Al momento del caricamento di una pendenza viene assegnato il valore false, se l'invio all'archivio va a buon fine il valore diventa true. Quando una pendenza in stato non eseguito viene modificata nei campi importo e/o data scadenza allora il valore del campo inviatoAca viene impostato a false e l'avviso verra' nuovamente inviato all'archivio.
• Per ogni pendenza selezionata per la spedizione dell'avviso la comunicazione verso PagoPA avviene tramite l'intermediario associato al dominio proprietario della pendenza, in fase di salvataggio della pendenza si deve controllare se l'intermediario configurato per il dominio e' configurato per utilizzare il servizio ACA, nel caso non lo fosse si deve impostare inviatoAca=true.
• La spedizione avviene tramite un batch che seleziona gli avvisi da inviare, cioe' le pendenze in stato=NON_ESEGUITO && inviatoAca=false, per ogni avviso da spedire viene schedulato un thread che si occupa della spedizione e della gestione dell'esito della chiamata verso PagoPA.

[pintorig]

E' stata fatta una richiesta di chiarimento a https://github.com/pagopa/pagopa-api/issues/909 con le seguenti richieste (per ognuna e' indicata l'attuale implementazione in GovPay):

1. Nel caso di pagamento multibeneficiario NON bisogna inviare l'avviso di pagamento, e' corretto? Pagamento multibeneficiario NON viene inviato l'avviso di pagamento.
2. In caso di aggiornamento di un avviso il servizio risponde sempre 201 Created? Mi aspetto sempre 201 Created.
3. Cosa succede se aggiorno un avviso modificando un campo che non sia l'importo o la data scadenza? La richiesta viene rifiutata, accettata senza modificare i dati "non modificabili" o accettata aggiornando l'avviso anche nei dati "non modificabili"? La richiesta di aggiornamento di un avviso viene fatta se si riscontra la modifica di data scadenza o importo, in tal caso tutti i campi vengono inviati con eventuali i valori modificati.
4. L'EC deve comunicare obbligatoriamente la chiusura della posizione al momento della ricezione della Ricevuta di pagamento? Vengono chiuse le posizioni inviando una richiesta con importo = 0 al momento della ricezione della ricevuta.

[pintorig]

Con il rilascio delle SANP 3.6.0 sono stati definiti tutti i punti per la gestione degli avvisi da inviare ad ACA:

Ogni EC, al momento delle creazione di una nuova posizione debitoria, deve effettuare il censimento della stessa sull’ACA tramite la paCreatePosition; grazie alla proprietà di idempotenza, per mezzo della stessa API è possibile aggiornare la posizione.

Fase di censimento

La richiesta di creazione di una nuova posizione giunge all’ACA per mezzo della paCreatePosition, fornendo in input i seguenti dati:

• fiscalCodePA: codice fiscale dell’Ente Creditore che ha creato la posizione debitoria;
• entityUniqueIdentifierType: tipologia del debitore (F=persona fisica, G=persona giuridica);
• entityUniqueIdentifierValue: codice fiscale del debitore;
• fullName: Nome e Cognome del debitore;
• IUV: identificativo univoco versamento;
• amount: importo (non è possibile censire una posizione con un importo uguale a zero);
• description: causale;
• dueDate: data di scadenza della posizione debitoria.

ACA effettua una verifica semantica e integra le informazioni della posizione:

• viene verificata la presenza di tutti i campi;
• viene verificata l'esistenza dell'EC sulla piattaforma pagoPA;
• recupera la denominazione dell’EC;
• recupera l’IBAN che verrà utilizzato in fase di accredito, viene ricercato quello configurato dall’EC tramite backoffice pagoPa o, se non presente tale configurazione, viene utilizzato quello con la modifica più recente.

Posizioni multibeneficiario

Anche le posizioni debitorie multibeneficiario devono essere inviate all'ACA, con le accortezze di seguito descritte:

• Nel campo fiscalCodePA deve essere inserito il CF dell'Ente che ha creato la posizione debitoria.
• Nei casi in cui il pagamento multibeneficiario venga gestito dal servizio StandIn di PagoPA S.p.A., le posizioni multibeneficiario verranno riversate al solo EC presente nel campo fiscalCodePA.
• gli n riversamenti verso gli n multi beneficiari saranno a carico dell'EC

[pintorig]

Fase di aggiornamento

E’ obbligatorio effettuare un aggiornamento della posizione debitoria richiamando la summenzionata API paCreatePosition nei seguenti casi:

• aggiornamento dell’importo;
• aggiornamento dello stato, per comunicare la chiusura o l’annullamento della posizione, impostando il valore del campo amount a zero;
• aggiornamento della data di scadenza.

La chiamata deve essere fatta contestualmente alla modifica effettuata sull'archivio dell'EC.

Ogni volta che viene eseguito un aggiornamento della posizione debitoria, la piattaforma aggiorna in automatico anche l’informazione dell'IBAN di accredito recuperandolo dal backoffice pagoPA.

Fase di annullamento

E' obbligatorio nel caso di posizione annullata o sostituita con una nuova effettuare l’annullamento della posizione debitoria richiamando la summenzionata API paCreatePosition.

La chiamata deve essere fatta contestualmente alla modifica effettuata sull'archivio dell'EC.

L’annullamento può essere effettuato esclusivamente impostando il valore del campo amount a zero.

Fase di chiusura

Nel caso di posizione debitoria pagata dal debitore tramite canali diversi dalla piattafroma pagoPA è necessario richiamare la summenzionata API paCreatePosition per effettuare la chiusura della stessa.

La chiusura può essere effettuata esclusivamente impostando il valore del campo amount a zero.

Come indicato nella Issue pagopa/pagopa-api#909: Lo stato della posizione viene aggiornata in automatico solo in caso di pagamento. In questa fase la piattaforma riesce ad intercettare l'esito del pagamento e in caso di esito positivo chiude in autonomia la posizione.

[pintorig]

@nardil Si e' deciso di introdurre in parallelo all'ACA anche il supporto ai servizi GPD.

In entrambi i casi e' previsto l'invio della posizione debitoria agli archivi centralizzati. L'invio della posizione verso ACA e' automatico e contestuale al caricamento della posizione su GovPay. L'invio della posizione verso GPD esclude l'invio automatico verso ACA.

Per richiedere l'invio verso GPD e' necessario indicarlo esplicitamente al momento del caricamento di una pendenza.

Per la gestione degli invii e' necessario aggiungere alla tabella versamenti la colonna inviatoGPD di tipo boolean che indica se la pendenza e' stato spedito all'ACA o al GPD. Il valore da impostare per tutte le pendenze gia' presenti in archivio e' false (invio ACA). Al momento del caricamento di una pendenza viene assegnato il valore false a meno che non venga richiesto l'invio GPD. Aggiungere la colonna di tipo datetime dataInvioGPD che si utilizza per decidere quali pendenze inviare. Le pendenze per cui dataUltimoAggiornamento > dataInvioGPD dovranno essere inviate.

[pintorig]

@nardil Revisione 02/02/2024

E' stato deciso al momento di non implementare il supporto al GPD.

Le modifiche da realizzare nel progetto GovPay sono le seguenti:

• Aggiungere alla tabella versamenti le colonne data_ultima_modifica_aca e data_ultima_comunicazione_aca
• La colonna data_ultima_modifica_aca contiene l'informazione di quando e' stata effettuata l'ultima modifica ai dati da spedire verso ACA. Il valore presente in questa colonna verra' modificato quando in fase di aggiornamento della pendenza si verifica una delle seguenti situazioni: annullamento o modifica dell'importo o della data scadenza.
• La colonna data_ultima_comunicazione_aca contiene l'informazione relativa all'ultima spedizione effettuata con successo verso ACA
• Realizzare la vista v_versamenti_aca che contiene tutti i dati necessari per la creazione dei messaggi da spedire verso ACA raccogliendo le pendenze da spedire v.stato = 'NON_ESEGUITO' and v.data_ultima_comunicazione_aca < v.data_ultima_modifica_aca
• La gestione delle spedizioni verso ACA sara' fatta attraverso il batch govpay-aca-batch.

[nardil]

Allineare il batch di alimentazione ACA alle SANP 3.7.0.

L'ultima versione prevede di fornire all'ACA anche un conto di accredito su cui riversare i fondi riscossi. Questo implica che in caso di multi-beneficiario ne vada individuato uno tra quelli indicati. Come policy interna, verra' selezionato il primo iban tra quelli dell'EC.

OpenPoint: In caso tutti gli importi siano attestati a beneficiari diversi dall'EC, quale conto scegliere?

[pintorig]

Allineare il batch di alimentazione ACA alle SANP 3.9.0 come richiesto dalla issue 10. Verificare l'aggiornamento e se non sono richieste modifiche in GovPay chiudere la issue