API VERSIONE GA 2.1
Pagamenti multipli, Supporto F24, Modalità di integrazione asincrona con pagoPA
Nuove funzionalità GA 2.1
Pagamenti multipli: possibilità di collegare più modelli di pagamento alla notifica (pagamenti alternativi o rateali).
Supporto modello di pagamento F24: possibilità di collegare alla notifica pagamenti gestiti con modelli di pagamento F24 con invio dei metadati e gestione delle spese di notifica.
Modalità di integrazione asincrona con pagoPA: integrazione con il modulo Gestione delle Posizioni Debitorie (GPD) di pagoPA con aggiornamento automatico dei costi di notifica. Modalità che semplifica l'integrazione, sollevando l'ente creditore dall'implementazione della chiamata all'API notificationCost e dell'aggiornamento dell'importo; rendendo il pagamento meno soggetto a errori di comunicazione.
File di definizione OpenAPI: https://raw.githubusercontent.com/pagopa/pn-delivery/v2.2.0-RC.1/docs/openapi/api-external-b2b-pa-bundle.yaml
Le modifiche alle API per supportare queste funzionalità
Nuova operation "Richiesta invio notifiche" sendNewNotificationV21
POST /delivery/v2.1/requests
Pagamenti multipli
Ad ogni destinatario recipients
è possibile associare N pagamenti nell'array payments
.
ATTENZIONE: il payload dei recipients
è cambiato e prevede un array payments
di pagamenti al posto del precedente payment
, quindi non utilizzate lo stesso payload della versione precedente altrimenti le notifiche saranno create senza pagamenti.
Gli elementi dell'arrayNotificationPaymentItem
possono essere di tipo pagoPa
o f24
.
Pagamento pagoPA
Per il pagamento di tipo pagoPA deve essere valorizzato l'elemento pagoPa il formato rimane identico ad eccezione del campo applyCost
.
Se la notifica prevede l'attualizzazione dell'importo (notificationFeePolicy=DELIVERY_MODE
) deve essere indicato su quale dei pagamenti devono essere riportati i costi della notifica indicando applyCost=true
.
In caso di integrazione asincrona con pagoPA (pagoPaIntMode =ASYNC
) il campo deve essere true
per almeno numero avviso per destinatario se e NotificationFeePolicy=DELIVERY_MODE
NOTA: Eliminato il campo noticeCodeAlternative
che diventa uno dei pagamenti della notifica di tipo pagoPA.
Pagamento F24
Per il pagamento di tipo F24 deve essere valorizzato l'elemento f24:
Il campo title
deve riportare una descrizione visibile al destinatario per capire quale modello F24 vuole visualizzare. Il campo non deve riportare nessun dato personale come nominativo, codice fiscale o altri dati protetti per privacy policy.
Il campo applyCost
di tipo boolean per indicare che devono essere addebitate le spese di notifica sulla modello F24 (si veda dettaglio). Una sola riga del modello F24 dovrà essere marcata con applyCost=true
(tutte le altre devono riportareapplyCost=false
) e dovrà riportare la cifra di costo di notifica a compensazione della PA mittente.
L'elemento metadataAttachment
deve riportare i riferimenti al file json dei metadati relativi ai dati che saranno riportati nel modello F24.
Metadati F24
Per poter generare dinamicamente il modello F24 con l'importo che comprenda i costi della notifica nel modello F24, SEND richiede l'invio di un file in formato JSON contenente i dati del modello con indicazione di una riga nella quale andare ad aggiungere i costi della notifica (campo applyCost
).
Tale riga sarà già valorizzata con un importo che comprende il costo della notifica a copertura per la PA mittente (es: 100 eurocent).
Se la notifica contiene N destinatari e M pagamenti F24 dovranno essere caricati N x M file di metadati per ogni modello.
Come si invia il file dei metadati F24
Il file dei metadati del modello F24 è caricato sulla piattaforma con le stesse modalità degli altri documenti allegati alla notifica, tramite la chiamata all'api newNotification/presignedUploadRequest
per ottenere gli url per il caricamento dei file.
Se la chiamata è andata a buon fine la response ci restituirà una URL e un secret che ci serviranno per eseguire l'upload dei file allegati, compreso il json dei metadati.
Una volta ricevuto l'URL per il caricamento del documento su S3 bisognerà impostare la chiamata da effettuare avendo cura di inserire negli headers:
Content-type: application/json
il valore di
x-amz-meta-secret
con ciò che ci ha restituito la chiamata precedenteil valore di
x-amz-checksum-sha256
con lo sha del file json contenente i metadati
Ecco un esempio della chiamata:
Allo stesso modo degli altri allegati la chiamata di upload restituirà l'header x-amz-version-id che dovrà essere utilizzato durante l'inserimento della notifica, nel campo ref.versionToken in corrispondenza del relativo pagamento F24.
Le tipologie di F24 che si possono caricare sono le seguenti:
f24Standard
: F24 Ordinario
f24Simplified
: F24 Semplificato
f24Excise
: Accise
f24Elid
: F24 Elementi Identificativi
Lo schema di validazione per il file json dei metadata è pubblicato al seguente url:
Indicazione della modalità di integrazione con pagoPA
Nuovo elemento pagoPaIntMode
per indicare la modalità di integrazione con pagoPA dei numeri avviso pagoPA contenuti nella notifica.
NOTA: tutti i numeri avviso contenuti nella notifica devono avere la stessa modalità di integrazione.
ASYNC: modalità asincrona
SYNC (default): modalità sincrona
Aggiunto campo paFee
di tipo integer per indicare l'ammontare (espresso in eurocent) a copertura dei costi sostenuti dalla PA mittente in base a quanto previsto dal Decreto 30 maggio 2022 «Individuazione dei costi e dei criteri e modalità di ripartizione e ripetizione delle spese di notifica degli atti tramite la piattaforma di cui all'art. 26, comma 14 del decreto-legge 16 luglio 2022, n. 76». Il campo paFee
è necessario per imputare il valore corretto nel calcolo del costo della notifica per il modello di pagamento F24 e per la modalità d'integrazione asincrona con pagoPA.
Altre modifiche
Aggiunto campo opzionale paymentExpirationDate
di tipo date con formato YYYY-MM-DD, serve per indicare la data di scadenza della pagamento della notifica (nel caso questo dato sia determinabile dalla PA mittente). Questo dato avrà il solo scopo informativo per l'utente, non ha alcuna implicazione sul workflow della notifica o del pagamento.