polo regionale dei pagamenti disciplinare tecnico · 2017-08-21 · a disposizione degli enti...

PoloRegionaledeiPagamentiDisciplinareTecnico

Versione 2.0

2

Sommario

SOMMARIO .................................................................................................................................... 2

1. INTRODUZIONE ................................................................................................................. 4

1.1. Premessa .................................................................................................................... 4

1.2. Scopo .......................................................................................................................... 4

1.3. Abbreviazioni .............................................................................................................. 4

2. COSA È PREVISTO DALLE DISPOSIZIONI NAZIONALI ......................................................... 4

2.1. Scadenze ..................................................................................................................... 4

2.2. Come funziona il sistema nazionale dei pagamenti PA .............................................. 5

2.3. Intermediari tecnologici ............................................................................................. 7

2.4. Il formato dell’IUV ...................................................................................................... 7

3. SERVIZI DISPONIBILI ALLE PA ............................................................................................ 7

3.1. I servizi di Portale di NRP ............................................................................................ 9

3.2. I servizi applicativi di NRP ......................................................................................... 10

3.3. Scenari di pagamento ............................................................................................... 11

3.4. NRP e gli scenari di riconciliazione dei pagamenti ................................................... 15

4. IL PORTALE DI BACK‐OFFICE DI NRP ............................................................................... 17

4.1. Accesso a RPT ........................................................................................................... 18

4.2. Accesso a RT ............................................................................................................. 19

4.3. Lista PSP: attivazione ................................................................................................ 19

4.4. Lista PSP: accesso ..................................................................................................... 19

4.5. Flussi di rendicontazione: attivazione ...................................................................... 19

4.6. Flussi di rendicontazione: accesso ............................................................................ 20

4.7. Flussi di quadratura: attivazione .............................................................................. 20

4.8. Flussi di quadratura: accesso .................................................................................... 20

4.9. Accesso al giornale degli eventi ................................................................................ 20

3

4.10. Accesso a dati generali statistici sull’attività di NRP................................................. 21

4.11. Configurazione servizi ............................................................................................... 21

4.12. Caricamento massivo pratiche ................................................................................. 21

4.13. Gestione pratiche in attesa ...................................................................................... 23

4.14. Storno di una RT ....................................................................................................... 23

5. IL PORTALE DI FRONT‐OFFICE DI NRP ............................................................................. 23

5.1. Pagamenti in attesa .................................................................................................. 23

5.2. Pagamenti spontanei ................................................................................................ 24

5.3. Link ai servizi di pagamento ...................................................................................... 24

6. I SERVIZI APPLICATIVI DI NRP: WEB SERVICES REST ....................................................... 24

6.1. Introduzione ............................................................................................................. 24

6.2. Convenzioni .............................................................................................................. 33

6.3. I metodi esposti ........................................................................................................ 35

7. I SERVIZI APPLICATIVI DI NRP: BRIDGE NRP .................................................................... 47

8. IL SISTEMA DI TEST DI NRP ............................................................................................. 49

9. APPENDICE A – CODICI DI ERRORE RESTITUITI DALLE PRIMITIVE .................................. 49

10. APPENDICE B – GLI STATI DI UNA PRATICA ALL’INTERNO DI NRP .................................. 51

11. APPENDICE C – IL PAGAMENTO IMMEDIATO NELLA PAP .............................................. 51

12. APPENDICE D – IL PAGAMENTO PRESSO PSP (NELLA PAP) ............................................ 60

4

1. INTRODUZIONE

1.1. Premessa

La normativa vigente prevede l’obbligo per ciascuna Pubblica Amministrazione di gestire i pagamenti elettronici (riscossioni) in formato elettronico secondo le regole e le Linee Guida predisposte dall’Agenzia per l’Italia Digitale (AgID) – con i relativi allegati tecnici – pubblicate sul sito: www.agid.gov.it/agenda‐digitale/pubblica‐amministrazione/pagamenti‐elettronici/linee‐guida .

1.2. Scopo

Lo scopo del presente documento è quello di descrivere i componenti sviluppati da Regione Liguria e messi a disposizione degli Enti Liguri per la gestione dei pagamenti elettronici dei quali sono beneficiari.

1.3. Abbreviazioni

IUV Identificativo Univoco di Versamento NRP Nodo Regionale Pagamenti API Application Programming Interface PSP Prestatore Servizi di Pagamento

IUV Identificativo Univoco di Versamento FE Front End

PAP Porta Applicativa Pagamenti (AgID) RPT Richiesta di Pagamento Telematica

REST REpresentational State Transfer RT Ricevuta Telematica (di pagamento)

WISP Wizard Scelta PSP (AgID)

2. COSAÈPREVISTODALLEDISPOSIZIONINAZIONALI

2.1. Scadenze

Ai sensi dell’articolo 5, comma 1 del CAD, le pubbliche amministrazioni e i gestori di pubblici servizi devono adeguare entro il primo giugno 2013 le proprie procedure informatiche e gli strumenti software al fine di consentire l’effettuazione dei pagamenti elettronici. Si precisa che la procedura di adesione al sistema nazionale dei pagamenti costituisce di per sé il rispetto dell’articolo 5 del CAD, a condizione che la pubblica amministrazione in sede di adesione alla piattaforma nazionale definisca un piano di attivazione che individui in dettaglio le attività da compiere e i tempi di realizzazione, da terminare entro il 31 dicembre 2015. Per quanto riguarda l’attivazione dei servizi il termine ultimo è il 31/12/2016. Ferma restando la facoltà di adesione alla piattaforma nazionale, i gestori di pubblici servizi possono ricevere pagamenti informatici a mezzo bonifico e/o bollettino di conto corrente postale senza l’uso della piattaforma di cui sopra. Di converso, le pubbliche amministrazioni possono ricevere pagamenti informatici a mezzo bonifico e/o bollettino di conto corrente postale senza l’uso della piattaforma nazionale solo in via transitoria, entro e non oltre il 31 dicembre 2015 e a condizione che abbiano già espletato la procedura di adesione.

5

2.2. ComefunzionailsistemanazionaledeipagamentiPA

Quanto segue è un estratto dalle Linee Guida AgID: vengono riportati gli elementi principali funzionali alla lettura delle sezioni successive di presente documento. Nell’ambito delle relazioni tra utilizzatori finali (cittadino, professionista, impresa) e pubbliche amministrazioni l’effettuazione di pagamenti è sempre riconducibile a un processo amministrativo che si articola in fasi ben definite, funzionali al suo corretto completamento. Tali fasi possono essere ricondotte in un “Ciclo di vita del pagamento”, a qualunque titolo gli importi siano dovuti: tassa, imposta, oblazione, ticket per prestazioni, etc. Le fasi possono essere schematizzate come segue: a) nascita della necessità del pagamento (da parte dell’ente o del privato); b) generazione delle informazioni necessarie per dar corso al pagamento; c) pagamento; d) regolamento e riversamento degli importi; e) riconciliazione del pagamento; f) emissione della quietanza da parte dell'ente creditore ed eventuale erogazione del servizio. Tenuto presente che le fasi sopra riportate possono avere un ordine diverso da quello su indicato e che tale ordine può variare a seconda dello scenario e della tipologia di servizio al quale si riferisce il pagamento, le Linee guida AgID contengono le indicazioni circa le modalità attraverso le quali automatizzare e de‐materializzare le varie fasi del “Ciclo di vita del pagamento” e contengono inoltre le informazioni essenziali per la loro attuazione. Gli enti creditori mettono a disposizione dell’utilizzatore finale (pagatore o soggetto versante) sui propri siti web e sugli avvisi di pagamento le seguenti informazioni minime: a) Denominazione dell’ente creditore; b) Identificativo dell’obbligato (il pagatore); c) Importo del pagamento dovuto; d) Identificativo univoco di versamento e causale del versamento; e) Identificativo del conto di pagamento sul quale versare le somme dovute (IBAN o conto corrente postale); f) Scadenza (se prevista). Nel momento in cui i dati vengono resi disponibili all’utilizzatore finale, gli stessi devono essere memorizzati in un apposito archivio ‐ che costituisce evidenza informatica dei pagamenti attesi ‐ al fine di facilitare la fase di riconciliazione. Gli enti creditori possono ampliare i dati resi disponibili in coerenza con le proprie soluzioni organizzative. Al fine di consentire le attività di riconciliazione del pagamento da parte degli enti creditori e quelle di riversamento a cura dei prestatori di servizi di pagamento, ciascun ente creditore attribuisce ad ogni operazione di incasso un codice identificativo denominato “Identificativo Univoco di Versamento” (IUV) che non può essere associato nel tempo ad alcun altro incasso emesso dal medesimo ente creditore. Gli enti creditori possono demandare a un soggetto terzo, in tutto o in parte, la generazione dell’Identificativo Univoco di Versamento, curando che ne sia mantenuta l’univocità nel tempo. Per i versamenti al bilancio dello Stato o ai conti aperti presso la Banca d’Italia nell’ambito del servizio di tesoreria dello Stato di cui al decreto del Ministro dell'economia e delle finanze 9 ottobre 2006, n. 293 (“Regolamento recante norme per l'introduzione di nuove modalità di versamento presso le tesorerie statali”), l’indicazione del codice IUV si affianca alle disposizioni fornite dalla Circolare della Ragioneria Generale dello Stato n. 20 dell’8 maggio 2007, con particolare riferimento agli elementi da indicare obbligatoriamente nel campo causale del versamento. In aderenza all’autonomia organizzativa degli enti il quadro normativo enuclea le operazioni di pagamento per le quali la verifica del buon fine dello stesso debba essere contestuale all'erogazione del servizio – per semplicità Pagamenti contestuali all’erogazione del servizio – dagli altri, che pertanto saranno individuati come Pagamenti non contestuali all’erogazione del servizio. I primi sono i pagamenti, effettuati dall’utilizzatore finale attraverso i siti web degli enti creditori (portale PA), concomitanti alla erogazione del servizio richiesto ovvero integrati in un procedimento amministrativo che prevede la de‐materializzazione dell’attestazione del pagamento. Per secondi ci si riferisce ai pagamenti per i quali non è richiesta, sul sito web dell’ente creditore, un’operatività di tipo interattivo con l’utilizzatore finale; tali pagamenti sono eventualmente supportati da un “avviso di pagamento analogico” e possono quindi essere perfezionati in

6

tempi successivi valendosi dei canali offerti dai prestatori di servizi di pagamento PSP quali, per esempio, banche, ecc. Nel seguito del documento i primi saranno denominati “pagamenti da portale PA” mentre i secondi “pagamenti da PSP”. L’Agenzia per l’Italia Digitale, ai sensi del vigente quadro normativo, mette a disposizione delle pubbliche amministrazioni, attraverso il Sistema Pubblico di Connettività, una piattaforma tecnologica per assicurare l’interconnessione e l’interoperabilità tra queste ultime e i prestatori di servizi di pagamento, denominata nel seguito “Nodo dei Pagamenti‐SPC”.

L’utilizzo della piattaforma è obbligatorio per le pubbliche amministrazioni

L’infrastruttura messa a disposizione dall’Agenzia per l’Italia Digitale consente agli enti creditori di gestire tutte le soluzioni organizzative adottate per far effettuare i pagamenti dovuti attraverso il Nodo dei Pagamenti‐SPC ‐ gestire in modo interattivo tutti i pagamenti, nonché consentire all’utilizzatore finale di operare direttamente sui canali offerti dai prestatori di servizi di pagamento, rendendo possibile agli enti creditori lo snellimento dei processi di riscossione, il miglioramento della qualità dei servizi erogati e il risparmio sui costi di processo. L’esecuzione dei pagamenti si perfeziona attraverso lo scambio di oggetti informatici denominati “Richiesta di pagamento telematico” e “Ricevuta telematica”, tra il “Nodo dei Pagamenti‐SPC” e le piattaforme dei prestatori di servizi di pagamento aderenti che colloquiano tra di loro in modalità cooperativa. Le “Ricevute telematiche” costituiscono prova dell’avvenuto addebito del pagatore o del soggetto versante e devono essere conservate, a cura degli enti creditori, con le modalità indicate nelle disposizioni sulla conservazione dei documenti informatici. L’adesione dei prestatori di servizi di pagamento al “Nodo dei Pagamenti‐SPC” consente a questi ultimi di rilasciare al pagatore una ricevuta, telematica o cartacea, con potere liberatorio. Per un approfondimento sulle modalità tecniche e organizzative per l’utilizzo della piattaforma tecnologica si rimanda all’Allegato B delle Linee Guida AgID.

7

Schema architetturale sistema nazionale (da Linee Guida AgID)

2.3. Intermediaritecnologici

Le Pubbliche Amministrazioni possono offrire il servizio e accedere al Nodo dei Pagamenti‐SPC anche attraverso un intermediario pubblico o privato (quali per esempio: regione, consorzio di enti pubblici o altro) che gestisce per suo conto i servizi di front‐office offerti all’utilizzatore finale, nonché tutte le funzionalità di interconnessione al Nodo dei Pagamenti‐SPC. I PSP possono anche essi utilizzare degli intermediari per connettersi al Nodo dei Pagamenti‐SPC ovvero per offrire i propri servizi di pagamento; tali soggetti possono essere rappresentati da altri prestatori di servizi di pagamento ovvero da circuiti o consorzi costituiti in ambito finanziario. Rimangono comunque inalterate le responsabilità di ente creditore e PSP nei confronti delle controparti e in particolare degli utilizzatori finali.

2.4. Ilformatodell’IUV

In deroga a quanto indicato nell’Allegato A delle Linee Guida, il formato dell’IUV è stato specificato da AgID nel seguente modo:

a) la lunghezza massima applicabile è di 15 posizioni; b) deve essere formato da soli numeri; c) le ultime due cifre a destra devono riportare il resto della divisione per 93 del numero ottenuto

anteponendo alle restanti cifre iniziali dello IUV anche i dati <aux digit> e <application code>1; Nell’ambito di NRP, il codice IUV ha la seguente struttura:

Versione PA Contatore (max 11 digits) Check

V P n n n n n n n n n n n C C

I significati dei campi sono i seguenti:

Versione: ha, al momento, un valore numerico pari a “0”;

PA: il campo è “0” se l’IUV è generato dal Nodo dei Pagamenti, “1” se è generato dalla PA;

check digits: resto della divisione per 93 del numero ottenuto anteponendo alle restanti cifre iniziali dello IUV anche i dati <aux digit> e <application code>.

Si ricorda che l’IUV è univoco nell’ambito di ciascuna PA: il pagamento, di fatto, a livello nazionale viene identificato da due identificatori: codice fiscale PA e IUV.

3. SERVIZIDISPONIBILIALLEPARegione Liguria mette a disposizione delle PA liguri:

1 Per <aux digit> e <application code> vedi il documento di Linee Guida Nazionali: al momento il primo è “0” mentre il

secondo è “00”.

8

la Porta di Dominio (PdD) configurata per il corretto colloquio con il Nodo dei Pagamenti‐SPC;

il Nodo Regionale dei Pagamenti (NRP) integrato con la PA. Il sistema Nodo Regionale dei Pagamenti (NRP):

si configura come intermediario tecnologico per le PA liguri;

si propone di semplificare il dialogo con il Nodo dei Pagamenti‐SPC (il nodo nazionale) manlevando, per esempio, le PA da tutte le attività legate alle Porte di Dominio

mette a disposizione delle PA liguri un ambiente operativo dedicato: questo ambiente utilizza, in riuso, le funzioni di un applicativo sviluppato dall’AgID (PAP – Porta Applicativa dei Pagamenti) e include anche un repository dei pagamenti; tale ambiente dedicato offre:

o una serie di servizi applicativi disponibili mediante WS REST; o una serie di servizi applicativi realizzati da un “bridge NRP” richiamabile via URL; o un portale di back‐office grazie al quale è possibile inserire nuove pratiche, controllare lo

stato di quelle già inserite e visualizzare gli incassi effettuati; o un portale di front‐office a disposizione dei cittadini per effettuare pagamenti;

su richiesta, genera lo IUV per conto della PA garantendone, quindi, l’unicità anche in presenza di più servizi distinti (della PA stessa) che utilizzano il sistema;

offre uno spazio di archiviazione sul quale ciascuna PA può caricare le pratiche da pagare;

offre disponibilità del servizio nei confronti del Nodo dei Pagamenti‐SPC manlevando quindi la PA dal mantenere disponibilità di servizio sui propri sistemi informativi: nella configurazione più semplice, la PA ha infatti solo l’onere di registrare l’informazione del debito su NRP (e di andarne a leggere l’esito).

NRP espone servizi e dialoga principalmente con:

Sistemi titolari di pratica: (nel seguito “sistema PA”) sistema al quale è delegata la gestione di pratiche

oggetto di pagamento. Esempi sono rappresentati dal sistema del bollo auto, dal CUP, dal sistema

informativo di una PA;

Portali di pagamento: (nel seguito “portale PA”) portali istituzionali che consentono al cittadino di

effettuare un pagamento (es. Ticket Web, Bollo Auto, Certificazioni, ecc.);

Nodo Nazionale dei Pagamenti: il Nodo dei Pagamenti‐SPC di AGID;

Operatori PA (bilancio, assistenza e manutenzione, ecc.);

9

La PA può interagire con NRP attraverso:

WS REST: interazione (applicativa) server‐to‐server tra sistema PA e NRP;

Bridge NRP: interazione (applicativa) tra Portale PA e sistema NRP (solo per pagamenti immediati);

Portale di Back‐office: interazione attraverso operatore PA e NRP;

Il cittadino può pagare:

Utilizzando il Portale PA, se presente;

Utilizzando il Portale di front‐office di NRP (per le partite già presenti su NRP);

Utilizzando i PSP.

3.1. IservizidiPortalediNRP

PortalediBack‐office

Il Portale di Back office è funzionale a operatori che fanno parte della PA intermediata o che sono

amministratori centrali di NRP.

Consente l’accesso a informazioni di reportistica e di rendicontazione e offre servizi di gestione di NRP.

Le funzioni principali sono:

Operazioni caricamento pratica (singola o massiva);

Operazioni di rendicontazione, controllo e storno;

Il Portale è fruibile attraverso protocollo https e a valle di una verifica positiva da parte del sistema di

identificazione regionale (IAM).

Ciascun operatore PA può avere accesso solamente alle transazioni afferenti alla propria PA. Non è

presente, al momento, un ulteriore filtro di accesso dell’operatore per codice servizio.

10

PortalediFront‐office

Il Portale di Front‐office consente al cittadino di effettuare il pagamento di pratiche che la PA ha

precedentemente caricato su NRP (pratiche con Avviso). Il cittadino si collega al Portale di Front‐office,

sceglie la PA beneficiaria e inserisce il codice IUV in suo possesso. Il Portale NRP procede al pagamento e

rilascia l’attestato di pagamento al cittadino. La RT, come per gli altri casi, rimane disponibile su NRP per la

PA che potrà, quindi, consegnare la ricevuta di pagamento al cittadino.

Il Portale di Front‐office consente, inoltre, al cittadino di effettuare un pagamento “spontaneo” di pratiche

che la PA ha precedentemente configurato su NRP. Il cittadino si collega al Portale di Front‐office, sceglie la

PA beneficiaria e sceglie il tipo di pratica (negozio) che desidera pagare, integra il pagamento con gli

estremi del pagatore, l’importo dovuto e la causale. A questo punto può decidere se effettuare il

pagamento on line oppure pagare in seguito presso un PSP abilitato. Il servizio si completa con la gestione

del pagamento in attesa con la possibilità di pagarlo on line od eliminarlo.

Il Portale di Front‐office, per i servizi concordati con la PA, può, se ritenuto necessario ed utile, presentare

anche una sezione dedicata ai pagamenti immediati (pratiche senza Avviso) per i quali rimanda il cittadino a

un link sul sistema specifico della PA (es., pagamento ticket, pagamento bollo auto) dove il cittadino può

recuperare il proprio debito ed effettuare il pagamento.

3.2. IserviziapplicatividiNRP

I servizi applicativi di NRP sono utilizzabili dai programmatori degli enti per creare specifici servizi applicativi

di pagamento e/o integrare le funzioni di pagamento nei sistemi verticali esistenti.

NPR rende disponibili i seguenti servizi:

WebServicesREST

Le funzioni REST offerte da NRP consentono di effettuare tutte le operazioni sia per quanto riguarda i

pagamenti sia per quanto riguarda la rendicontazione (e manutenzione). Tali funzionalità sono al momento

qui elencate solo per facilitare la comprensione degli scenari di pagamento illustrati nel paragrafo

successivo: la trattazione di dettaglio è riportata nella Sezione 6.

Descrizione Funzione WS REST

Lista PSP papRestChiediListaPSP

AggiornamentolistaPSPdanodonazionale

papRestAggiornaListaPSP

Richiesta IUV papRestGeneraIUV

Caricamento di un debito papRestCaricaPagamentoDiretto

Annullamento di un debito papRestAnnullaPagamentoDiretto

Richiesta di pagamento immediato papRestInviaRPT

Pagamentodiretto:attivazioneRPTinattesa

papRestAttivaRPT

Richiesta storico RPT papRestChiediStoricoRPT

Pagamentodiretto:richiestastatoRPTinattesa

papRestNodoChiediStatoRPT

11

Descrizione Funzione WS REST

VerificaRPTpendentitraNRPeNodonazionale

papRestNodoChiediListaPendentiRPT

Richiesta RT papRestChiediRT

RercuperoRT papRestGetRT

Richiesta storico RT papRestChiediStoricoRT

Richiesta elenco flussi rendicontazione papRestChiediElencoFlussiRendicontazione

Richiesta singolo flusso rendicontazione papRestChiediFlussoRendicontazione

ScaricoflussidirendicontazionedaNodoNazionale

papRestScaricaNuoviFlussiRendicontazione

Elaboraflussodirendicontazione papRestElaboraFlussiRendicontazione

ScaricoflussidiquadraturadaNodoNazionale

papRestScaricaNuoviFlussiQuadraturaPA

Elaboraflussodiquadratura papRestElaboraFlussiQuadraturaPA

Interrogazione Giornale degli Eventi papRestInterrogaGdE()

StornoRT papRestStornaRT

Richiestapagamentocarrello papRestInviaCarrelloRPT

BridgeNRP

Per semplificare ulteriormente l’interazione (e integrazione) con NRP per quei sistemi di pagamento

regionale in esercizio già da tempo che (attualmente) utilizzano il servizio (e, quindi, le specifiche tecniche)

QuiPago – gestite dall’azienda Key Client – è stato realizzato un modulo detto “Bridge NRP” che, si

comporta come un “proxy” presentando a tali sistemi il Nodo Regionale dei Pagamenti attraverso

interazioni molto simili a quelle attualmente utilizzate per il servizio QuiPago. Le funzioni di Bridge NRP

sono quindi progettate per supportare il Portale PA per le sole funzioni di pagamento immediato e

comportano adattamenti minimi ai sistemi verticali che utilizzano già questo sistema di pagamento.

Nello scambio di informazioni tra Portale PA e Bridge NRP è obbligatorio aggiungere la fase di

autenticazione reciproca compiuta accodando a ogni messaggio un MAC (Message Code Authentication)

calcolato sui dati della transazione. L’adozione di un MAC è obbligatoria in quanto consente di verificare, sia

a Regione Liguria, sia al Portale PA, che non siano stati manipolati i dati inviati attraverso URL. La

trattazione di dettaglio è riportata nella Sezione 7.

3.3. Scenaridipagamento

Le funzioni esposte da NRP consentono alla PA di progettare e realizzare i propri servizi di pagamento

attraverso differenti modalità.

Di seguito sono mostrati alcuni esempi che illustrano i casi d’uso più comuni.

In tutti questi casi verranno usati i seguenti termini:

Cittadino: soggetto (cittadino o impresa) che deve effettuare un pagamento alla PA

Sistema PA: sistema informativo della PA dedicato a tematiche specifiche (es., CUP, Pronto

Soccorso, Bollo Auto, multe, ecc.) e dotato di un proprio “sottosistema pagamenti”

Portale PA: portale della PA collegato a un proprio “sottosistema pagamenti”

12

Sottosistema pagamenti: sottosistema della PA in grado di interagire con NRP per quanto concerne

l’aspetto dei pagamenti.

Operatore PA: soggetto della PA profilato sul sistema regionale che opera all’interno del portale di

back‐office di NRP.

Casod’uso1a:pagamentoimmediatodaportalePAconWSREST

In questo caso il cittadino si collega con il proprio Internet browser al portale PA e – mediante il

sottosistema pagamenti ‐ inserisce tutte le informazioni relative al proprio debito (utili alla predisposizione

della RPT). Inseriti i dati procede “immediatamente” al pagamento on line (modello 1 di PagoPA:

pagamento immediato).

I passi logici sono i seguenti:

1. il cittadino si collega al portale della PA e ricerca il proprio debito;

2. il portale PA acquisisce dal cittadino il PSP prescelto attraverso il sistema WISP di AgID;

3. Il sottosistema pagamenti:

a. genera un proprio IUV o ne richiede uno a NRP (attraverso la funzione papRestGeneraIUV)

b. completa la RPT con lo IUV e i dati identificativi del PSP prescelto dal cittadino

c. procede con un pagamento immediato, attraverso la funzione papRestInviaRPT

d. ridirige il browser del cittadino sull’URL del PSP (ricevuta da NRP in risposta a

papRestInviaRPT) per l’autorizzazione al pagamento

4. il cittadino:

a. introduce l’autorizzazione al pagamento (sul sito del PSP)

5. Il PSP – una volta recuperato l’incasso – ridirige il browser del cittadino verso il portale PA e invia la

RT a NRP

6. Il portale PA, a questo punto, può recuperare la RT interrogando NRP (attraverso la funzione

papRestChiediRT) e, se il pagamento è andato a buon fine (RT positiva) consegnare la ricevuta al

cittadino.

13

Questo caso d’uso, per una sua parte, è assimilabile a quello del “pagamento immediato” della PAP e, per

semplicità di lettura, riassunto in Appendice C.

Casod’uso1b:pagamentoimmediatodaportalePAconBridgeNRP

Da un punto di vista dell’interazione con il cittadino, questo caso è identico al precedente. Viene però

richiamato dal Portale PA il Bridge NRP. Questa funzionalità presenta al portale un’interazione simile a

quella già utilizzata da diversi Portali di pagamento regionali prima dell’introduzione del Nodo Nazionale dei

Pagamenti e, oltre a rappresentare una notevole facilitazione per nuovi portali PA, consente di riutilizzare,

quasi senza modifiche, molti servizi di pagamento attualmente in esercizio.

Il Bridge NRP tratta esclusivamente pagamenti immediati e si occupa, fra l’altro, della scelta del PSP e della

generazione dell’IUV.

14

Casod’uso2:debitoinseritodaPAepagatodaPSP(scenariodipagamentodiretto)

In questo caso il cittadino paga presso una struttura PSP un debito generato all’interno della PA e di cui è

posto a conoscenza tramite un Avviso di Pagamento.

Il debito viene generato dal sistema PA mediante il proprio sottosistema pagamenti.


1. La PA inserisce i dati del debito mediante il proprio sottosistema pagamenti (o da Portale di Back‐

office):

a. genera un proprio IUV o ne richiede uno a NRP;

b. inserisce il debito (con IUV) su NRP;

c. produce l’Avviso di Pagamento che riporta lo IUV associato al debito, consegnandolo (es.

via e‐mail, posta tradizionale) al cittadino;

2. il cittadino:

a. si reca presso una struttura PSP e mostra l’Avviso di Pagamento (che contiene il C.F. della

PA e l’IUV della pratica);

3. il PSP:

a. interroga il NRP utilizzando C.F. PA e IUV contenuti nell’Avviso di Pagamento;

b. in caso di risposta positiva:

i. consente la finalizzazione del pagamento

ii. produce un attestato di pagamento (con l’IUV) per il cittadino e contestualmente

iii. invia la RT a NRP, ove rimarrà a disposizione della PA

c. in caso negativo, la transazione verrà negata

4. Il sistema PA, una volta recuperata la RT da NRP, potrà consegnare – se il caso – la ricevuta al

cittadino.

Il passo 1. (caricamento del debito su NRP da parte della PA) può essere fatto sia attraverso chiamata a

metodo WS Rest esposto da NRP (papRestCaricaPagamentoDiretto) da parte del sottosistema PA oppure

15

attraverso il Portale di Back‐office di NRP (caricamento singolo o massivo di debiti). Di seguito, lo schema

nel primo caso (WR Rest) in cui la PA chiede anche un IUV a NRP.

Questo caso d’uso, per una sua parte, è assimilabile a quello del “pagamento diretto attivato presso

strutture PSP” della PAP e, per semplicità di lettura, riassunto in Appendice D.

Casod’uso3:debitoaggiornatodasistemaPA

In questo caso il sistema PA ha già precedentemente inserito un debito in NRP, questo debito non è ancora

stato pagato e nasce l’esigenza di aggiornarne, per esempio, l’importo (es., mora e interessi). Questa

operazione può essere fatta sia attraverso l’utilizzo dei WS Rest esposti da NRP (combinazione di

papRestAnnullaPagamentoDiretto e papRestCaricaPagamentoDiretto), sia attraverso il Portale di Back‐

office di NRP. Di seguito lo schema nel primo caso.

Il debito viene aggiornato dal sistema PA mediante il proprio sottosistema pagamenti.

3.4. NRPegliscenaridiriconciliazionedeipagamenti

Come specificato nelle Linee Guida di AgID (Allegato B), e qui riassunto per semplicità di lettura, una volta

terminata la fase di pagamento da parte del PSP, la PA beneficiaria provvede a riconciliare le Ricevute

16

Telematiche (RT) con le informazioni fornite dalla propria Banca Tesoriera. Il PSP che riceve l’ordine dal

proprio cliente o che esegue l’incasso per conto del ente creditore può regolare contabilmente l’operazione

in modalità singola o in modalità cumulativa, il che comporta per la PA beneficiaria due diverse modalità di

riconciliazione.

Qualora, a fronte del singolo versamento, il PSP effettui una singola disposizione di pagamento nei

confronti della Banca Tesoriera della PA beneficiaria per regolare contabilmente l’operazione (ad esempio:

l’utilizzo della forma tecnica “bonifico di tesoreria”), si parla di riconciliazione in modalità singola.

Qualora il PSP effettui un’unica disposizione di pagamento nei confronti della Banca Tesoriera dell’ente

creditore per regolare contabilmente i pagamenti relativi agli esiti contenuti in una o più Ricevute

Telematiche, si parla di rendicontazione in modalità multipla che viene effettuata dall’ente creditore sulla

base dei dati forniti dal proprio istituto tesoriere e di quelli contenuti nel flusso di rendicontazione generato

dal PSP che viene messo a disposizione della PA beneficiaria attraverso NRP. La riconciliazione in questo

caso deve essere effettuata in due fasi: nella prima fase il dato identificativoFlusso ‐ presente nella causale

di versamento del SEPA Credit Transfer, secondo lo standard indicato nella Sezione II dell’Allegato A alle

Linee guida ‐ deve essere abbinato con quello presente nel Flusso di rendicontazione inviato dal PSP e

disponibile su NRP.

Nella fase di riconciliazione sono quindi presenti tre elementi:

1. RT: la ricevuta telematica che viene resa disponibile immediatamente alla PA dopo l’avvenuto

incasso da parte del PSP;

2. il bonifico della somma incassata dal PSP nei confronti della banca della PA beneficiaria (tesoriere)

che avviene entro il giorno successivo a quello in cui è avvenuto l’incasso;

3. il flusso di rendicontazione che viene predisposto dal PSP (e fatto pervenire a NRP) entro due giorni

successivi a quello in cui è avvenuto l’incasso.

Di seguito uno schema dei vari elementi della rendicontazione (il dialogo tra PSP e NRP avviene sempre

attraverso il Nodo Nazionale):

17

Primocaso:riconciliazionedeipagamentiinmodalitàsingola

Il cittadino effettua un pagamento per una PA (indifferentemente, da portale PA o da PSP). Il PSP

predispone immediatamente la RT che viene inviata a NRP che, a sua volta, la rende disponibile alla PA

(funzione papRestChiediRT). Entro il giorno successivo la PA riceve un bonifico con l’importo della RT: nella

causale di versamento del SEPA Credit Transfer è riportato l’IUV del pagamento effettuato e, quindi, la PA

può recuperare i dettagli del pagamento attraverso la lettura (su NRP) della corrispondente RT.

Secondocaso:riconciliazionedeipagamentiinmodalitàmultipla

Vengono effettuati più pagamenti per una stessa PA (indifferentemente, da portale PA o da PSP) presso un

PSP. Al verificarsi di ciascun pagamento, il PSP predispone immediatamente la RT che viene inviata a NRP

che, a sua volta, la rende disponibile alla PA (funzione papRestChiediRT). Entro il giorno successivo la PA

beneficiaria riceve un bonifico cumulativo dal PSP relativo a più incassi, (e quindi a più RT) che, nella causale

di versamento del SEPA Credit Transfer, riporta il dato identificativoFlusso. Entro due giorni successivi

all’incasso la PA può recuperare su NRP le informazioni (IUV, importo) di tutte le RT coinvolte nel bonifico

cumulativo corrispondente al dato identificativoFlusso (funzione papRestChiediFlussoRendicontazione). Le

informazioni di dettaglio delle singole RT potranno sempre essere recuperate con la funzione

papRestChiediRT.

4. ILPORTALEDIBACK‐OFFICEDINRPIl Portale di Back office è progettato per essere di supporto agli operatori PA che, sostanzialmente, possono

far parte della PA intermediata da NRP o essere amministratori centrali di NRP stesso.

18

Il Portale è fruibile attraverso protocollo https e a valle di una verifica positiva da parte del sistema di

identificazione regionale (IAM).

Ciascun operatore può avere accesso solamente alle transazioni afferenti alle PA per le quali risulta

abilitato. Non è presente, al momento, un ulteriore filtro di accesso dell’operatore per codice servizio.

I profili di accesso previsti sono di seguito elencati unitamente alle sezioni accessibili.

Servizi del Portale

di Back office

referente

contabile

assistenza operatore

cruscotto

amministratore

NRP

1. Accesso a RPT X X X

2. Accesso a RT X X X

3. Lista PSP: attivazione X X X

4. Lista PSP: accesso X X X

5. Flussi di rendicontazione: attivazione X X X

6. Flussi di rendicontazione: accesso X X X

7. Flussi di quadratura: attivazione X X

8. Flussi di quadratura: accesso X X

9. Accesso al giornale degli eventi X X

10. Dati generali statistici X X X X

11.Configurazioneservizi X X

12.Caricamentomassivopratiche X X

13.Gestionepraticheinattesa X X

14.StornodiRT X X

Di seguito una descrizione più dettagliata dei servizi del Portale.

4.1. AccessoaRPT

Il report di accesso a RPT mostra un elenco di tutte le RPT che soddisfano una serie di criteri di ricerca.

I criteri sono i seguenti:

PAP dell’Ente: una

Servizio: uno o tutti

Stato: uno o tutti

Soggetto pagatore: uno o tutti

IUV: uno o tutti

Data da: data di inizio intervallo scelta da calendario

Data a: data di fine intervallo scelta da calendario

L’elenco delle RPT riporta in lista una sintesi dei dati principali della RPT.

A partire dalla singola riga, è prevista la possibilità di accedere a una pagina con tutti i dettagli della RPT.

Il sistema consente la restituzione dei dati selezionati in Excel, CSV e/o PDF.

19

4.2. AccessoaRT

Il report di accesso a RT mostra un elenco di tutte le RT che soddisfano una serie di criteri di ricerca.

I criteri sono i seguenti:


Servizio: uno o tutti

Esito pagamento: uno o tutti

Soggetto pagatore: uno o tutti

IUV: uno o tutti



L’elenco delle RT riporta in lista una sintesi dei dati principali della RT ed il link al sevizio di presentazione e

scarico della Ricevuta Telematica.

A partire dalla singola riga, è prevista la possibilità di accedere a una pagina con tutti i dettagli della RT.


4.3. ListaPSP:attivazione

Il servizio consente di scaricare dal Nodo nazionale la lista aggiornata dei PSP.

Questa stessa funzione è schedulata automaticamente ogni giorno al momento della prima richiesta di

pagamento.

4.4. ListaPSP:accesso

L’utente seleziona:


Banca: una o tutte

Tipo versamento: uno o tutti

Il report restituisce la lista dei PSP che corrispondono ai criteri selezionati.


4.5. Flussidirendicontazione:attivazione

Il servizio consente di ricevere dal Nodo nazionale i flussi di rendicontazione e di elaborali su NRP.

L’elaborazione verifica la corretta corrispondenza tra gli IUV presenti nel flusso e quanto risulta all’interno

della PAP.

20

4.6. Flussidirendicontazione:accesso





Il report restituisce la lista dei flussi di rendicontazione presenti.


4.7. Flussidiquadratura:attivazione

Il servizio consente di ricevere dal Nodo nazionale i flussi di quadratura e di elaborali su NRP.

4.8. Flussidiquadratura:accesso





Il report restituisce la lista dei flussi di quadratura presenti.


4.9. Accessoalgiornaledeglieventi





Esito pagamento: uno o tutti

IUV: uno o tutti

Il report restituisce il contenuto del giornale degli eventi con le informazioni relative ai log.

Per la sua natura la funzione è abilitata agli operatori di assistenza.


21

4.10. Accessoadatigeneralistatisticisull’attivitàdiNRP





Il report restituisce le statistiche della PAP per l’intervallo di tempo selezionato riportando:

Numero annuo complessivo di transazioni di pagamento (con esito positivo ed esito negativo);

Numero annuo per servizio di transazioni di pagamento annuali (con esito positivo ed esito

negativo).


4.11. Configurazioneservizi

Il servizio consente agli operatori di ente di definire i servizi che desiderano rendere disponibili agli

utilizzatori finali (cittadini ed imprese) per:

Pagare “avvisi di pagamento” prodotti e distribuiti dall’ente

Effettuare “pagamenti spontanei”

Nel primo caso il modello di pagamento è sempre il 3, nel secondo caso l’utente finale, una volta

individuato il debito potrà procedere con un pagamento immediato (modello 1) o con uno diretto (modello

3).

In questo servizio, quindi, l’operatore definisce:

Il servizio pubblicato e la sua tipologia (“avviso” o “spontaneo”)

L’ente beneficiario del servizio (normalmente se stesso, ma potrebbe anche essere un altro ente

afferente a NRP)

Tutti gli elementi indispensabili per contestualizzare il pagamento. A titolo di esempio riportiamo

l’IBAN di accredito, il tipi di versamento possibili associati al servizio, circuito MyBank, PSP poste,

l’indicazione se il flusso prevede la generazione dell’IUV tramite NRP o se se ne fa carico il servizio

verticale esterno.

Ogni configurazione è definita negozio e questo codice dovrà essere utilizzato, nel caso degli avvisi di

pagamento, per la predisposizione del file contenente la lista delle pratiche da caricare su NRP.

4.12. Caricamentomassivopratiche

Questo sevizio permette di:

22

Eseguire l’upload di file .zip (uno per volta) contenenti ognuno un flusso di Import nel formato

standard NRP2.

Visualizzare la lista dei flussi caricati con il loro rispettivo stato (“in elaborazione”, “caricato”,

“rigettato”, “pubblicato”).

Per i flussi in stato “rigettato”, verificare, consultando il log della elaborazione, gli errori riscontrati

durante il caricamento (ad esempio: codice negozio non presente per l’ente, flusso con IUV

presente a fronte di configurazione con IUV generato da NRP).

Annullare un flusso appena caricato. L’operazione di annullamento è disponibile solamente se un

flusso è in stato “caricato”.

Per i flussi “caricati” dare il consenso alla pubblicazione ed al loro utilizzo reale da parte degli

utenti finali. Il sistema pone il flusso in stato “pubblicato” e non sono più possibili modifiche.

Non sono previsti caricamenti parziali di file: un solo errore prevede il rigetto di tutto il file.

Il processo di caricamento:

1. Pone lo stato del flusso in “in elaborazione”;

2. Per ogni debito verifica la completezza dei dati che caratterizzano il debito; se l’IUV è presente,

verifica anche che sia corretto e non già utilizzato (o già utilizzato ma con esito negativo: controllo

del campo “codice contesto pagamento”); se ci sono errori pone lo stato in “rigettato” e ritorna

rendendo disponibili gli errori riscontrati. Altrimenti

3. Per ogni debito:

a. Genera l’IUV per i debiti per i quali non è presente;

b. Predispone e inserisce la RPT su PAP (pagamento diretto)

4. Pone lo stato del flusso in “caricato”

5. in caso di errore pone il flusso in stato “rigettato”

Il formato del file per il caricamento massivo di pratiche è descritto nel documento “Polo regionale ligure

dei pagamenti: formato file di scambio dati” al quale si rimanda per tutti i dettagli.

E’ reso disponibile anche un WS di ricezione del file che consente, ad una applicazione esterna, di inviare in

automatico il flusso a NRP.

In questo caso gli utenti dovranno utilizzare il servizio di NRP per la sola fase di validazione del flusso per la

sua pubblicazione.

2 Vedi documento “Polo regionale ligure dei pagamenti: formato file di scambio dati”

23

4.13. Gestionepraticheinattesa

Questa funzione consente a un operatore di accedere alla lista delle “pratiche in attesa” caricate tramite

questa funzione o quella descritta qui sopra.

Ogni pratica non ancora pagata, può essere:

Eliminata

Modificata nel contenuto

E’ anche possibile caricare ex novo una pratica e, per questo, il servizio:

1. Presenta una maschera con la quale riceve in input i dati della RPT;

2. Verifica la completezza dei dati inputati;

3. Genera un IUV;

4. Predispone e inserisce l’RPT parziale (senza PSP) su PAP (attraverso la funzione PAP di caricamento

del pagamento diretto)

5. Genera un codice “hash” di tutte le informazioni della RPT e lo memorizza su NRP.

4.14. StornodiunaRT

Lo storno è un’operazione attraverso la quale la PA può procedere all’annullamento (storno) di un

pagamento effettuato a proprio favore.

Il servizio consente all’operatore di ente di individuare il pagamento da stornare secondo alcuni parametri

di ricerca (IUV, soggetto pagatore, intervallo temporale).

La funzione è soggetta alle regole dello storno previste da AgiD e dai singoli PSP.

Esso si esplica nell’invio di una richiesta di revoca (RR) da parte dell’Ente Creditore, contenente i riferimenti

della RT oggetto della revoca e nella risposta da parte del PSP contenente l’esito della revoca (ER), che il

PSP può accettare di eseguire utilizzando i propri processi contabili e amministrativi interni, ovvero può

anche rifiutare.

ATTENZIONE: lo storno è applicabile sono nei confronti dei PSP che sono abilitati allo stesso.

5. ILPORTALEDIFRONT‐OFFICEDINRP

5.1. Pagamentiinattesa

Il servizio di front office è riservato ai destinatari delle RPT in attesa di pagamento.

Consente di:

Selezionare l’ente di riferimento,

24

Selezionare un IUV che risulta in “attesa di pagamento”,

Avviare il processo di pagamento secondo le modalità previste dal modello 1 (pagamento

immediato).

5.2. Pagamentispontanei

Il servizio di front office è riservato agli utilizzatori finali dei servizi di pagamento (cittadini ed imprese)

senza accesso profilato (accesso libero).

Consente di:

Selezionare l’ente per il quale si deve effettuare il pagamento

Scegliere la macro tipologia di pagamento tra quelli configurati dall’ente attraverso il servizio di

back office descritto in precedenza

Completare i dati relativi al pagamento (estremi del pagatore, importo, causale)

Decidere quale modello adottare per il pagamento tra quelli gestiti da NRP

Avviare, in caso di modello 1, il processo di pagamento immediato.

Stampare, in caso di modello 3, l’avviso di pagamento con l’IUV.

5.3. Linkaiservizidipagamento

Se ritenuto utile per gli utilizzatori finali sarà disponibile si NRP una sezione che indica gli indirizzi web (URL)

dei servizi di pagamento degli enti.

Questo servizio sarà abbiano ad una specifica funzione di back office che consentirà agli operatori dell’ente

di aggiornare gli indirizzi pubblicati per il proprio ente.

6. ISERVIZIAPPLICATIVIDINRP:WEBSERVICESREST

6.1. Introduzione

In questo capitolo, dedicato ai programmatori degli enti, descriveremo le componenti software denominate

“RestController”, il cui scopo è essenzialmente quello di raggruppare in oggetti ben definiti e facilmente

individuabili tutte le funzionalità presenti all’interno di NRP e afferenti a una specifica entità logica gestita

dal sistema ed esposti sotto forma di WS REST.

Un “RestController” contiene l’implementazione vera e propria dei singoli WS esposti ed è fisicamente

realizzato nella forma di Servlet Java specializzate nel gestire tutte le richieste (i.e. i WS) relative a una

specifica entità logica gestita dal sistema definita “contesto”.

25

I contesti previsti sono PSP, IUV, RPT, RT, Rendicontazione.

Come naming‐convention, la servlet denominata “[contesto]RestController”, implementa ed espone tutti i

metodi relativi all’entità “[contesto]”.

I RestController previsti sono quindi:

PspRestController

Scopo: esporre i metodi REST relativi ai PSP

Metodi esposti:

o papRestChiediListaPsp

IuvRestController

Scopo: esporre i metodi REST relativi agli IUV

Metodi esposti:

o papRestGeneraIUVPubblico

RptRestController

Scopo: esporre i metodi REST relativi alle RPT

Metodi esposti:

o papRestInviaRPT

o papRestCaricaPagamentoDiretto

o papRestAnnullaPagamentoDiretto

o papRestAggiornaPagamentoDiretto

o papRestChiediStatoRPT

o papRestChiediStoricoRPT

RtRestController

Scopo: esporre i metodi REST relativi alle RT

Metodi esposti:

o papRestChiediRT

o papRestChiediStoricoRT

RendicontazioneRestController

Scopo: esporre i metodi REST relativi ai Flussi di Rendicontazione

Metodi esposti:

o papRestChiediElencoFlussiRendicontazione

o papRestChiediFlussoRendicontazione

Nella seguente tabella descriviamo sinteticamente i metodi RESTful, suddivisi per contesto di riferimento

(i.e. colonna “Cntx”) ed evidenziando i metodi HTTP, le URI, e gli output in termini di Request Body,

Response Code.

Riguardo agli Error Code eventualmente restituiti, per tutti i metodi valgono le seguente regole:

L’Error Code restituito è:

o 400: in caso di errori;

o 405: se il metodo utilizzato è diverso da quello previsto;

26

o 500: in caso di problemi di connessione col DB. Questo codice è previsto per tutti i metodo

che interagiscono con il DB di NRP;

Nel Body della Response viene fornito un faultBean contenent:

o uno dei faultCode previsti dal metodo (e dettagliati nel paragrafo di descrizione di dettaglio

del relativo metodo)

o nella faultString un dettaglio maggiore, qualora disponibile.

N.B. Nella tabella <CP> = Common Path = http://<hostnameDelServer>:<porta>/pap‐web/rest ; i parametri

<hostnameDelServer>:<porta> verranno comunicati in sede opportuna alla PA aderente a NRP.

27

Metodo REST HTTP URI Request Body

Response Code se OK; Response Body (se presente)

papRestChiediListaPSP GET <CP>/psps + query params:

pagina (default 0)

risultati (default 10)

‐ RC: 200; RB: JSON contenente:

il numero totale di PSP presenti nel DB dal NRP

una lista di informative PSP

papRestAggiornaListaPSP POST <CP>/psps ‐ RC: 201

papRestGeneraIUV POST <CP>/iuvs


IUV pubblico (15 digits)

papRestCaricaPagamentoDiretto POST <CP>/rpts/pagamentodiretto JSON con dati RPT (no PSP)

RC: 201; RB: JSON con esito OK

papRestAnnullaPagamentoDiretto DELETE <CP>/rpts/pagamentodiretto/{iuv} ‐ RC: 201; RB: JSON con esito OK La cancellazione è logica: il pagamento viene messo in stato=annullato

papRestInviaRPT POST <CP>/rpts JSON con dati RPT

RC: 201; RB: JSON contenente l’esito della chiamata e l’eventuale url di redirect

28



papRestAttivaRPT

POST <CP>/rpts/pagamentodiretto/ JSON con iuv e solamente i dati integrativi RPT (PSP, contesto pagamento, …)


papRestInviaCarrelloRPT POST <CP>/rptm JSON con dati RPT


papRestChiediStoricoRPT GET <CP>/rpts + query params:

startDate

endDate

idUtente

statoPagamento

pagina (default 0)



il numero totale di RPT presenti nel DB di NRP coerenti con i filtri in input

una lista di RPT, costituita da un numero di elementi pari a risultati, o eventualmente meno, in caso dell’ultima pagina

29



papRestNodoChiediStatoRPT GET <CP>/nodorpts/{iuv}+ query param: ‐ codiceContestoPagamento

‐ RC: 200;RB: JSON contenente lo stato

papRestNodoChiediListaPendentiRPT GET <CP>/nodorpts + query params:‐ rangeDa ‐ rangeA ‐ pageSize

‐ RC: 200;RB: JSON con lista URI RPT pendenti

papRestChiediRT GET <CP>/rts/{iuv} ‐ RC: 200; RB: JSON contenente lo stato della Pratica associata e, se pari a”RT verificata”, la RT (se firmata, la RT sarà restituita insieme al tipo di firma) associata allo IUV passato.

papRestGetRT GET <CP>/rts/rt/{iuv} ‐ RC: 200; RB: JSON contenente lo stato della Pratica associata e la RT associata allo IUV passato.

papRestStornaRT PUT <CP>/rts/{iuv}

papRestChiediStoricoRT GET <CP>/rts + query params:

startDate

endDate

idUtente

codiceUnitOperBeneficiario

statoPagamento

pagina (default 0)



il numero totale di RT presenti nel DB di NRP coerenti con i filtri in input

una lista di RT, costituita da

30



un numero di elementi pari a risultati, o eventualmente meno, in caso dell’ultima pagina

papRestRecuperaRTDaNodo POST <CP>/rts/recuperadanodo/{iuv} + query param:

codiceContestoPagamento

‐ RC: 201;RB: JSON contenente lo stato iniziale (prima della chiamata) e finale (dopo la chiamata) della Pratica

papRestChiediFlussoRendicontazione GET <CP>/rends/{identificativoFlusso} + query params:

dataOraFlusso


il flusso di rendicontazione corrispondente all’identificatore del flusso richiesto (vedi Allegato tecnico Linee Guida Nodo Nazionale); se il parametro dataOraFlusso è nullo viene ritornato l’ultimo flusso

31



disponibile;

papRestChiediElencoFlussiRendicontazione GET <CP>/rends+ query params:

startDate

endDate

risultati

pagina


il numero totale di flussi presenti nel DB di NRP coerenti con i filtri in input

una lista di flussi, costituita da un numero di elementi pari a risultati, o eventualmente meno, in caso dell’ultima pagina

papRestScaricaNuoviFlussiRendicontazione POST <CP>/rends RC: 201; RB: JSON contenente: ‐ # flussi totali disponibili; ‐ # flussi nuovi;

papRestElaboraFlussiRendicontazione PUT <CP>/rends/elabora RC: 200; RB: JSON contenente: ‐ # flussi elaborati OK; ‐ # flussi elaborati KO;

32



papRestScaricaNuoviFlussiQuadraturaPA POST <CP>/quads + query params:

dominioPA

RC: 201; RB: JSON contenente: ‐ # flussi totali disponibili; ‐ # flussi nuovi;

papRestElaboraFlussiQuadraturaPA PUT <CP>/quads/elabora RC: 200; RB: JSON contenente: ‐ # flussi elaborati OK; ‐ # flussi elaborati KO;

papRestInterrogaGdE GET <CP>/gde + query string:

IUV startDate endDate risultati pagina


il numero totale di entry del GdE presenti nel DB di NRP coerenti con i filtri in input

una lista di entry del GdE, costituita da un numero di elementi pari a risultati, o eventualmente meno, in caso dell’ultima pagina

33

6.2. Convenzioni

Coerentemente con la definizione del paradigma RESTful: i metodi http GET, PUT, POST, DELETE

vengono utilizzati come di seguito descritto:

POST: (CREATE) creazione di una nuova risorsa sul server. Convenzionalmente restituisce la

rappresentazione della risorsa appena creata.

GET: (READ) recupero della rappresentazione di una risorsa presente sul server identificata tramite

una URI. È da intendersi come una operazione di sola lettura che non modifica in alcun modo il

database (a meno eventualmente dell’aggiunta di informazioni di log per il tracciamento delle

operazioni).

PUT: (UPDATE) aggiornamento di una risorsa presente sul server identificata tramite una URI

DELETE: (DELETE) cancellazione di una risorsa presente sul server identificata tramite una URI.

In particolare, distinguendo singole risorse da liste di risorse, tali metodi http vengono utilizzati come

schematizzato nella seguente tabella:

Risorsa URI riferita a lista di Risorse:

http://server/resources URI riferita ad una singola risorsa:

http://server/resources/item17

GET Recupera la lista le URI ed eventualmente altri dettagli dei membri della lista.

Recupera la rappresentazione della specifica risorsa identificata dalla URI.

PUT Sostituisce l’intera lista con una nuova Sostituisce la risorsa identificata dalla URI, se non esiste, la crea.

POST Crea una nuova risorsa da aggiungere alla lista. La URI della nuova risorsa è assegnata automaticamente e solitamente restituita in risposta della chiamata.

Generalmente non usato per single risorse appartenenti a una lista. Considera l’entità referenziata dalla URI come una lista a sé stante e crea un nuovo elemento in essa.

DELETE Cancella l’intera lista (salvo diverse indicazioni specifiche).

Cancella la risorsa specificata dalla URI dalla lista di appartenenza (salvo diverse indicazioni specifiche).

(WS REST) risorse vs liste di risorse vs metodi HTTP

Per quanto riguarda casi in cui fosse necessario restituire degli errori che si dovessero eventualmente

verificare a fronte di una chiamata REST, il paradigma RESTful prevede la restituzione di errori standard

HTTP, all’interno dei quali far ricadere tutti i casi possibili, insieme ad una descrizione dello specifico errore

verificatosi contenuta nel corpo della response alla chiamata al WS REST stesso.

Nel NRP, i metodi HTTP da utilizzare in fase di invocazione, così come i codici di ritorno restituiti, variano a

seconda della logica di business che i singoli WS REST dal NRP implementano. Data la natura dal NRP, non

saranno restituiti tutti i codici previsti dalle specifiche HTTP, ma solo il sottoinsieme necessario.

Nella seguente tabella si riporta la mappatura dei vari codici di ritorno di chiamate HTTP che saranno

restituiti dal NRP in risposta all’invocazione dei WS REST.

Codice Descrizione

200 Request andata a buon fine.

201 (in risposta ad una chiamata via POST o PUT) risorsa create con successo.

400 Richiestamal formattata

404 Risorsa non trovata (risorsa inesistente).

405 Metodo HTTP errato (ad esempio utilizzato per indicare che si è cercato di usare un

PUT in luogo di un POST, un GET in luogo di un PUT ecc.)

34

Codice Descrizione

500 Errore nel server. Tipicamente non si riferisce ad un errore logico nella richiesta,

quanto ad un errore sul server che gestisce le richieste (ad es. una eccezione non

codici di ritorno HTTP dei WS REST

In generale, relativamente alla gestione degli errori (codici 4xx), i WS REST esposti dal NRP, oltre al

particolare codice HTTP restituiranno nel body della response una descrizione quanto più dettagliata

dell’errore, sotto forma di faultBean in formato JSON.

Un generico faultBean, coerentemente con le specifiche attuative del Nodo dei Pagamenti‐SPC, si compone

delle seguenti proprietà faultCode, faultString, id, description. In formato JSON un faultBean assumerà

dunque la forma:

Per ogni metodo vengono indicati i seguenti elementi:

Descrizione: descrizione sintetica generale del metodo Gestione errore: in caso di errore, nel body della response della chiamata http, viene

restituito un faultBean in formato JSON. Per ogni metodo si elencano i faultCode restituiti, assumendo che la faultString conterrà il dettaglio dell’errore.

Definizione WS REST: tabella descrittiva del web service, definito in termini di: o Request: rappresenta le modalità di chiamata de web service, definita in termini di:

Metodo HTTP URI Parametri Request Body

o Response OK: rappresenta l’output del web service nel caso di esecuzione corretta, definito in termini di: Status code Response body

o Response OK: rappresenta l’output del web service nel caso di esecuzione errata, definito in termini di: Status code Response body

Nell’allegato “Disciplinare Tecnico Polo Pagamenti ‐ Allegato‐RPT‐RT.xsd” è riportato lo schema a cui deve

aderire la RPT compilata dalla PA.

Ilcampo“servizioPA”

Nelle sezioni precedenti viene citato più volte il campo “servizio PA” in input a diverse funzioni. Il motivo

per cui viene citato è che NRP attua un controllo particolare su quel campo, imponendo che ci sia coerenza

in tutte le fasi del pagamento. Da un punto di vista strettamente implementativo, la specificazione del

servizio che all’interno delle PA utilizza i pagamenti elettronici è già presente nella RPT prevista dalle Linee

Guida Nazionali (più precisamente negli allegati tecnici) e, in particolare, nel campo

codiceUnitOperBeneficiario.

{ faultCode: faultCode,

faultString: faultString,

description: description

}

35

Di seguito, quindi, il campo “servizio PA” non viene più citato e si intende che la PA, per questo, utilizzi il

sopra citato campo della RPT, qualora ritenuto necessario.

CodificheinterneallaPAdelpagamento

Si ricorda che eventuali codifiche interne alla PA del pagamento (diverse dall’IUV) possono essere inserite

nel campo “datiSpecificiPagamento” della RPT (vedi Allegato B alle Linee Guida Nazionali).

6.3. Imetodiesposti

papRestChiediListaPSP()

Descrizione: metodo utilizzato dal Portale PA per recuperare la lista dei PSP aderenti e già censiti dal Nodo, presenti sul DB del NRP.

Gestione errore:

o PAP_UNEXPECTED_ERROR: se il DB dal NRP non è raggiungibile o PAP_ERROR_SIZE: se risultati o pagina sono valorizzati in modo errato

Request Metodo HTTP GET

URI <CP>/psps

Parametri pagina: indica il numero di pagina (deve essere >= 1 e < del

numero di pagine disponibili relativamente al parametro

risultati)

risultati: indica il numero di risultati per pagina da restituire

(deve essere > 0 e < 100)

Request Body ‐

Response OK Status Code 200

Response Body JSON contenente:

il numero totale di PSP presenti nel DB dal NRP

una lista di informative PSP, costituita da un numero di elementi

pari a risultati, o eventualmente meno, in caso dell’ultima pagina

Response KO Status Code Response Body

400 faultBean in formato JSON 405: se http method diverso da GET oPOST;

‐

500: in caso di problemi diconnessione col DB;

faultBean in formato JSON

papRestAggiornaListaPSP()

Descrizione: metodo utilizzato dal Portale PA per aggiornare la lista dei PSP aderenti

Gestione errore:

o PAP_UNEXPECTED_ERROR: se il DB dal NRP non è raggiungibile, se il salvataggio dei PSP va in errore, se la cancellazione dei PSP pre esitenti ca in errore

o PAP_NODO_NON_RAGGIUNGIBILE: se l’invocazione del nodo per il recupero della lista non vca a buon fine

Request Metodo HTTP POST

URI <CP>/psps

Parametri ‐

36

Request Body ‐


Response Body JSON contenente le informative PSP preseenti sul DB



‐



papRestGeneraIUV()

Descrizione: metodo utilizzato dal Portale PA per la generazione di un identificativoUnivocoVersamento in formato 15 digits

Gestione errore:

o PAP_UNEXPECTED_ERROR: se il DB del NRP non è raggiungibile o PAP_ERROR_SIZE: se risultati o pagina sono valorizzati in modo errato


URI <CP>/iuvs

Parametri ‐

Request Body ‐


Response Body {iuv: identificativoUnivocoVersamento

}


405: se http method diverso da POST; ‐500: in caso di problemi diconnessione col DB;


papRestCaricaPagamentoDiretto()

Descrizione: Permette di caricare nel DB del NRP, in una opportuna Pratica, una RPT parziale per cui sono definiti tutti i dati tranne i riferimenti al PSP (incluso il codiceContestoPagamento, la cui valorizzazione è a carico del PSP). La RPT parziale viene verificata in formato e struttura e successivamente storicizzata. Se l'operazione va a buon fine la Pratica passa nello stato “In attesa di PSP”.

Gestione errore:

o PAP_UNEXPECTED_ERROR: nel caso di DB del NRP non raggiungibile o PAP_IUV_ASSENTE: nel caso di IUV nullo o vuoto o PAP_IUV_DUPLICATO: nel caso di IUV duplicato (lo IUV in input risulta già associato a

un’altra RPT) o PAP_RPT_MALFORMATA, RPT in input strutturalmente errata (per esempio non contiene

dati obbligatori)

37


URI <CP>/rpts/pagamentodiretto

Parametri ‐

Request Body JSON contentente i dati della RPT parziale


Response Body {“esito”: “OK” }


400 faultBean in formato JSON 405: se http method diverso da POST; ‐500: in caso di problemi diconnessione col DB;


papRestAnnullaPagamentoDiretto()

Descrizione: sposta la Pratica individuata dallo IUV specificato nella URI dallo stato “In attesa di PSP” allo stato “Pagamento diretto annullato”, che rappresenta lo stato di un pagamento diretto attivato presso PSP che si è deciso di annullare all’interno del NRP (ad esempio perché il pagamento è stato effettuato tramite un sistema esterno al Nodo dei Pagamenti SPC).

Gestione errore:

o PAP_UNEXPECTED_ERROR: nel caso di DB del NRP non raggiungibile o PAP_STATO_ERRATO: Pratica in uno stato diverso da “In attesa di PSP” o PAP_IUV_ASSENTE: nel caso di IUV nullo o vuoto

Request Metodo HTTP DELETE

URI <CP>/rpts/pagamentodiretto/{iuv}

Parametri ‐

Request Body ‐


Response Body {“esito”: “OK” }


400 faultBean in formato JSON 405: se http method diverso da DELETE; ‐500: in caso di problemi diconnessione col DB;


papRestInviaRPT()

Descrizione: metodo utilizzato dal Portale PA per l’invio al Nodo di una Richiesta di Pagamento Telematico. Il metodo viene invocato con una RPT completamente valorizzata (anche per quanto riguarda il PSP). Storicizza nel DB del NRP (all’interno di una specifica Pratica) e poi invia al Nodo dei Pagamenti‐SPC la RPT fornita in input.

Gestione errore:

o PAP_UNEXPECTED_ERROR: nel caso di DB del NRP non raggiungibile o PAP_NODO_NON_RAGGIUNGIBILE: nel caso di Nodo non raggiungibile o PAP_RPT_MALFORMATA, RPT in input strutturalmente errata (ad esempio non

38

contiene dati obbligatori)

Request Metodo HTTP PUT

URI <CP>/rpts/

Parametri ‐

Request Body JSON dati RPT completamente valorizzata


Response Body JSON contenente l’esito della chiamata e l’eventuale url di redirect


400 faultBean in formato JSON 405: se http method diverso da PUT; ‐500: in caso di problemi diconnessione col DB;


papRestChiediStoricoRPT()

Descrizione: restituisce lo storico delle RPT generate dal NRP coerenti con i filtri in input Gestione errore:

o PAP_UNEXPECTED_ERROR, se il DB del NRP non raggiungibile o PAP_ERRORE_DATA, in caso di errori sull’intervallo di date in input o PAP_ERROR_SIZE, in caso di risultati o pagina valorizzati in modo errato


URI <CP>/rpts

Parametri startDate: la data inizio di invio delle RPT endDate: la data fine di invio delle RPT idUtente: l’identificativo del soggetto pagatore delle RPT statoPagamento: lo stato della Pratica relativa alle RPT risultati (se non fornito, default = 10): indica il numero di risultati per pagina da restituire (deve essere > 0 e < 100)

pagina (se non fornito, default = 1): indica il numero di pagina (deve essere >= 1 e < del numero di pagine disponibili relativamente al parametro risultati)

Request Body ‐


Response Body JSONcontenente: il numero totale di RPT presenti nel DB del NRP coerenti con i filtri in input

una lista di RPT, costituita da un numero di elementi pari a risultati, o eventualmentemeno, in caso dell’ultima pagina



‐



papRestNodoChiediStatoRPT()

Descrizione: metodo utilizzato dal Portale PA per richiedere al Nodo la sua visione di una specifica RPT

Gestione errore:

39

o PAP_NODO_NON_RAGGIUNGIBILE, se il nodo non è raggiungibile o Inoltre, essendo di fatto un wrapper il seguente metodo può restituire i codici di errori previsti dal

nodo:

PPT_RPT_SCONOSCIUTA PPT_SINTASSI_EXTRAXSD PPT_SEMANTICA PPT_AUTENTICAZIONE PPT_AUTORIZZAZIONE PPT_DOMINIO_SCONOSCIUTO PPT_DOMINIO_DISABILITATO PPT_INTERMEDIARIO_PA_SCONOSCIUTO PPT_INTERMEDIARIO_PA_DISABILITATO PPT_STAZIONE_INT_PA_SCONOSCIUTA PPT_STAZIONE_INT_PA_DISABILITATA PPT_SUPERAMENTOSOGLIA


URI <CP>/nodorpts/{iuv}

Parametri CodiceContestoPagamento

Request Body ‐


Response Body JSON contenente lo stato restituito dal Nodo, come definito in SANP



‐

papRestChiediRT()

Descrizione: metodo utilizzato dal Portale PA per richiedere al NRP una copia di una RT. Se l’RT è presente sul DB del NRP ed è nello stato “RT verificata”, viene restituita in JSON in formato base64 (se firmata, insieme al tipo di firma). Altrimenti, se lo stato è tra quelli ammessi (“RT verificata”, “In attesa di RT” o “RT Errata”) restituisce solo lo stato.

Gestione errore:

o PAP_UNEXPECTED_ERROR: in caso di DB del NRP non raggiungibile o PAP_IUV_ASSENTE: se non esiste una Pratica relativa allo IUV in input o PAP_STATO_ERRATO: se lo stato è diverso da “RT verificata”, “In attesa di RT” o “RT Errata” o PAP_RT_NON_DISPONIBILE: se non è presente nella relativa Pratica


URI <CP>/rts/{iuv}

Parametri ‐

Request Body ‐

Response OK Status Code 200: se presente nel db del NRP

Response Body JSON contenente lo stato della Pratica associata e, se pari a”RTverificata”, la RT (se firmata, la RT sarà restituita insieme al tipo di firma) associata allo IUV passato.


404: se nella Pratica associata allo IUV in faultBean in formato JSON

40

input (codificato nella URI) non esiste, èin stato errato o non è presente la RT405: se http method diverso da GET ‐500: in caso di problemi diconnessione col DB;


papRestGetRT()

Descrizione: metodo utilizzato dal Portale PA per richiedere al NRP una copia di una RT.

Gestione errore:

o PAP_UNEXPECTED_ERROR: in caso di DB del NRP non raggiungibile o PAP_IUV_ASSENTE: se non esiste una Pratica relativa allo IUV in input o PAP_RT_NON_DISPONIBILE: se non è presente nella relativa Pratica


URI <CP>/rts/rt/{iuv}

Parametri ‐

Request Body ‐ Response OK Status Code 200: se presente nel db del NRP

Response Body JSON contenente lo stato della Pratica associata e la RT associataallo IUV passato.


404: se nella Pratica associata allo IUV ininput (codificato nella URI) non esiste o non è presente la RT


405: se http method diverso da GET ‐500: in caso di problemi diconnessione col DB;


papRestRecuperaRTDaNodo()

Descrizione: metodo utilizzato dal Portale PA per richiedere al Nodo dei Pagamenti SPC la sua versione della RT associata allo IUV e CCP in input. In assenza di errori, la RT recuperata viene associata alla Pratica corrispondente (individuata tramite lo IUV), eventualmente sovrascrivendo la RT precedentemente associata se presente (in tal caso la precedente RT viene spostata come blob nella tabella RT_ERRATE). Se l’operazione avviene senza errori viene restituita la RT in JSON in formato base64, insieme al tipo di firma nel caso di RT firmata

Gestione errore:

o PAP_FAULT_NODO_NON_RAGGIUNGIBILE: se l’invocazione non va a buon fine o in timeout

o PAP_UNEXPECTED_ERROR: in caso di DB della PAP non raggiungibile

o PAP_IUV_ASSENTE: se non esiste una Pratica relativa allo IUV in input

o PAP_STATO_ERRATO: se lo stato è diverso da “RT verificata”, “In attesa di RT” o “RT Errata”

o PAP_RT_MALFORMATA: se la verifica logico‐strutturale della RT non va a buon fine

o PAP_SEMANTICA: se qualcosa della RT non corrisponde alla RPT o PAP_ID_DOMINIO_ERRATO: se il dominio della RT non corrisponde a quello della RPT


URI <CP>/rts/recuperadanodo/{iuv}

Parametri codiceContestoPagamento

41

Request Body ‐‐ Response OK Status Code 201

Response Body JSON contenente lo stato iniziale a finale della Pratica associata


404: se nella Pratica associata allo IUV in input (codificato nella URI) non esiste, è in sato errato


405: se http method diverso da POST500: in caso odi problemi di connessione col DB

‐faultBean in formato JSON

papRestChiediStoricoRT()

Descrizione: restituisce lo storico delle RT ricevute dal NRP, coerenti con i filtri in input Gestione errore:

o PAP_UNEXPECTED_ERROR, se il DB del NRP non raggiungibile o PAP_ERRORE_DATA, in caso di errori sull’intervallo di date in input o PAP_ERROR_SIZE, in caso di risultati o pagina valorizzati in modo errato


URI <CP>/rts

Parametri startDate: la data inizio di ricezione delle RT endDate: la data fine di ricezione delle RT idUtente: l’identificativo del soggetto pagatore delle RT codiceUnitOperBeneficiario: l’identificativo della struttura della PA

statoPagamento: lo stato della Pratica relativa alle RT risultati (se non fornito, default = 10): indica il numero di risultati per pagina da restituire (deve essere > 0 e < 100)


Request Body ‐


Response Body JSONcontenente: il numero totale di RT presenti nel DB del NRP coerenti con i filtri in input

una lista di RT, costituita da un numero di elementi pari a risultati, o eventualmentemeno, in caso dell’ultima pagina


400 faultBean in formato JSON 405: se http method diverso da GET; ‐500: in caso di problemi diconnessione col DB;


papRestNodoChiediListaPendentiRPT()

Descrizione: metodo utilizzato dal Portale PA per richiedere al Nodo la sua visione delle RPT in attesa di RT

42

Gestione errore:

o PAP_NODO_NON_RAGGIUNGIBILE: nel caso di Nodo non raggiungibile

o PAP_ERRORE_DATA: nel caso di errori sulle date

o PAP_ERROR_SIZE: nel caso di errori sulla dimensione dei record richiesti

o noltre, essendo di fatto un wrapper il seguente metodo può restituire i codici di errori previsti dal

nodo:

PPT_SINTASSI_EXTRAXSD PPT_SEMANTICA PPT_AUTENTICAZIONE PPT_AUTORIZZAZIONE PPT_DOMINIO_SCONOSCIUTO PPT_DOMINIO_DISABILITATO PPT_INTERMEDIARIO_PA_SCONOSCIUTO PPT_INTERMEDIARIO_PA_DISABILITATO PPT_STAZIONE_INT_PA_SCONOSCIUTA PPT_STAZIONE_INT_PA_DISABILITATA PPT_SUPERAMENTOSOGLIA


URI <CP>/nodorpts

Parametri rangeDa: La data iniziale degli RPT restituiti rangeA: La data finale degli RPT restituiti pageSize: Il numero massimo dei risultati restituiti

Request Body ‐ Response OK Status Code 200: se presente nel db del NRP

Response Body JSON contenente la lista delgi RPT pendenti


400 faultBean in formato JSON 405: se http method diverso da GET ‐

papRestChiediElencoFlussiRendicontazione()

Descrizione: fornisce alla PA la lista dei flussi memorizzati in NRP e, per ciascuno, il parametro dataOraFlusso associato.

Gestione errore:

o PAP_UNEXPECTED_ERROR: in caso di DB del NRP non raggiungibile

43


URI <CP>/rends/

Parametri startDate: la data inizio di ricezione delle RT endDate: la data fine di ricezione delle RT risultati (se non fornito, default = 10): indica il numero di risultati per pagina da restituire (deve essere > 0 e < 100)


Request Body ‐


Response Body JSONcontenente: il numero totale di Flussi presenti nel DB del NRP coerenti con i filtri in input

una lista di informazioni sui Flussi, costituita da un numero di elementi pari a risultati, o eventualmente meno, in caso dell’ultima pagina.




papRestChiediFlussoRendicontazione()

Descrizione: ritorna il flusso di rendicontazione corrispondente all’identificatore del flusso richiesto (vedi Allegato tecnico Linee Guida Nodo Nazionale); Il metodo ha lo scopo di ritornare il Flusso di Rendicontazione che corrisponde all’identificativo identificativoFlusso contenuto nella causale del bonifico cumulativo (bonifico relativo a più RT), in formato XML, costituito essenzialmente da una lista di singoli pagamenti, per ognuno dei quali è specificato l’importo. Se il parametro dataOraFlusso è nullo viene ritornato l’ultimo flusso di rendicontazione disponibile.

Gestione errore:

o PAP_UNEXPECTED_ERROR: in caso di DB del NRP non raggiungibile o PAP_IDFLUSSO_ASSENTE: se non esiste un Flusso relativo all’identificatore

identificativoFlusso in input

44


URI <CP>/rends/{identificativoFlusso}

Parametri dataOraFlusso: la data e l’ora associati al Flusso Request Body ‐


Response Body JSONcontenente: il flusso di rendicontazione corrispondente all’identificatore del flusso richiesto (vedi Allegato tecnico Linee Guida Nodo Nazionale); se il parametro dataOraFlusso è nullo viene ritornato l’ultimo flusso disponibile. Nel caso di verifica con esito negativo il dettaglio delle anomalie.




Il solo identificativoFlusso non è sufficiente a determinare se esso sia l’ultimo, dato che è ammissibile che nel DB sia

presente un flusso con lo stesso identificativo, al fine di poter gestire ricezioni ed elaborazioni successive di versioni

diverse dello stesso flusso di rendicontazione.

Per comprendere la necessità di tale implementazione, si consideri a titolo di esempio il seguente scenario:

1. Al tempo t0 NRP mette a disposizione della PA un flusso F0 individuato dalla coppia [identificativoFlusso,

dataOraFlusso0], contenente però delle anomalie rilevate dall’elaborazione dei flussi di rendicontazione;

2. l’amministratore della PA, dopo aver rilevato il problema, contatta il PSP che ha emesso il flusso F0 segnalando

l’anomalia;

3. l’amministratore del PSP verifica che l’anomalia effettivamente è presente, individua il problema, lo risolve e

invia una nuova versione del flusso al Nodo dei Pagamenti SPC (Nodo Nazionale);

4. al tempo t1 NRP riceve dal Nodo dei Pagamenti SPC un nuovo flusso F1 individuato dalla coppia

[identificativoFlusso, dataOraFlusso1]

5. a questo punto NRP, grazie al fatto che un flusso non é identificato dal solo identificativoFlusso ma dalla coppia

[identificativoFlusso, dataOraFlusso] è in grado di distinguere il flusso F0 dal flusso F1, mantenendo al tempo

stesso la storia di entrambi.

Una volta individuati i flussi “nuovi”, viene invocato sul Nodo il metodo nodoChiediFlussoRendicontazione(), con il

quale il Nodo dei Pagamenti‐SPC restituisce lo specifico flusso di rendicontazione in formato XML, costituito

essenzialmente da una lista di singoli pagamenti, per ognuno dei quali è specificato l’importo.

Per ogni nuovo flusso NRP procede a un’elaborazione volta a verificare la coerenza delle istanze di

SingoloPagamento incrociandole con i corrispondenti SingoloPagamento associati alle RT che si trovano nello stato

“RT Verificata”. In caso di verifiche positive, imposta lo stato del flusso a “Elaborato OK”, altrimenti allo stato

“Elaborato KO” (il flusso contiene almeno un singolo pagamento incoerente con le informazioni presenti su NRP).

papRestInterrogaGdE()

Descrizione: restituisce una lista di eventi memorizzati nel Giornale degli Eventi della PAP, come specificato dai parametri di selezione/filtraggio forniti in input

Gestione errore: o PAP_UNEXPECTED_ERROR: in caso di DB del NRP non raggiungibile

45

o PAP_ERRORE_DATA: in caso di errori sull’intervallo di date in input o PAP_ERROR_SIZE: in caso di risultati o pagina valorizzati in modo errato


URI <CP>/gde

Parametri IUV: identificativo univoco di versamento startDate: la data inizio di ricezione delle RT endDate: la data fine di ricezione delle RT risultati (se non fornito, default = 10): indica il numero di risultati per pagina da restituire (deve essere > 0 e < 100)


Request Body ‐


Response Body JSONcontenente: il numero totale di entry del GdE presenti nel DB della PAP coerenti con i filtri in input

una lista di entry del GdE, costituita da un numero di elementi pari a risultati, o eventualmente meno, in caso dell’ultima pagina




papRestScaricaNuoviFlussiRendicontazione()

Descrizione: recupera dal Nodo e salva sul DB della PAP i Flussi di Rendicontazione non ancora presenti, per futura elaborazione

Gestione errore:

o PAP_UNEXPECTED_ERROR: in caso di DB della PAP non raggiungibile o PAP_FAULT_NODO_NON_RAGGIUNGIBILE, in caso di fallimento dell’invocazione al Nodo o faultCode restituiti dal Nodo, in caso di errore nell’esecuzione metodo sul Nodo


URI <CP>/rends

Parametri ‐

Request Body ‐


Response Body JSONcontenente: il numero totale dei Flussi il numero totale dei Flussi scaricati




46

papRestScaricaNuoviFlussiQuadraturaPA()

Descrizione: recupera dal Nodo e salva sul DB della PAP i Flussi di Quadratura non ancora presenti, per futura elaborazione

Gestione errore:

o PAP_UNEXPECTED_ERROR: in caso di DB della PAP non raggiungibile o PAP_FAULT_NODO_NON_RAGGIUNGIBILE, in caso di fallimento dell’invocazione al Nodo o faultCode restituiti dal Nodo, in caso di errore nell’esecuzione metodo sul Nodo


URI <CP>/quads

Parametri dominioPA

Request Body ‐


Response Body JSONcontenente: il numero totale dei Flussi il numero totale dei Flussi scaricati




papRestElaboraFlussiRendicontazione()

Descrizione: per ogni flusso di rendicontazione nello stato “Non elaborato”, verifica la coerenza delle istanze di SingoloPagamento, incrociandole con i corrispondenti SingoloPagamento associati alle RT che si trovano nello stato “RT Verificata”. A fronte di ogni SingoloPagamento verificato positivamente, aggiorna lo stato della relativa RT

Gestione errore:



URI <CP>/rends/elabora

Parametri ‐

Request Body ‐


Response Body JSONcontenente: il numero dei Flussi elaborati OK il numero dei Flussi elaborati KO




47

papRestElaboraFlussiQuadraturaPA()

Descrizione: per ogni flusso di rendicontazione nello stato “Non elaborato”, verifica la coerenza delle istanze di SingoloPagamento, incrociandole con i corrispondenti SingoloPagamento associati alle RT che si trovano nello stato “RT Verificata”. A fronte di ogni SingoloPagamento verificato positivamente, aggiorna lo stato della relativa RT

Gestione errore:



URI <CP>/quads/elabora

Parametri ‐

Request Body ‐


Response Body JSONcontenente: il numero dei Flussi elaborati OK il numero dei Flussi elaborati KO




7. ISERVIZIAPPLICATIVIDINRP:BRIDGENRPI servizi del Bridge NRP sono raggiungibili dalle applicazioni dell’ente indicando i seguenti parametri con metodo

post (consigliato) o metodo get.

Conformemente al sistema Qui Pago, tramite questa interfaccia, è possibile avviare la modalità di

pagamento immediato per uno solo pagamento destinato ad un unico beneficiario.

Non è possibile, attraverso questa interfaccia, ad esempio, effettuare più pagamenti contemporanei per un

beneficiario (RPT con più di un pagamento fino ad un massimo di 5), ne pagare per più beneficiari (carrello

di RPT), ne pagare una marca da bollo.

Parametro Descrizione Formato Obbligatorio

codTrans identificativo del pagamento

(univoco per ogni pagamento)

da 2 a 30 caratteri

alfanumerici

(escluso “#”)

obbligatorio

importo Importo in centesimi di euro

(es., 25.73 ‐> 2573)

obbligatorio

divisa Divisa 3 caratteri (EUR) obbligatorio

alias Valore fisso comunicato da

Regione

url_back url in caso di annullamento vedi dopo obbligatorio

url url a cui inviare i parametri di obbligatorio

48

Parametro Descrizione Formato Obbligatorio

risposta con il risultato della

transazione

urlpost url (post) a cui inviare i

parametri di risposta con il

risultato della transazione

mac Message Code Authentication max 40 caratteri obbligatorio

mail indirizzo e‐mail del pagatore Da 1 a 150 caratteri obbligatorio

languageId codice linguaggio sempre il valore

“ITA”

nome Nome del pagatore max 140 caratteri

cognome Cognome del pagatore max 140 caratteri

identificativoFiscalePagatore Identificativo fiscale del

pagatore (CF o PIVA)

max 34 caratteri

anagraficaPagatore Anagrafica del pagatore max 140 caratteri

tipoPagatore Natura giuridica del pagatore

F (persona fisica) G (persona

giuridica)

max 1 carattere

Il parametro url_back indica un indirizzo che verrà richiamato alla pressione del tasto “annulla” a cui

verranno accodati i seguenti parametri:

Variabile Valoreimporto importodaautorizzaredivisa EURcodTrans codiceidentificativodelpagamentoassegnatodalgestoredelnegozioesito ANNULLOoERRORE

Se tale parametro non viene valorizzato, alla pressione del tasto “annulla”, non verrà

effettuata nessuna operazione. (facoltativo)

Il parametro iuv, se presente deve contenere un IUV valido (campo PA=1 e codice controllo corretto). Se

assente, l’IUV verrà generato da NRP (campo PA=0).

L’esito della richiesta di pagamento, viene comunicato dal PSP attraverso il Nodo Nazionale prima e NRP

dopo al Portale PA e reindirizzando l’acquirente all’URL applicativo, al quale vengono inviati, in modalità

GET, i seguenti parametri:

Parametro Descrizione Formato e Valore

alias identificatore PA AN max 30 caratteri

codTrans Codice transazione Da 2 a 30 caratteri

importo importo in centesimi di euro

(es., 25.73 ‐> 2573)

codAut Codice autorizzazione Da 2 a 6 caratteri

mac Message Code

Authentication

brand

tContab

49

Parametro Descrizione Formato e Valore

esito esito transazione 2 caratteri (“OK” o

“KO”)

divisa Divisa 3 caratteri (“EUR”)

data data della transazione yyyymmdd

orario orario della transazione hhmmsss

email indirizzo e‐mail del

pagatore

Da 1 a 150 caratteri

cognome cognome del pagatore Da 1 a 30 caratteri

nome nome del pagatore Da 1 a 30 caratteri

IUV identificativo univoco del

pagamento di PagoPA

uidriscossione identificativo univoco del

pagamento per il PSP

ParametriAggiuntivi Eventuali parametri

aggiuntivi

8. ILSISTEMADITESTDINRP

Per gli Enti sviluppatori NRP pubblica un ambiente DEMO che permette di interfacciare le applicazioni con il

nodo nazionale di test.

9. APPENDICEA–CODICIDIERRORERESTITUITIDALLEPRIMITIVE

faultCode faultString

PAP_IUV_DUPLICATO Tentativo di utilizzo di uno IUV già associato ad una RPT

PAP_IUV_ASSENTE Codice di errore restituito se in fase di creazione di unanuova RPT non viene passato in input uno IUV o lo IUV passato è vuoto

PAP_RPT_MALFORMATA Codice di errore restituito se la verifica dell' RPT inviata fallisce rispetto all'XSD definito nelle specifiche del Nodo dei SPC

PAP_RT_MALFORMATA Codice di errore restituito se la verifica dell' RT inviato falliscerispetto all'XSD definito nelle specifiche del Nodo dei Pagamenti SPC

PAP_RT_DUPLICATA Codice di errore restituito in fase di invio della RT da parte delNodo, se e' gia' presente una Pratica in stato “Rt Verificata”

PAP_PSP_NON_DISPONIBILE Codice di errore restituito se la verifica di esistenza di un PSPsul DB del NRP fallisce

PAP_UNEXPECTED_ERROR Codice di errore restituito in caso in cui non sia possibile individuare puntualmente l'errore verificatosi

PAP_FAULT_NODO_NON_RAGGIUNGIBILE Codice di errore restituito in caso di Nodo non raggiungibileper timeout o connessione non disponibile

50

PAP_ERRORE_DATA Codice di errore restituito in caso in cui la data sia malformata o non valida(es. data from maggiore di data to)

PAP_ERROR_SIZE Codice di errore restituito in caso in cui venga passata unasize minore o uguale a zero.

PAP_ERRORE_GDE Codice di errore restituito in caso in cui ci sia un errore nelsalvataggio o recupero di uno o piu' eventi nel GdE

PAP_STAZIONE_INT_ERRATA Codice di errore restituito se la stazione passata non corrisponde con quella configurata nei file di configurazione del NRP

PAP_ID_DOMINIO_ERRATO Codice di errore restituito se il dominio passato non corrisponde con quello configurato nei file di configurazione del NRP

PAP_SINTASSI_XSD Codice di errore restituito se la struttura di una una RPT o unaRT non corrisponde all'XSD definito nelle specifiche del Nodo dei Pagamenti SPC

PAP_STATO_ERRATO Codice di errore restituito se il metodo invocato è in uno stato non atteso rispetto al workflow dei pagamenti

PAP_ERRORE_IMPORTO_RT Codice di errore restituito se la RT contiene un importo totale diverso da quello riportato dalla rendicontazione

PAP_QUADRATURA_ERROR Codice di errore restituito se le verifiche di importi o totaliquadrature fallisce

PAP_PAGAMENTO_RT_ASSENTE Codice di errore restituito se la RT non contiene un pagamento con lo iur presente nella rendicontazione

PAP_PSP_ERRATO Codice di errore restituito se non viene trovato alcun PSP per iltipo di versamento passato

PAP_ERRORE_RENDICONTAZIONE Codice di errore restitutito se vi è un errore nella rendicontazione

PAA_ERRORE_FORMATO_BUSTA_FIRMATA Formato busta di firma errato o non corrispondente al tipoFirma.

PAA_ID_DOMINIO_ERRATO Codice di errore restituito se il dominio passato non corrisponde con quello configurato nei file di configurazione. Nel caso di verifica RT se non corrisponde con quello della RPT

PAA_ID_INTERMEDIARIO_ERRATO Codice di errore restituito se l'intermediario passato non corrisponde con quello configurato nei file di configurazione del NRP.

PAA_STAZIONE_INT_ERRATA Codice di errore restituito se la stazione intermediario noncorrisponde con quella configurata nei file di configurazione del NRP. Nel caso di verifica RT se non corrisponde con quello della RPT

PAA_RPT_SCONOSCIUTA Codice di errore restituito se non viene trovata nella base datidel NRP una RPT corrispondente alla RT inviata

PAA_RT_DUPLICATA Codice di errore restituito in fase di invio della RT da partedel Nodo, se e' gia' presente una Pratica in stato RT VERIFICATA

PAA_TIPOFIRMA_SCONOSCIUTO Il campo tipoFirma non corrisponde ad alcun valore previsto.

PAA_ERRORE_FORMATO_BUSTA_FIRMATA Formato busta di firma errato o non corrispondente al tipoFirma.

PAA_SINTASSI_XSD Codice di errore restituito se la struttura di una una RPT o unaRT non corrisponde all'XSD definito nelle specifiche del Nodo dei Pagamenti SPC

PAA_SEMANTICA Codice di errore restituito se la struttura di una una RT noncorrisponde alla sua RPT. Nello specifico potrebbero essere diversi gli identificativi del soggetto pagatore, versante, ente beneficiario o la versione oggetto della RT

51

10. APPENDICEB–GLISTATIDIUNAPRATICAALL’INTERNODINRP

11. APPENDICEC–ILPAGAMENTOIMMEDIATONELLAPAP

52

In questo caso il cittadino si collega con il proprio Internet browser al portale dell’Ente creditore e –

mediante il sistema dei pagamenti dell’Ente creditore ‐ inserisce tutte le informazioni relative al

proprio debito (utili alla predisposizione della RPT).

Descrizionecasod’uso


1. il cittadino si collega via browser al portale dell’Ente creditore per effettuare il pagamento

2. il portale dell’Ente creditore – attraverso la comunicazione tra PAP e NP ‐ lo indirizza verso il sito PSP configurato precedentemente su NP

3. il cittadino effettua il pagamento e viene reindirizzato al portale dell’Ente creditore

4. il portale dell’Ente creditore chiede al NP – tramite PAP – la RT

Sequencediagramdelcasod’uso

Nel seguente sequence diagram vengono illustrate le interazioni tra i vari attori del sistema.

53

Sequence Diagram – pagamento con esecuzione immediata

Per ogni passaggio viene data una breve descrizione.

1) Submit “Procedi col pagamento”: corrisponde all’azione con cui l’Utilizzatore Finale decide di procedere

con il pagamento.

1.1) Recupera sessione, carrello e canale: operazioni necessarie sul Portale PA per recuperare le

informazioni necessarie alla creazione della RPT (i.e. tutti gli input richiesti dal metodo REST

papRestInviaRPT() per la generazione della RPT, tranne lo IUV) ed in particolare la lista dei PSP

disponibili mediante la chiamata al metodo REST papRestChiedListaPSP()

54

1.2) papRestGeneraIUV(): il Portale PA richiede alla PAP un nuovo IUV a cui associare la successiva

richiesta di invio RPT.

1.2.1) Crea nuova Pratica e imposta stato a "IUV appena creato": contestualmente alla creazione di

uno IUV interno alla PAP, viene creata una nuova Pratica a cui viene associato lo IUV appena

creato ed il cui stato viene posto a “IUV appena creato”.

1.3) papRestInviaRPT(): il Portale PA richiede alla PAP la generazione della RPT, passando in input lo IUV

e tutti gli altri dati necessari alla creazione della RPT: dati beneficiario, soggetto pagatore, soggetto

versante (opzionale), dati di riferimento al PSP, ecc;

1.3.1) Verifica correttezza richiesta: la PAP effettua un controllo di correttezza strutturale e logica dei

dati in input e, in caso di errore (non contemplato in questo sequence diagram):

nessuna RPT viene salvata in forma esplosa nel database (non ha senso inserire in una

pratica una richiesta di pagamento errata), ma viene salvato il relativo XML nella tabella

RptErrate

viene restituita una response http con codice di errore e faultBean opportunamente

valorizzati.

Il flusso si interrompe.

1.3.2) Storicizza RPT() e cambia stato a “RPT storicizzata”: la PAP provvede a:

storicizzare la RPT in input nella sua forma esplosa (quindi non solo la stringa relativa al suo

XML, ma i suoi dati all’interno di una struttura articolata di tabelle in forma relazionale), in

quanto la considera strutturalmente e logicamente corretta;

salva nella Pratica individuata dallo IUV in input i riferimenti alla RPT in forma esplosa. La

pratica viene posta nello stato “RPT storicizzata”.

1.3.3) nodoInviaRPT(): la PAP invoca il WS SOAP passando la RPT al Nodo dei Pagamenti‐SPC;

1.3.3.1) il Nodo verifica la correttezza dell’RPT inviata dalla PAP. In caso di controlli falliti (caso non

rappresentato nel presente sequnce diagram), il Nodo, in risposta della chiamata al WS SOAP,

invia alla PAP un faultBean opportunamente valorizzato, al che la PAP pone la Pratica nello

stato “Invio RPT al Nodo KO” e restituisce al Portale PA un codice di errore ed un faultBean

opportunamente valorizzati, di fatto interrompendo il flusso e permettendo al Portale PA di

gestire l’errore (comunicandolo eventualmente all’Utilizzatore Finale).

1.3.3.2) pspInviaRPT(): il Nodo invia al FESP del PSP la RPT, che gli associa un SessionID (somma

dell’identificativo del carrello e dei parametri per il pagamento immediato). Il Nodo riceve

nella response i dati necessari alla costruzione dell’URL di redirect;

1.3.3.2.1) Verifica RPT(): il PSP verifica la correttezza della RPT appena inviatagli dal Nodo e in

caso di errore (caso non rappresentato nel presente sequnce diagram), il PSP restituisce un

faultBean al Nodo, che a sua volta restituisce un faultBean alla PAP, che pone la Pratica

nello stato “Invio RPT al Nodo KO” (il dettaglio dell’errore, insieme alla sua origine nel PSP

55

sono comunque reperibili dai dettagli dell’errore presenti nel faultBean che arriverà al

Portale PA) e restituisce al Portale PA un codice di errore ed un faultBean opportunamente

valorizzati, di fatto interrompendo il flusso e permettendo al Portale PA di gestire l’errore

(comunicandolo eventualmente all’Utilizzatore Finale).

1.3.3.3) Costruisce URL per redirect a FESP del PSP compreso il SessionID: Il Nodo compone la URL

di redirect e la invia al Browser dell’utilizzatore come risposta alla chiamata di cui al punto

1.3.3;

1.3.4) Cambia stato Pratica a “IN_ATTESA_DI_RT”: la PAP cambia lo stato della Pratica a

“IN_ATTESA_DI_RT”. Da questo momento in poi, a prescindere dalle successive azioni, che

avvengono al di fuori del suo controllo, la PAP, una volta restituita la response alla chiamata al WS

REST papRestInviaRPT(), considera la richiesta di pagamento inviata correttamente e si pone in

attesa della relativa RT. Dal suo punto di vista infatti la PAP ha terminato per il momento il flusso,

che proseguirà dietro diretto controllo del Portale PA, come illustrato di seguito.

1.4) predispone redirect a FESP: il Portale PA recupera la URL dalla response della chiamata al metodo

rest papRestInviaRPT() e costruisce la pagina di ritorno da visualizzare sul browser dell’Utilizzatore

Finale, in modo che questa esegua la redirect verso la pagina dei pagamenti offerta dal FESP.

2) Redirect: esecuzione dell’operazione di redirect del browser dell’Utilizzatore finale sulla pagina del FESP,

del sistema del PSP, deputata al pagamento;

3) Selezione strumento di pagamento e submit: l’Utilizzatore finale, dopo essersi accreditato, sceglie sulla

pagina del PSP, se del caso, lo strumento di pagamento fra quelli offerti dal PSP, quindi, innesca la

procedura di autorizzazione del pagamento;

3.1) Effettua il pagamento verso il Payment Gateway: l’Utilizzatore finale autorizza il pagamento sul

sistema del PSP prescelto e termina la sessione sul sistema del PSP;

3.2) Predispone il redirect verso il Nodo: il FESP predispone i dati necessari alla costruzione della URL di

redirect, come la SessionID (necessaria a tenere traccia del pagamento, di chi l’ha effettuato, per

conto di chi e a favore di quale PA).

4) Redirect a Nodo: il browser dell’Utilizzatore finale viene reindirizzato sul web server del Nodo, passando

nella request la SessionID.

4.1) Recupera dati associati alla SessionID e costruisce pagina contenente l’esito “OK” del pagamento;

4.2) Predispone redirect verso web application PA: il Nodo, recuperando tramite la SessionID associata,

la web application della PA di provenienza della RPT, predispone la URL di redirect specificando

l’esito dell’operazione di pagamento (i.e. “OK”)

5) Redirect verso pagina OK del Portale PA: il browser dell’utilizzatore finale viene reindirizzato verso il

Portale PA, specificando nella request http anche l’esito dell’operazione (i.e. “OK”), che di conseguenza

visualizzerà la pagina “IN_ATTESA_DI_RT (Ricevuta Telematica)”

56

Nella seguente figura è rappresentato il sequence diagram relativo al reperimento della Ricevuta

Telematica (RT), fornendo per ciascun passaggio una breve descrizione.

Si precisa che le interazioni tra l’Utilizzatore Finale e il Portale PA sono descritte facendo riferimento a una

fra le tante possibili implementazioni, descritta al solo scopo di rappresentare uno scenario di utilizzo

completo, necessario per soli fini espositivi delle funzionalità della PAP. Tale scenario implementativo è da

intendersi quindi come descrittivo di una fra le innumerevoli scelte progettuali a carico dell’Integratore PA,

che potrà naturalmente decidere di implementare le interazioni tra Portale PA e Utilizzatore Finale anche in

modi diversi.

Sequence Diagram ‐ richiedi RT (pagamento con esecuzione immediata)

Alla ricezione del messaggio “IN_ATTESA_DI_RT”, l’Integratore PA, nella modalità di pagamento immediato,

può scegliere di implementare una delle due modalità di richiesta della RT:

unsolicited (uno script Java che a cadenza periodica controlla che la RT sia stata consegnata)

solicited (un bottone con cui controllare se la RT sia arrivata o non ancora).

57

In ogni caso, relativamente a questa fase del processo di pagamento, per ogni RPT inviata con successo al

Nodo, la relativa Pratica può trovarsi in uno di due stati possibili: “IN_ATTESA_DI_RT” o “RT_VERIFICATA”.

Inizialmente la RT si troverà nel primo stato. Non appena il Nodo invierà la ricevuta, la relativa Pratica

passerà al secondo stato.

Ciò è sintetizzato nel sequence diagram “richiedi RT”, nel quale si identificano tre sezioni: quella relativa

allo stato iniziale “IN_ATTESA_DI_RT”, quella relativa all’evento che storicizza la RT e permette di cambiare

stato e quella relativa allo stato “RT_VERIFICATA”.

58

EsempidichiamateaiserviziespostidaNRPversoilportaledell’Entecreditore

1. papRestGeneraIUV()

Request:

Resource <CP>/rest/iuvs

Method POST

Query parameters ?iso11649=false

Body ‐

Response OK:

Body {"iuv": "015208000000000"}

Response KO:

Body HTTP Status 405 ‐ Method Not Allowed

2. papRestInviaRPT()

Request:

Resource <CP>/rest/rpts/

Method POST

Query parameters ‐

Body { "versioneOggetto": "5.2", "dominio": { "identificativoDominio": "00849050109", "identificativoStazioneRichiedente": "00849050109_01" }, "identificativoMessaggioRichiesta": "RPT_20150727_01", "dataOraMessaggioRichiesta": "2015-07-27T10:00:00", "autenticazioneSoggetto": "N/A", "soggettoPagatore": { "identificativoUnivocoPagatore": { "tipoIdentificativoUnivoco": "F", "codiceIdentificativoUnivoco": "00000001234" }, "anagraficaPagatore": "Anagrafica Pagatore Test 1" }, "enteBeneficiario": { "identificativoUnivocoBeneficiario": { "tipoIdentificativoUnivoco": "G", "codiceIdentificativoUnivoco": "00849050109"

59

}, "denominazioneBeneficiario": "Regione Liguria test" }, "datiVersamento": { "dataEsecuzionePagamento": "2015-07-27", "importoTotaleDaVersare": 1.00, "tipoVersamento": "CP", "identificativoUnivocoVersamento": "015208000000000", "codiceContestoPagamento": "n/a", "firmaRicevuta": 0, "datiSingoloVersamento": [ { "importoSingoloVersamento": 1.00, "ibanAccredito": "IT23X0000100001000000000999", "causaleVersamento": "/RFB/015208000000000/1.00", "datiSpecificiRiscossione": "9/1.00" } ]

},

"identificativoPSP":"idPsp1",

"identificativoCanale": "idCanale11",

"identificativoIntermediarioPSP": "idIntermediario1"

}

Response OK:

Body { "esito": "OK", "redirect": 1, "url": <url PSP configurato sul NP> "fault": null }

Response KO:


60

3. papRestChiediRT()

Request:

Resource <CP> /rest/rts/015208000000000

Method GET


Body -

Response OK:

Body { "tipoFirma": "", "rt": <RT in formato Base64>, "statoPratica": "RT_VERIFICATA" }

Response KO:


12. APPENDICED–ILPAGAMENTOPRESSOPSP(NELLAPAP)In questa modalità il pagamento è disposto presso i sistemi del PSP scelto dall’utente dopo aver

ricevuto un avviso di pagamento emesso dalla PA beneficiaria. Nella PAP tale successione di eventi

viene modellata attraverso una RPT priva dei dati del PSP che sarà utilizzato per pagare, in quanto al

momento della creazione tali dati non sono noti. È necessario quindi suddividere la creazione di una

RPT in due fasi:

• Caricamento di una nuova RPT: la PA beneficiaria riscontra l’esistenza di una posizione debitoria a

carico di un determinato utilizzatore finale e quindi viene creata una nuova RPT in cui sono definiti

tutti dati tranne quelli relativi al particolare PSP che sarà utilizzato per il pagamento, essendo questi

indeterminati. In questa fase sarà generato un avviso di pagamento, contenente i dati utili ad

identificare e attivare la RPT in attesa.

• Scelta del PSP ed esecuzione del pagamento: l’utilizzatore finale scegliendo il PSP da utilizzare per

il pagamento, permette l’inserimento dei relativi dati all’interno della RPT creata nella fase

precedente e quindi l’esecuzione del pagamento in maniera analoga ai modelli precedenti.

61

A valle delle due fasi appena descritte, la Pratica PAP di riferimento sarà nello stato

“IN_ATTESA_DI_RT” e il flusso che si seguirà da questo punto in poi sarà del tutto analogo a quello di

un pagamento immediato.

Per la descrizione dettagliata di questa modalità di pagamento è necessario introdurre due nuove

entità:

Avviso di Pagamento

o Cos’è: un documento (cartaceo o elettronico) in possesso dell’utilizzatore finale all’interno che fornisce al PSP le informazioni necessarie per identificare la RPT in attesa (in chiaro come una stringa numerica o codificate in codici ottici come barcode o Qrcode)

o Chi lo genera: la PA beneficiaria.

o Quando viene generato: a monte del processo di pagamento

o Cosa contiene: oltre alle informazioni di servizio comprende i dati necessari per l’esecuzione del pagamento:

codiceIdentificativoEnte: identificativo dell’ente creditore (i.e. il codice fiscale della PA beneficiaria)

numero Avviso

auxDigit: cifra riservata per usi futuri (che attualmente deve essere posta uguale a 0)

applicationCode: codice numerico di due cifre che rappresenta un identificativo dell’archivio in cui è memorizzata la richiesta di pagamento in attesa che ha dato luogo alla generazione dell’avviso. Nel caso di adozione della PAP, rappresenta l’identificativo univoco della PAP stessa ed è utilizzato dal Nodo, in fase di attivazione della RPT, per individuare la PAP presso la quale è stato caricato il pagamento diretto relativo.

identificativoUnivocodiVersamento (IUV): identificativo univoco all’interno della singola PA

importoVersamento: contenente l’importo del singolo versamento

o Chi lo utilizza: l’Utilizzatore Finale presentandolo al PSP scelto per il pagamento, che a sua volta lo utilizza per identificare la relativa RPT in attesa e innescare il pagamento

Caricatore RPT

o Chi è: la persona fisica o la procedura elettronica che si occupa di caricare un nuovo pagamento sul database della PAP, (attivato o meno presso PSP) tramite apposite funzionalità predisposte dalla PAP.

o Cosa fa: a seconda delle scelte progettuali operate dall’Integratore PA, effettua il caricamento di una nuova RPT può essere eseguita (anche in modo non mutuamente esclusivo):

da un addetto della PA beneficiaria;

da un Utilizzatore Finale, tramite apposita funzione esposta sul Portale PA

62

da un processo automatico (i.e. processo batch di caricamento) o manuale che richiama direttamente le funzionalità esposte dalla PAP sotto forma di WS REST .

o Come lo fa: invocando la specifica primitiva PA e fornendo i parametri richiesti. In questo caso il cittadino si collega con il proprio Internet browser al portale dell’ente creditore e – mediante il sistema dei pagamenti dell’Ente creditore ‐ inserisce tutte le informazioni relative al proprio debito (utili alla predisposizione della RPT).

Descrizionecasod’uso


1. L’Ente creditore riscontra la posizione debitoria di un utilizzatore finale e ‐ attraverso il Caricatore RPT ‐ crea una nuova RPT, priva dei dati del PSP (al momento non noto); contestualmente viene creato un nuovo Avviso di Pagamento

2. l’utilizzatore finale – ricevuto l’avviso di pagamento di cui al punto precedente – si collega al portale il portale del PSP prescelto e immette i dati (contenuti nell’Avviso stesso) utili a identificare e attivare la RPT in attesa

3. la RPT viene così completata e il pagamento viene effettuato

4. il portale dell’Ente creditore chiede al NP – tramite PAP – la RT e la invia all’utilizzatore finale secondo gli scenari sopra indicati (pagamento immediato o differito)

Sequencediagramdelcasod’uso

Facendo riferimento al seguente sequence diagram, andiamo a descrivere in dettaglio i passaggi

previsti per la prima fase di questa modalità di pagamento, quella cioè relativa al caricamento di uno

nuovo pagamento diretto attivato presso PSP.

Sequence Diagram ‐ pagamento attivato presso PSP (carica pagamento diretto)

63

1) Carica nuovo pagamento diretto presso PSP(): L’intero scenario collegato a questa modalità di

pagamento viene attivato dal Caricatore RPT, nel momento in cui, tramite specifica funzionalità, carica

un nuovo pagamento;

1.1) papRestGeneraIUV(): (operazione opzionale) il Portale PA richiede alla PAP un nuovo IUV a cui

associare la successiva richiesta di invio RPT.

1.1.1) Crea nuova Pratica ed imposta stato a "IUV_APPENA_CREATO": contestualmente alla

creazione di uno IUV interno alla PAP, viene creata una nuova Pratica a cui viene associato lo IUV

appena creato ed il cui stato viene posto a “IUV_APPENA_CREATO”;

1.2) papRestCaricaPagamentoDiretto(): il Portale PA chiama il WS REST della PAP a cui passa lo IUV

appena generato, insieme a tutti i dati necessari alla creazione di una nuova RPT, tranne quelli relativi

al PSP, non essendo in questa fase ancora stato stabilito il PSP presso il quale si andrà a effettuare il

pagamento. La response a tale invocazione REST conterrà l’esito dell’operazione (che nel caso

descritto nel Sequence Diagram corrisponde a una condizione di corretta esecuzione, quindi ad un

codice di ritorno HTTP 201, avendo appena aggiunto una nuova entità nel database della PAP).

1.2.1) Verifica correttezza richiesta: la PAP effettua un controllo di correttezza strutturale e logica dei

dati in input e, in caso di errore (non contemplato in questo Sequence Diagram):

nessuna RPT viene salvata in forma esplosa nel database (non ha senso salvare nella Pratica i

dati di una richiesta di pagamento errata), ma viene comunque salvato il relativo XML nella

tabella RptErrate;

viene restituita una response http con codice di errore e faultBean opportunamente

valorizzati;

Il flusso si interrompe;

1.2.2) Storicizza RPT() e cambia stato a “IN_ATTESA_DI_PSP”: la PAP provvede a:

storicizzare la RPT in input nella sua forma esplosa (quindi non solo la stringa relativa al suo

XML, ma i suoi dati all’interno di una struttura articolata di tabelle in forma relazionale), in

quanto la considera strutturalmente e logicamente corretta;

valorizzare all’interno della Pratica identificata dallo IUV in input i riferimenti alla RPT in

forma esplosa. La pratica viene poi posta nello stato “In attesa di PSP”.

Come evidenziato dal sequence diagram, i compiti della PAP relativi ad una richiesta di caricamento di un

nuovo pagamento diretto attivato presso PSP si esauriscono con la response della chiamata al WS REST

papRestCaricaPagamentoDiretto().

Al fine di garantire la corretta e completa implementazione della modalità di pagamento qui descritta, sarà

compito dell’Integratore PA realizzare sul Portale PA specifiche funzionalità in grado di:

64

individuare la corretta esecuzione della richiesta di caricamento di pagamento diretto attivato

presso PSP, tramite la verifica dell’esito dell’invocazione del WS REST

papRestCaricaPagamentoDiretto(), gestendo eventualmente nel modo più opportuno condizioni di

errore che dovessero verificarsi;

generare un Avviso di Pagamento opportunamente formattato e contenente i dati previsti;

implementare i meccanismi di recupero da parte dell’Utilizzatore Finale dell’Avviso di Pagamento

appena generato (ad esempio prevedendo la stampa del relativo PDF).

SceltadelPSPedesecuzionedelpagamento

A valle della fase di caricamento di una nuova RPT, l’Utilizzatore Finale, in possesso dell’Avviso di

pagamento, può recarsi presso un PSP di sua scelta, presentare l’Avviso di Pagamento ed eseguire il

pagamento, concludendo lo scenario previsto dalla modalità di pagamento diretto attivato presso PSP.

In conformità alle specifiche SANP, la PAP mette a disposizione del Nodo dei Pagamenti, e quindi

indirettamente del PSP, il metodo di utilità tramite il quale è possibile eseguire una operazione di verifica in

sola lettura dello stato del pagamento, operazione che non altera in alcun modo i dati del sistema.

Tale funzione, realizzata dal metodo paaVerificaRPT() esposto dalla PAP verso il Nodo sotto forma di WS

SOAP, è quindi reiterabile senza conseguenze un numero arbitrario di volte.

Al momento della presentazione di un Avviso di Pagamento da parte dell’Utilizzatore Finale presso le

strutture messe a disposizione dal PSP, questi può opzionalmente eseguire la funzione esposta dal nodo

denominata nodoVerificaRPT(), che a sua volta richiamerà il relativo WS SOAP della PAP paaVerificaRPT()

tramite cui la PAP verificherà lo stato del pagamento associato allo IUV in input (che identifica la RPT),

restituirà poi tale stato al Nodo, che a sua volta lo restituirà alle strutture messe a disposizione dal PSP che

potranno comunicare l’esito della verifica all’Utilizzatore Finale (vedi Figura 1).

In caso di verifica positiva (si ha una verifica positiva quando la RPT si trova nello stato “In attesa di PSP”)

l’Utilizzatore Finale potrà decidere se procedere o meno col pagamento. In caso contrario (pagamento

inesistente, già pagato ecc.) il PSP comunicherà all’Utilizzatore Finale l’impossibilità di procedere col

pagamento, adducendo la corretta motivazione.

La decisione di utilizzare o meno la funzionalità di verifica dipende dalle scelte implementative del PSP,

anche in funzione delle condizioni operative del pagamento. Egli potrà infatti scegliere se:

esporre tale opzione di verifica come funzione di utilità:

o agli Utilizzatori Finali

o agli operatori di sportello delle strutture PSP, che potranno utilizzare a loro discrezione tale

funzione

eseguire le verifiche come operazione di default preliminare all’attivazione della RPT, a fronte della

presentazione di un Avviso da parte di un Utilizzatore Finale

non utilizzare del tutto la funzionalità di verifica

65

Per l’esecuzione del pagamento vero e proprio viene eseguito il metodo esposto al PSP dal Nodo

denominato nodoAttivaRPT(), tramite il quale, dopo aver eseguito gli stessi controlli e le stesse operazioni

conseguenti alla chiamata della funzione nodoVerificaRPT() e averne ottenuto un riscontro positivo,

richiede alla PAP la “attivazione” della RPT, che corrisponde alla valorizzazione dei campi della RPT relativi

al PSP (che fino al momento della effettiva richiesta dell’esecuzione del pagamento non erano valorizzati)

ed al CCP (i.e. codiceContestoPagamento), generato dal PSP, che insieme allo IUV permette di identificare

univocamente al richiesta di pagamento. Tale codice è utilizzato per discriminare l’eventuale reiterazione

della funzione di attivazione.

A valle dell’attivazione di una RPT è possibile procedere con l’esecuzione del pagamento, effettuato il quale

il PSP:

1. rilascia all’Utilizzatore Finale una ricevuta cartacea di avvenuto pagamento

2. genera ed invia la relativa RT al Nodo, che a sua volta la inoltra alla PAP, che la rende quindi

disponibile al Portale PA per poter essere consultata dall’Utilizzatore Finale ed eventualmente da

un operatore di backoffice.

A differenza della funzione di verifica di una RPT, la nodoAttivaRPT() modifica lo stato interno della PAP a

prescindere dall’esito del pagamento (presente sulla RT), andando a:modificare il database della PAP

attraverso:

la valorizzazione dei campi della RPT relativi al PSP che fino a quel momento erano vuoti

la modifica dello stato della Pratica relativa a tale RPT

Si noti che, nel caso di esito “pagamento non eseguito” (RT avente esito pagamento 1), sarà invece

possibile reiterare il pagamento, anche cambiando il PSP.

Di seguito riportiamo il sequence diagram della funzione “VerificaRPT”, fornendo per ciascun passaggio una

breve descrizione.

66

Sequence Diagram ‐ pagamento attivato presso PSP (scenario "VerificaRPT")

1) L’Utilizzatore finale presenta Avviso di pagamento: l’Utilizzatore Finale si reca presso lo sportello del PSP

esibendo l’Avviso di Pagamento;

1.1) nodoVerificaRPT(): il PSP invia al Nodo una richiesta di verifica RPT.

1.1.1) identifica la PAP di riferimento(): il Nodo identifica la PAP associata all’Avviso di Pagamento

relativo alla RPT in input, al fine di chiedere la verifica dello stato della RPT alla PAP su cui è stata

caricata;

1.1.2) paaVerificaRPT(): il Nodo richiede alla PAP appena identificata di verificare lo stato della RPT

1.1.2.1) Verifica stato Pratica = "IN_ATTESA_DI_PSP" o “RT_VERIFICATA”: la PAP verifica che il

pagamento sia effettivamente in uno degli stati ammessi per poter effettuare il pagamento (i.e.

“IN_ATTESA_DI_PSP” o “RT_VERIFICATA”). Nel caso in cui la Pratica fosse nello stato

“RT_VERIFICATA” l’esito del pagamento della RT associata deve essere “Pagamento non eseguito”

(i.e. valore del campo esito Pagamento = 1). In caso contrario restituisce un faultBean contenente

la descrizione del motivo per cui la verifica è fallita. In ogni caso, l’esito seguirà il percorso inverso

delle request, ritornando al PSP l’informazione richiesta. A questo punto il PSP utilizzerà tale

informazione coerentemente con lo scenario operativo che avrà deciso di implementare (nel caso

rappresentato nel sequence diagram, il PSP restituirà all’Utilizzatore Finale l’esito positivo della

verifica).

67

Sequence Diagram ‐ pagamento attivato presso PSP (scenario "AttivaRPT")

1) presenta avviso di pagamento e chiede di pagare: l’Utente si reca presso lo sportello del PSP esibendo

l’Avviso di pagamento (eventualmente sotto forma di stampa con o senza barcode) e chiedendo di

effettuare il pagamento. A seconda delle modalità operative che ha deciso di implementare, il PSP può

eseguire una verifica della RPT relativa all’Avviso di Pagamento ricevuto, oppure procedere senza controlli

preliminari all’attivazione della RPT, ricevendo in caso di problemi un messaggio di errore. Nello scenario

descritto nel presente sequence diagram si procedere all’attivazione senza previa verifica.

1.1) nodoAttivaRPT(): il PSP invia al Nodo una richiesta di attivazione RPT.

68

1.1.1) identifica la PAP di riferimento(): il Nodo identifica (tramite i campi codiceIdentificativoEnte ed

applicationCode presenti nell’avviso di pagamento) la PAP associata all’Avviso di Pagamento relativo

alla RPT in input, al fine di chiedere la verifica dello stato della RPT alla PAP su cui è stata caricata;

1.1.2) paaAttivaRPT(): il Nodo richiede alla PAP di attivare la RPT identificata dai dati presenti

nell’Avviso di Pagamento.

1.1.2.1) Verifica stato Pratica = "IN_ATTESA_DI_PSP " o “RT_VERIFICATA”: la PAP verifica che:

la Pratica associata all’Avviso di Pagamento sia effettivamente in uno degli stati ammessi

(i.e. “IN_ATTESA_DI_PSP” o “RT_VERIFICATA”)

nel caso in cui la Pratica fosse nello stato “RT_VERIFICATA”, l’esito del pagamento della RT

associata deve essere negativo (i.e. valore del campo esito Pagamento=1)

In caso positivo si può proseguire con il flusso di attivazione, altrimenti (caso non descritto nel

presente sequence diagram) si restituirebbe un faultBean contenente la descrizione del motivo

per cui la verifica è fallita ed il flusso si interromperebbe restituendo al PSP la descrizione

dell’errore, che sarebbe eventualmente comunicato all’Utente in attesa di pagare.

1.1.2.2) completa la RPT aggiungendo i riferimenti al PSP: la PAP estrae dalla Pratica identificata

dall’Avviso di Pagamento la RPT e ne valorizza i campi relativi al PSP ed al CCP, utilizzando i dati in

input al WS SOAP paaAttivaRPT() (contenenti di fatti tutti i dati del PSP chiamante).

1.1.2.3) Storicizza RPT e cambia stato a "RPT_STORICIZZATA": la PAP salva la RPT e cambia lo stato

della relativa Pratica a “RPT_STORICIZZATA”.

1.1.2.4) nodoInviaRPT(): la PAP invia la RPT completamente valorizzata al Nodo dei Pagamenti,

che a sua volta invoca il metodo pspInviaRPT() del PSP (operazione 1.1.2.4.1), da cui riceve un OK

(o un faultBean opportunamente valorizzato, caso non descritto nel sequence diagram).

1.1.2.5) Cambia stato Pratica a "IN_ATTESA_DI_RT": la PAP cambia lo stato della Pratica

ponendolo a “IN_ATTESA_DI_RT”, dato che le operazioni ad essa deputate sono per il momento

concluse, fino al ricevimento della RT che attesta l’esito positivo del pagamento.

2) effettua il pagamento: l’Utente effettua il pagamento presso il PSP, da cui riceve una ricevuta con valore

liberatorio.

Da questo punto in poi il flusso della RT seguirà esattamente il flusso descritto nel seguito.

69

Sequence Diagram ‐ richiesta RT pagamento attivato presso PSP

EsempidichiamateaiserviziespostidaNRPversoilportaledell’Entecreditore

1. papRestGeneraIUV()

Request:

Resource <CP>/rest/iuvs

Method POST

Query parameters ?iso11649=false

Body ‐

70

Response OK:

Body {"iuv": "015208000000001"}

Response KO:

Body HTTP Status 405 - Method Not Allowed

2. papRestCaricaPagamentoDiretto()

Request:

Resource <CP>/rest/rpts/pagamentodiretto/

Method POST


Body { "versioneOggetto": "5.2", "dominio": { "identificativoDominio": "00849050109", "identificativoStazioneRichiedente": "00849050109_01" }, "identificativoMessaggioRichiesta": "RPT_20150727_02", "dataOraMessaggioRichiesta": "2015-07-27T12:00:00", "autenticazioneSoggetto": "N/A", "soggettoPagatore": { "identificativoUnivocoPagatore": { "tipoIdentificativoUnivoco": "F", "codiceIdentificativoUnivoco": "00000001234" }, "anagraficaPagatore": "Anagrafica Pagatore Test 1" }, "enteBeneficiario": { "identificativoUnivocoBeneficiario": { "tipoIdentificativoUnivoco": "G", "codiceIdentificativoUnivoco": "00849050109" }, "denominazioneBeneficiario": "Regione Liguria test" }, "datiVersamento": { "dataEsecuzionePagamento": "2015-07-27", "importoTotaleDaVersare": 2.00, "tipoVersamento": "CP", "identificativoUnivocoVersamento": "015208000000001", "codiceContestoPagamento": "n/a", "firmaRicevuta": 0, "datiSingoloVersamento": [ { "importoSingoloVersamento": 2.00, "ibanAccredito": "IT23X0000100001000000000999", "causaleVersamento": "/RFB/015208000000001/2.00", "datiSpecificiRiscossione": "9/2.00" }

71

] } }

Response OK:

Body { "esito": "OK", }

Response KO:


3. papRestChiediRT()

Request:

Resource <CP> /rest/rts/015208000000000

Method GET


Body -

Response OK:

Body { "tipoFirma": "", "rt": <RT in formato Base64>, "statoPratica": "RT_VERIFICATA" }

Response KO:


polo regionale dei pagamenti disciplinare tecnico · 2017-08-21 · a disposizione degli enti...

Documents