Cosa sono i flussi di rendicontazione e come usarli correttamente

Un Flusso di Rendicontazione di PagoPA è il documento digitale, inviato dai Prestatori di Servizi di Pagamento (PSP), che contiene il dettaglio dei pagamenti effettuati attraverso il sistema pagoPA in un determinato giorno e che devono essere riversati su uno specifico conto corrente dell’Ente Creditore (EC). 

All’interno del flusso sono riportate informazioni di riepilogo come il numero totale dei pagamenti e l’importo complessivo, ed informazioni di dettaglio come l’Identificativo Univoco Versamento (IUV), Identificativo Univoco di Riscossione (IUR) e la data di pagamento. Se durante le operazioni di riconciliazione dovessero emergere dei disallineamenti (come ad esempio tra il contenuto del flusso, i dati delle ricevute telematiche, e l’importo del bonifico), l’Ente Creditore potrà chiedere una correzione del flusso e/o un’operazione di riversamento. 

I Flussi di Rendicontazione sono importanti per i seguenti 3 motivi:

• Trasparenza e Tracciabilità: consentono la tracciabilità di tutti i pagamenti e facilitano la verificabilità contabile.
• Sicurezza: assicurano il tracciamento di tutti i pagamenti, compresi quelli per i quali l’Ente potrebbe non disporre della relativa ricevuta.
• Efficienza: consentono l’individuazione di quanto l’Ente ha incassato rispetto a quanto emesso, riducendo così gli errori.

⚠ Importante evidenziare che l'abilitazione al servizio per la gestione dei Flussi di Rendicontazione sulla componente Gestione Posizioni Debitorie (GPD) non avviene in modo automatico. Dopo aver staccato le Subscription dal portale, gli EC comunicano, tramite Ticket ad Operations, che intendono attivare i Flussi di Rendicontazione sulla componente GPD e gli Enti da attivare. L’abilitazione si conclude quando il Team Operations chiude il ticket lavorato.

Attualmente PagoPA mette a disposizione delle API in formato SOAP che in formato REST. Qui di seguito prenderemo in considerazione entrambi i formati.

In questa sezione vengono descritte le API SOAP disponibili per i PSP per la Gestione dei Flussi di Rendicontazione (FdR).

⚠Le API SOAP stanno per essere deprecate

I PSP hanno a disposizione una modalità per rendere i Flussi di Rendicontazione agli EC tramite chiamate alla funzione SOAP nodoInviaFlussoRendicontazione. In questo scenario l’EC potrà recuperare le informazioni solamente via chiamate SOAP.

Gestione dei Flussi di Rendicontazione

Base UAT URL: https://api.uat.platform.pagopa.it/nodo-auth/node-for-psp/v1

Qui di seguito è possibile trovare la body-request della precedente chiamata SOAP:

identificativoIntermediarioPSP:  l'intermediario/broker può coincidere con il PSP stesso.

Tutti i campi sono obbligatori

Nel caso di risposta positiva (HTTP 200) il campo esito dentro la risposta nodoInviaFlussoRendicontazioneRisposta potrà prendere i valori OK (operazione eseguita con successo) oppure KO (operazione terminata con errore).
In caso di risposta KO nel campo esito verrà restituito il faultBean configurato con tutte le informazioni relative al problema riscontrato:

In questa sezione vengono descritte le API SOAP disponibili per gli EC per la Gestione dei Flussi di Rendicontazione (FdR).

⚠Le API SOAP sono in via di deprecazione.

PagoPA mette a disposizione 2 api SOAP per gestire i Flussi di Rendicontazione:

• nodoChiediElencoFlussiRendicontazione
• nodoChiediFlussoRendicontazione

entrambe le API devono essere chiamate in POST e le informazioni necessarie per identificare i dati richiesti. Le 2 API per poter funzionare richiedono le seguenti informazioni mandatorie (oltre a quelle specifiche):

• identificativoIntermediarioPA
• password
• identificativoStazioneIntermediarioPA (String): identificativo della stazione dell'EC nel sistema pagoPa.

Gestione dei Flussi di Rendicontazione

Base UAT URL: https://api.uat.platform.pagopa.it/nodo-auth/node-for-pa/v1

Qui di seguito è possibile trovare la body-request della precedente chiamata SOAP (i campi sottolineati sono mandatori):

Nel caso di risposta positiva (HTTP 200) il campo esito dentro la risposta nodoChiediFlussoRendicontazioneRisposta potrà prendere i valori OK (operazione eseguita con successo) oppure KO (operazione terminata con errore).
In caso di risposta KO nel campo esito verrà restituito il faultBean già analizzato.

In caso di risposta OK verrà ritornato un elenco di flussi di rendicontazione e ogni flusso di rencircontazione sarà identificato da:

• identificativoFlusso
• dataOraFlusso

Base UAT URL: https://api.uat.platform.pagopa.it/nodo-auth/node-for-pa/v1

Qui di seguito è possibile trovare la body-request della precedente chiamata SOAP (i campi sottolineati sono mandatori):

Nel caso di risposta positiva (HTTP 200) il campo esito dentro la risposta nodoChiediFlussoRendicontazioneRisposta potrà prendere i valori OK (operazione eseguita con successo) oppure KO (operazione terminata con errore).
In caso di risposta KO nel campo esito verrà restituito il faultBean già analizzato.

In caso di risposta OK verrà ritornato lo specifico flusso di rendicontazione in formato base64 (xmlRendicontazione).

PagoPA mette a disposizione degli EC e degli PSP due nuove primitive per il download e l'upload dei Flussi di Rendicontazione. Questi nuovi servizi mirano a ottimizzare il flusso logico attuale, gestendo efficacemente tutte le fasi di gestione dei FdR, anche per quelli di grandi dimensioni. EC e PSP potranno adeguare le loro chiamate alle nuove primitive per una gestione efficiente dei FdR. Per utilizzare le nuove API, sarà necessaria una sottoscrizione al nuovo prodotto, con ulteriori informazioni disponibili nella guida alla Connettività. Sono disponibili due nuovi prodotti: FDR - Flussi di rendicontazione [ORG] per gli EC e FDR - Flussi di rendicontazione [PSP] per i PSP.

⚠ Rispetto alle API SOAP, le nuove API REST non introducono particolari cambiamenti nel flusso generale. Il principale aggiornamento è la costruzione progressiva dell'elenco dei pagamenti tramite una chiamata dedicata.

⚠ È inoltre rilevante sottolineare che le subscription key e le relative abilitazioni sono differenziate in base all'ambiente di utilizzo, che può essere UAT (Ambiente di Test/Collaudo) o PROD (Ambiente di Produzione). Questa distinzione assicura che le operazioni di test e quelle effettivamente operative siano ben separate, permettendo agli enti e agli intermediari di testare le loro implementazioni in un ambiente controllato prima di passare alla produzione.

Base UAT URL: https://api.uat.platform.pagopa.it/fdr-psp/service/v1

1. chiamare l’operation /psps/{pspId}/fdrs/{fdr} in POST per creare un FdR
   1. parametro pspId: identificativo del PSP
   2. parametro fdr: identificativo del flusso nel formato <data regolamento><istituto mittente>”-“<flusso> (e.g., 2021-11-21ABI00000-AABB648200001295)

   3. request body: contiene le informazioni specifiche del flusso di rendicontazione in formato json. Qui di seguito è riportato un esempio:

      {
        "fdr": "2021-11-21ABI00000-AABB648200001295",
        "fdrDate": "2023-04-05T09:21:37.8100000+00:00",
        "sender": {
          "type": "LEGAL_PERSON",
          "id": "SELBIT2B",
          "pspId": "60000000001",
          "pspName": "Bank",
          "pspBrokerId": "70000000001",
          "channelId": "80000000001",
          "password": "1234567890"
        },
        "receiver": {
          "id": "APPBIT2B",
          "organizationId": "20000000001",
          "organizationName": "Comune di xyz"
        },
        "regulation": "SEPA - Bonifico xzy",
        "regulationDate": "2023-04-03T12:00:30.9000000+00:00",
        "bicCodePouringBank": "UNCRITMMXXX",
        "totPayments": 1,
        "sumPayments": 0.01
      }

2. chiamare 1 o più volte l’operation /psps/{pspId}/fdrs/{fdr}/payments/add in PUT per aggiungere uno o più pagamenti:
   1. parametro pspId: identificativo del PSP (deve corrispondere all’identificativo PSP usato per creare il flusso)
   2. parametro fdr: identificativo del flusso (deve corrispondere all’identificativo FdR usato per creare il flusso)

   3. request body: contiene le informazioni specifiche del pagamento che si sta aggiungendo allo FdR in formato json. Qui di seguito è riportato un esempio:

      ⚠ Con ogni chiamata a questa operation si possono aggiungere fino a 1000 pagamenti

      {
        "payments": [
          {
            "index": 1,
            "iuv": "abcdefg",
            "iur": "abcdefg",
            "idTransfer": 1,
            "pay": 0.01,
            "payStatus": "EXECUTED",
            "payDate": "2023-02-03T12:00:30.9000000+00:00"
          }
        ]
      }

3. finito l’inserimento di tutti i pagamenti all’interno della FdR, bisogna chiamare l’operation /psps/{pspId}/fdrs/{fdr}/publish in POST al fine di rendere disponibile all’EC la Fdr
   1. parametro pspId: identificativo del PSP (deve corrispondere all’identificativo PSP usato per creare il flusso)
   2. parametro fdr: identificativo del flusso (deve corrispondere all’identificativo FdR usato per creare il flusso)

Base UAT URL: https://api.uat.platform.pagopa.it/fdr-org/service/v1

1. chiamare l’operation /organizations/{organizationId}/fdrs in GET per recuperare l’elenco degli FdR visibili per l’EC. Questa chiamata è paginata: questo significa che se il numero di FdR che devono essere ritornate è molto alto saranno necessarie più chiamate per recuperarli tutti. Per questa ragione (gestione della paginazione) e per poter filtrare le FdR per PSP che le ha inviate ci sono questi parametri opzionali (query parameter) che permettono di filtrare il recupero dei dati:
   1. organizationId: identificativo dell’EC
   2. page: il numero di pagina che si vuole recuperare

   3. size: il numero di FdR massimo per ogni “pagina” recuperata

      page e size permettono di gestire il recupero paginato, quindi, ad esempio, con la seguente chiamata /organizations/{organizationId}/fdrs?page=3&size=100 (ammesso che esistano) si recuperano gli FdR che vanno dal 201° al 300°. 

   4. pspId: identificativo del PSP

   5. publishedGt: data da cui recuperare le FdR (verranno ignorate tutte le FdR pubblicate prima della data scelta.

      pspId e publishedGt, invece, permettono di essere più selettivi sugli FdR da recuperare; ad esempio, con la chiamata /organizations/{organizationId}/fdrs?pspId={000004}&publishedGt=2024-05-15T15:00:00+02:00 si recuperano tutti gli FdR emessi dal PSP con id 000004 e pubblicati a partire dal 15 maggio 2024 dopo le ore 15 UTC+2.

      Naturalmente i 4 parametri opzionali si possono utilizzare a piacere per meglio gestire il recupero delle FdR.

      Un esempio di risposta del servizio è riportato qui di seguito

      {
        "metadata": {
          "pageSize": 25,
          "pageNumber": 1,
          "totPage": 1
        },
        "count": 1,
        "data": [
          {
            "fdr": "AAABBB",
            "pspId": "1",
            "revision": 1,
            "published": "2023-04-03T12:00:30.9000000+00:00"
          }
        ]
      }

      dove oltre alle informazioni specifiche del FdR (che serviranno poi per recuperare i pagamenti), nel campo metadata possiamo trovare tutte le informazioni che ci servono per la gestione della paginazione dei risultati:

      1. totPage: il numero tatale di pagine
      2. pageSize: il numero massimo di elementi presente per pagina
      3. pageNumber: la pagina corrente

      Quindi ad esempio totPage = 10 e pageSize = 25 vuol dire che ci sono tra 75 e 100 FdR disponibili

2. chiamare l’operation /organizations/{organizationId}/fdrs/{fdr}/revisions/{revision}/psps/{pspId} in GET per recuperare tutte le informazioni relative alla FdR specifica:

   1. organizationId: identificativo dell’EC
   2. fdr: l’identificativo della FdR recuperata con la chiamata precedente
   3. revision: il numero di revisione anch’essa recuperata con la chiamata precedente
   4. pspId: l’identificativo del PSP anch’esso recuperato con la chiamata precedente

   Una tipica risposta positiva è riportata qui di seguito:

   {
     "status": "CREATED",
     "revision": 4,
     "created": "2023-04-03T12:00:30.9000000+00:00",
     "updated": "2023-04-03T12:00:30.9000000+00:00",
     "fdr": "2016-08-16pspTest-1178",
     "fdrDate": "2023-04-05T09:21:37.8100000+00:00",
     "regulation": "SEPA - Bonifico xzy",
     "regulationDate": "2023-04-03T12:00:30.9000000+00:00",
     "bicCodePouringBank": "UNCRITMMXXX",
     "sender": {
       "type": "LEGAL_PERSON",
       "id": "SELBIT2B",
       "pspId": "60000000001",
       "pspName": "Bank",
       "pspBrokerId": "70000000001",
       "channelId": "80000000001",
       "password": "1234567890"
     },
     "receiver": {
       "id": "APPBIT2B",
       "organizationId": "20000000001",
       "organizationName": "Comune di xyz"
     },
     "published": "2023-04-03T12:00:30.9000000+00:00",
     "computedTotPayments": 100,
     "computedSumPayments": 100.9,
     "totPayments": 100,
     "sumPayments": 100.9
   }

3. Una volta recuperate tutte le informazioni sul FdR si può procedere a recuperare i pagamenti che lo compongono con l’operation /organizations/{organizationId}/fdrs/{fdr}/revisions/{revision}/psps/{pspId}/payments in GET

   1. organizationId: identificativo dell’EC
   2. fdr: l’identificativo della FdR recuperata con la chiamata precedente
   3. revision: il numero di revisione anch’essa recuperata con la chiamata precedente
   4. pspId: l’identificativo del PSP anch’esso recuperato con la chiamata precedente

   Anche questa API è paginata attraverso i seguenti parametri opzionali (query parameter):

   1. page: il numero di pagina che si vuole recuperare

   2. size: il numero di FdR massimo per ogni “pagina” recuperata

      Una tipica risposta positiva è riportata qui di seguito:

      {
        "metadata": {
          "pageSize": 25,
          "pageNumber": 1,
          "totPage": 3
        },
        "count": 100,
        "data": [
          {
            "index": 1,
            "iuv": "abcdefg",
            "iur": "abcdefg",
            "idTransfer": 1,
            "pay": 0.01,
            "payStatus": "EXECUTED",
            "payDate": "2023-02-03T12:00:30.9000000+00:00"
          }
        ]
      }

      Il numero massimo di pagamenti che possono essere ritornati per ogni invocazione sono 1000. Come per l’operation  /organizations/{organizationId}/fdrs nella risposta è presente un campo metadata dove possiamo trovare tutte le informazioni che ci servono per la gestione della paginazione dei risultati.

Gestione degli FdR

Qui di seguito vengono riportate le attività principali che riguardano il flusso di vita di un FdR: 

• Creazione e Invio: Quando un utente, il giorno D, effettua un pagamento il PSP che ha preso in carico la transazione, una volta confermato l'addebito, ha l’obbligo di riversare, a D+1, l’importo del pagamento. A D+2, il riversamento delle somme deve essere seguito dall’invio del flusso di rendicontazione.
• Confronto e Verifica: Gli Enti Creditori utilizzano il Flusso di Rendicontazione per verificare quali pagamenti sono stati effettuati e che gli importi contenuti nel flusso corrispondano a quanto ricevuto con il riversamento bancario. 

⚠ Il Flusso di Rendicontazione include tutte le transazioni di pagamento effettuate, specificando l'importo pagato, il riferimento del pagamento, e altre informazioni rilevanti.

In caso di errori, il PSP può correggere il flusso e inviarlo nuovamente al nodo, avendo cura di usare lo stesso identificativo del Flusso (identificativoFlusso) e il campo dataOraFlusso aggiornato. 

Un flusso di sovrascrittura deve essere inviato, al massimo, entro le 24 ore del quarto giorno lavorativo successivo alla ricezione dell'ordine di pagamento (D+4).

Infatti, Per garantire una gestione adeguata, l'EC deve controllare e, se necessario, gestire il contenuto associato a ciascun identificativoFlusso inviato entro il quarto giorno lavorativo (D+4) successivo alla ricezione dell'ordine di pagamento., come da seguente schema

⚠ Non deve mai accadere che invii diversi di uno stesso flusso contengano la stessa dataOraFlusso. 

Nella sezione seguente verranno dettagliate alcune domande riguardanti i Flussi di Rendicontazione:

• Quali Api Key bisogna utilizzare: Sempre l’ultimo valore della sottoscrizione che il soggetto direttamente connesso ha provveduto a generare attraverso il portale SelfCare.
• Cosa è il parametro idTransfer: Nella primitiva Add payments to fdr , il parametro idTransfer è un valore che fa riferimento all’indice dati singolo pagamento;
• Cosa è il parametro Index: Nella primitiva Add payments to fdr , il parametro Index è un valore progressivo, non necessariamente inizializzato a 1, che identifica in maniera univoca la posizione del pagamento all’interno del flusso.  
• A che cosa si riferisce il valore 1000: Nella primitiva Add payments to fdr , per quanto riguarda il valore 1000 dell’indice posizionale, esso rappresenta il numero massimo di righe che possono essere scritte all'interno del flusso, per ogni chiamata.
• Le pubbliche amministrazioni possono recuperare un flusso tramite FTP?: Non è previsto lo scambio di file tramite FTP perché non è più necessario in quanto con i nuovi Flussi di Rendicontazione, dove si è andato a suddividere il flusso in piccoli pezzi, va a sistemare la problematica dei flussi di rendicontazione di grande dimensione. 
• Cosa succede se per errore il PSP carica nuovamente lo stesso pacchetto: Quando un PSP invia una richiesta multipla riceve un messaggio di Errore. In base al messaggio di errore si può capire se il pacchetto è già stato aggiunto oppure se il pacchetto viene rifiutato poiché c’è un errore nel contenuto della richiesta nella fase di sottomissione del pacchetto.  
• Si possono effettuare inserimenti paralleli dei pacchetti di un flusso?: Un PSP può effettuare inserimenti paralleli di pacchetti per poter migliorare gli algoritmi e potrà, qualora un invio di uno o più pacchetti possa andare male, rinviare nuovamente i pacchetti.
• Quanti pacchetti possono esserci in un file: Partendo dal fatto che non c’è un limite massimo di pacchetti che compongono il flusso di rendicontazione. Il limite viene impostato soltanto sul numero massimo di pagamenti che possono essere scritte all'interno del flusso, per ogni chiamata.