Come integrarsi e gestire le API in modalità asincrona

Questo tutorial fornisce istruzioni sull'integrazione e la gestione delle API in modalità asincrona per la piattaforma pagoPA.

Il tutorial è rivolto a Partner Tecnologici, Intermediari Tecnologici e Enti Creditori per la gestione tecnica delle posizioni debitorie e delle richieste di pagamento.

L’erogazione del servizio delle API asincrone è gestito mediante l'integrazione con un set specifico di API. 

Questo servizio mira a fornire una gestione tecnica delle posizioni debitorie ai Partner Tecnologici, agli Intermediari Tecnologici e, ove necessario, direttamente agli Enti Creditori (EC). 

La gestione comprende sia le operazioni di creazione, aggiornamento e cancellazione delle posizioni debitorie create dai Partner Tecnologici o dagli Enti Creditore su uno specifico layer tecnico della piattaforma pagoPA, che copre anche richieste di pagamenti spontanei, come la gestione della loro pagabilità tramite il Nodo dei Pagamenti. 

In aggiunta, il servizio aggiorna lo stato delle posizioni debitorie dopo l'interazione con la piattaforma pagoPA per l'esecuzione di pagamenti.

Adottando il servizio di integrazione Asincrona, gli EC possono semplificare significativamente l'infrastruttura tecnologica necessaria per interagire con la piattaforma pagoPA, in relazione alla gestione delle loro posizioni debitorie. 

I vantaggi principali sono:

• Rispetto delle Linee Guida: il servizio è sempre aggiornato alle ultime funzionalità della piattaforma pagoPA;
• Rispetto delle SLA: il servizio ha dei meccanismi di scalabilità basati sul carico;
• Continuità operativa: assicurare le misure di continuità operativa in conformità con gli obblighi indicati dalla Banca d'Italia (ex art. 146 T.U.B.).

Inoltre, il servizio apre la porta a nuovi casi d'uso per gli aderenti, come i servizi di pagamento spontaneo e la gestione integrata degli avvisi di pagamento. 

⚠ L’EC mantiene la responsabilità per l'accuratezza dei dati relativi alle posizioni debitorie che vengono trasmessi a PagoPA S.p.A. per l'utilizzo di questo servizio.

Nella sezione seguente verranno dettagliati i seguenti aspetti:

• Trattamento di Dati Personali 
• Passaggio alla Modalità Asincrona di un Ente Creditore
• API Disponibili per un Ente Creditore
• Ricevute di Pagamento

In relazione al trattamento dei dati personali, l'EC funge da titolare del trattamento dei dati personali associati alla posizione debitoria. A meno che non venga diversamente specificato attraverso una comunicazione scritta, l'EC accetta l'Accordo sul trattamento dei dati personali da parte del responsabile del trattamento, ai sensi dell'articolo 28 del Regolamento (UE) 2016/679, designando di conseguenza PagoPA S.p.A. come Responsabile del Trattamento.

Se l'EC si affida a un Intermediario Tecnologico e/o a un Partner Tecnologico per il trattamento dei dati personali legati alla posizione debitoria, sarà quest'ultimo a sottoscrivere l'accordo menzionato, a meno che non venga fornita un'indicazione contraria tramite documento scritto. 

In questo scenario, PagoPA S.p.A. assumerà il ruolo di sub-responsabile del trattamento per conto dell'EC, che deve aver concesso un'autorizzazione generale per l'uso di altri responsabili del trattamento.

Nel caso in cui l'EC decida di non accettare l'Accordo sul Trattamento dei Dati e/o eventuali modifiche o aggiornamenti successivi, la sua adesione al servizio verrà sospesa fino a quando il trattamento dei dati personali non sarà regolamentato da un altro accordo, in conformità con l'articolo 28 del Regolamento (UE) 2016/679.

L'accordo è disponibile al seguente link: DPA_PagoPA S.p.A. vs EC_posizioni debitorie (gitbook.com)

Per passare alla modalità Asincrona, un EC deve seguire i seguenti passi:

1. Con riferimento alla documentazione SANP Implementare le API asincrone 
2. Accedere al portale Self Care e richiedere la subscription key (API key) per la connettività asincrona. Questo passo è fondamentale perché tutte le interazioni con pagoPA avvengono attraverso chiamate REST (REpresentational State Transfer) e per consentire al Nodo di accettare queste chiamate, l'EC deve inserire nello header HTTP delle chiamate la subscription key specifica per il tipo di servizi che intende utilizzare. In assenza di questa chiave, il Nodo non procederà con l'accettazione della chiamata restituendo un errore HTTP 401 (Unauthorized). La sottoscrizione consente all'EC di gestire le posizioni debitorie, inclusi la creazione, pubblicazione, aggiornamento, invalidazione e cancellazione.
3. Sempre dal portale SelfCare configurare la Stazione di collaudo che servirà l’integrazione asincrona: la configurazione non è diversa, se non per i contenuti, da una normale stazione.
4. Una volta che la stazione è stata verificata e autorizzata dal team di Service Management, si è pronti per iniziare la fase di test
5. L’EC deve configurare le sottoscrizioni per i Flussi di Rendicontazione e per le Receipt (paSendRTV1/V2). Questo passaggio assicura che l'EC possa ricevere correttamente i dati relativi ai pagamenti e alle conferme di pagamento.
6. Dopo aver configurato tutte le sottoscrizioni e implementati i processi proprio lato utilizzando le API REST messe a disposizione da pagoPA, è necessario che l'EC proceda con i test delle funzionalità principali seguendo il piano di test fornito da pagoPA:
   1. creazione della posizione debitoria;
   2. pubblicazione della stessa;
   3. il suo aggiornamento;
   4. la sua cancellazione;
   5. caricamenti massivi (facoltativo).
      Questi test sono fondamentali per verificare che l'integrazione con il sistema pagoPA funzioni correttamente e che le operazioni asincrone siano gestite senza problemi.
7. Appena terminati con successo i test, fornire le evidenze a PagoPA attraverso un piano di test condiviso.
8. Ottenuto il semaforo verde da PagoPa per il passaggio in produzione, si procede a un penny test nell’ambiente di produzione
9. Dopo aver pubblicato la posizione debitoria, l'EC può procedere con il tentativo di innescare il pagamento della posizione debitoria attraverso l'inserimento di tutti i dati necessari in Checkout e verificando l'avvenuta corretta sequenza di chiamate verso pagoPA.
10. Se il pagamento viene eseguito con successo, l'EC potrà acquisire la ricevuta di pagamento. Questo passaggio è fondamentale per confermare l'avvenuto pagamento e per mantenere un record contabile e amministrativo dell'operazione.

In questa sezione vengono descritte le API REST disponibili per gli EC per la Gestione delle Posizioni Debitorie (GPD), delle Ricevute di Pagamento e dei Flussi di Rendicontazione.

⚠ È importante evidenziare che tutte le operazioni disponibili attraverso queste API sono segregate per codice fiscale dell'ente creditore (organizationfiscalcode). Questo significa che ogni operazione è specifica e univoca per ciascun ente creditore, garantendo così una gestione sicura e personalizzata delle informazioni.

Nel contesto dell'intermediazione, gli intermediari hanno la possibilità di associare alla loro subscription key da uno a un numero indefinito di codici fiscali degli enti intermediati. Questo permette agli intermediari di utilizzare un'unica subscription key per effettuare chiamate API per conto di tutti gli enti che rappresentano. Le richieste per tali abilitazioni devono essere inoltrate a PagoPA sia al momento della creazione della subscription key che successivamente.

⚠ È 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 URL: https://developer.pagopa.it/pago-pa/api/gestione-posizioni-debitorie#/

⚠Base URL: https://developer.pagopa.it/pago-pa/api/gpd-recupero-receipt#/pago-pa/api/

La gestione delle ricevute di pagamento può essere effettuata attraverso due metodi complementari:

• Modalità Asincrona (Pull): in questa modalità, l'EC utilizza chiamate asincrone, come precedentemente descritto, per recuperare le Ricevute Telematiche (RT) di interesse. Questo implica che l'Ente deve organizzare un processo di scheduling per controllare periodicamente la disponibilità delle ricevute e, se queste non sono ancora pronte, pianificare tentativi successivi;
• Modalità Sincrona (Push): questa modalità si avvale di una Stazione di Broadcast associata all'EC. Per ogni pagamento completato con successo, il Nodo dei Pagamenti invierà una notifica a paSendRT a tale stazione, permettendo all’EC di essere informato in tempo reale del completamento del pagamento.

Nonostante entrambe le modalità siano supportate, la modalità Asincrona richiede l'implementazione di un processo di verifica e tentativi ripetuti per il recupero delle ricevute, risultando in un approccio che può rivelarsi oneroso sia per gli Enti che per pagoPA. Di conseguenza, quando è possibile, si raccomanda di preferire l'approccio Sincrono per il recupero delle ricevute, in quanto permette un flusso di lavoro più efficiente e meno dispendioso.