Ruby Wrapper per pagoPA SOAP API basato sulla gemma Savon

Project	PagoPa Soap Ruby
Gem name	pagopa-soap
License	BSD 3
Version
Continuous integration
Test coverage
Credits	Contributors

All'interno del Gemfile del progetto inserire questa righa:

gem 'pagopa-soap'

Quindi eseguire il comando:

$ bundle

In alternativa è possibile installare la gemma globalbmente lanciando il comando:

$ gem install pagopa-soap

TODO: Write usage instructions here Inizializzare il wrapper e generare le classi dinamiche in base al WSDL:

PagoPA::SOAP.build

Dopo aver lanciato la build, il sistema genera le nuove classi con il namespace PagoPA. Ecco la lista delle nuove classi disponibili:

PagoPA::NodoChiediStatoRpt
PagoPA::NodoChiediListaPendentiRpt
PagoPA::NodoInviaRpt
PagoPA::NodoInviaCarrelloRpt
PagoPA::NodoChiediCopiaRt
PagoPA::NodoChiediInformativaPsp
PagoPA::NodoPaChiediInformativaPa
PagoPA::NodoChiediElencoQuadraturePa
PagoPA::NodoChiediQuadraturaPa
PagoPA::NodoChiediElencoFlussiRendicontazione
PagoPA::NodoChiediFlussoRendicontazione
PagoPA::NodoInviaRichiestaStorno
PagoPA::NodoInviaRispostaRevoca
PagoPA::NodoChiediSceltaWisp
PagoPA::NodoInviaAvvisoDigitale

Ogni classe comprende tre sottoclassi per poter costruire la request, inoltrarla al sistema tramite il client ed ottenere la response corrispondente. Per pagoPA è possibile specificare WSDL, endpoint e namespace in un blocco di configurazioni:

# config/initializers/pagopa_soap.rb
# This is your pagoPA Wrapper setting.
PagoPA::SOAP::Configurable.configure do |config|
  config.namespace = "PagoPA"
  config.wsdl_base = "WSDL with webservice specification"
  config.wsdl_notify = "WSDL with webservice for PUSH notification"
  config.endpoint_base = "https://host-nodo-spc/webservices/"
  config.endpoint_notify = "https://host-nodo-spc-push/webservices/"
end

The gem is available as open source under the terms of the BSD 3-Clause License.

1. Premessa
2. Analisi Attuativa
3. Esempi di connessione
4. Requisiti del sistema EC
5. Implementazioni Future
6. Ipotesi di integrazione 6.1. Wrapper API Ruby 6.2. Engine Rack
7. Appendice

Secondo le linee guida emesse dall’Agenzia per l’Italia Digitale il NODO dei pagamenti SPC (pagoPA) vuole essere il sistema centralizzato di controllo e interoperabilità tra la Pubblica Amministrazione ed i Cittadini.

Il sistema comunica tramite Web Service SOAP con un Header di autenticazione e si aspetta un canale TLS con certificati x.509 v3 e che l’EC (Ente Creditore) che effettua le chiamate sia inserito in una white list di IP verificati.

Attraverso l’interfaccia WISP (Wizard interattivo di scelta dei PSP - Prestatori di Pagamento) viene demandato al sistema pagoPA l’attuazione delle linee guida in merito ai sistemi di pagamento e alla visualizzazione dei costi aggiuntivi degli stessi, richiedendo l’autenticazione tramite SPID al cittadino e quindi unificando l’UX del processo di pagamento.

Il Nodo SPC inoltre lavora anche come server di chiamata in quanto anche i metodi normali (bollettino postale, bonifico, etc…) sono controllati e gestiti tramite il suo supporto, di conseguenza l’EC che intende collegarsi al sistema deve predisporre un ambiente anche di ricezione di Request SOAP.

Attualmente un EC ha un sistema proprietario di gestione dati e rendicontazione di conseguenza si possono immaginare due scenari di integrazione:

• Integrazione tramite Canale di scambio delle informazioni e dei dati che poi dovranno essere gestiti direttamente nel gestionale del singolo EC
• Integrazione tramite Repository dati e quindi tramite sync da EC e successivamente gestore delle comunicazioni tra Cittadino e Pagamento

Il portale EC deve inoltre fornire al cittadino delle alternative al pagamento digitale tramite QRCode o bollettino postale di nuova generazione come da linee guida contenute nel documento Avviso Analogico

In ultima analisi, visto che si vorrebbe lasciare la massima libertà di scelta del metodo di integrazione più ottimale direttamente agli EC si sono scorporati al massimo tutte le componenti richieste per collegarsi a pagoPA cosi da consentirne l’ utilizzo anche in maniera separata.

Viene fornito uno Startup Kit con cui è possibile visualizzare attraverso il software SOAP UI tutte le chiamate possibili effettuabili da un EC o dal Nodo SPC ed eventualmente scaricando i espositori presenti su GitHub si possono avere i WSDL ed XSD delle relative request sia in ingresso che in uscita.

I WebService attualmente disponibili sono:

• nodoInviaCarrelloRPT
• nodoInviaAvvisoDigitali
• nodoChiediElencoFlussiRendicontazione
• nodoChiediFlussoRendicontazione
• nodoChiediListaPendentiRPT
• nodoChiediStatoRPT
• nodoInviaRichiestaStorno
• nodoChiediInformativaPSP
• nodoChiediElencoQuadraturePA
• nodoChiediQuadraturaPA
• paaVerificaRPT
• paaAllegaRPT
• paaChiudiNumeroAvviso
• paaChiediAvvisiDigitali
• paaInviaEsitoStorno

Come supporto sono stati realizzati degli schemi di integrazione che illustrano i funzionamenti principali del sistema che sono visibili nella rispettiva appendice.

Per poter iniziare ad utilizzare il sistema pagoPA occorre accreditarsi presso lo stesso e condividere un certificato di autenticazione che dovrà poi essere presente negli Header di ogni request in maniera da permettere al portale di verificare l’attendibilità della fonte.

Visti i futuri sviluppi introdotti dall’Agenzia per l’Italia Digitale che vogliono introdurre una sessione permanente tramite il protocollo di autenticazione SPID (SAML 2.0) ogni EC dovrá permettere ai propri utenti (Cittadini) di poter accedere al sistema tramite l’Identità Unica cosi da velocizzare il processo di pagamento implementato tramite WISP.

Tutti i log delle richieste e relative risposte, anche gli errori, dovranno essere archiviati e mantenuti.

Dalle linee guida File Transfer si legge come in futuro il sistema di comunicazione tramite WebService SOAP sarà ridotto in merito al nuovo standard di comunicazione dati tramite SFTP cosi che le comunicazioni XML (risposte ai Web Service) siano depositate direttamente in un aree dedicata dell’EC che lo ha richiesto.

In preparazione di questa nuova metodologia di comunicazione il WRAPPER API dovrebbe permettere l’archiviazione della risposta anche in maniera non diretta e prevedere la posizione ed il nome del file da utilizzare per poter estrapolare tutte le informazioni necessarie all’EC.

Si tratta di una gemma che dovrebbe semplificare la gestione delle chiamate e relative risposte tra EC e sistema pagoPA.

Il wrapper dovrebbe gestire tutti i possibili messaggi di errore delle chiamate. Il sistema dovrebbe automatizzare tutto il processo tramite WISP consentendo una configurazione rapida e di minimo impatto al sistema esistente.

Si rimanda al documento Specifiche Attuative in cui sono illustrati tutti i webservice dispomnibili e il loro funzionamento.

Per quanto riguarda i messaggi di errore si rimanda invece al documento Errori webservice Per i codici di versamento Codici versamento, riversamento e rendicontazione

In sintesi cosa dovrebbe contenere la gemma:

• Generatore Header autenticato per inizializzare la request
• Validatore delle request e response SOAP
• Implementare tutte le request verso pagoPA
• Implementare la possibilità di creare degli endpoint per le request da pagoPA
• Generatore di IUV (Identificativo Univoco Versamento)
• Generatore di QRCode o Barcode

Per la generazione dello IUV devono essere ovviamente inseriti dei parametri di configurazione a livello di sistema in quanto, come da specifiche, deve essere univoco a livello di sistema e deve seguire delle specifiche chiare ().

Il sistema dovrebbe contenere il WSDL base attraverso il quale poter effettuare tutte le chiamate e avere le specifiche di riferimento per ognuna di esse.

Deve essere presente un file di configurazione e di seguito un esempio dei parametri necessari:

• BASE_URI_PAGOPA
• DOMINIO_ID_EC
• CODICE_EC
• ENDPOINTS

Il sistema dovrebbe inoltre prevedere la possibilità tramite activerecord, di archiviare in DB le response sia delle varie richieste che di quelle generate automaticamente da pagoPA, cosi da avere un log e consentire anche in un secondo momento di poter prendere i dati ed utilizzarli.

Si pensava inoltre di poter prevedere che il modello sia configurabile in maniera tale da permettere di utilizzare una struttura e codice più adeguati al sistema a cui si aggiunge l’ integrazione.

Le chiamate verso i WebService devono prevedere uno User-Agent all'interno degli Header di chiamata altrimenti tornano come status code 302.

Si tratta di un sistema completo che dovrebbe operare in supporto al sistema attuale integrato tramite WISP permettendo ad un EC di implementare la procedura completa integrandosi direttamente con i vari PSP supportati.

In questo caso il sistema conterrebbe la gemma precedente ed in più avrebbe la gestione centralizzata di tutto il traffico in uscita ed entrata dal relativo EC.

Come da linee guida dovrebbe inoltre contenere delle viste (di cui sarà possibile fare un override) che permettono la stampa a video di tutti i PSP con il relativo costo aggiuntivo e la gestione dei metodi di pagamento con i relativi redirect di completamento della procedura di pagamento.

In questo modo non servirebbe andare a creare tutto il sistema di controller nell’app principale ma la nuova gemma avrebbe tutte le configurazioni al suo interno comprensive di ENDPOINT di chiamata da pagoPA e gestione delle tabelle necessarie al suo corretto funzionamento.

Le tabelle necessarie dovrebbero essere:

• responses -> memorizza tutte le chiamate in ingresso
• requests -> memorizza tutte le chiamate in uscita

Inoltre dovrebbe essere possibile indicare al sistema i nomi delle tabelle o dei modelli che gestiscono le pendenze di pagamento e i dati utente cosi da permettere al sistema di prelevare le informazioni necessarie ad effettuare le transazioni.

Grafici di revoca dei pagamenti come da linee guida di AgID