Docs Italia beta

Documenti pubblici, digitali.

SEZIONE III – SPECIFICHE TECNICHE

7. Introduzione

La presente sezione descrive le interfacce di cooperazione applicativa del software che implementa i servizi del NodoSPC.

Il NodoSPC definisce le regole di cooperazione tra i due attori (EC e PSP) del processo di pagamento, i quali sono connessi al NodoSPC per mezzo di piattaforme software così denominate:

  • stazioneIntermediarioPA: rappresenta la piattaforma software utilizzata da un Ente Creditore per scambiare i messaggi all’interno del sistema pagoPA relativamente ai processi di pagamento di uno o più servizi.
  • Canale: rappresenta la piattaforma software messa a disposizione da un PSP (e connessa al NodoSPC) che realizza un servizio di pagamento messo a disposizione dell’utilizzatore finale al fine di completare un pagamento verso un Ente Creditore.

Entrambi gli attori possono utilizzare una molteplicità di piattaforme software per colloquiare con il NodoSPC, in funzione delle proprie esigenze.

Per la piena comprensione dell’interscambio dei messaggi all’interno del sistema, si deve tenere presente la possibilità che tra l’attore principale ed il NodoSPC si interponga un intermediario (intermediarioPA, intermediarioPSP) a cui l’attore principale ha demandato il compito di gestire la propria piattaforma software di interconnessione e rendere disponibili le interfacce verso il NodoSPC. Nella figura seguente sono rappresentate le varie casistiche possibili.

image0

Figura 1: Diagramma delle connessioni logiche al NodoSPC

Si definisce quindi:

  • IntermediarioPA: il soggetto che opera come intermediario per un Ente Creditore. Qualora l’Ente Creditore non si avvalga di un intermediario, rappresenta l’Ente Creditore stesso;
  • IntermediarioPSP: il soggetto che opera come intermediario per un PSP. Qualora il PSP non si avvalga di un intermediario, rappresenta il PSP stesso;
  • StazioneIntermediarioPA: il sistema software gestito da un IntermediarioPA, che si interfaccia direttamente col NodoSPC;
  • Canale: il sistema software gestito da un IntermediarioPSP, che si interfaccia direttamente al NodoSPC con le modalità previste.

Allo stesso soggetto è consentito di connettersi al NodoSPC in maniera diversa (diretta o intermediata) in funzione dei servizi offerti.

Nelle descrizioni seguenti si ometterà di fare riferimento a detti intermediari, in quanto essi non svolgono un ruolo logicamente distinguibile dai soggetti intermediati.

7.1. Interfacce/Protocolli

Il NodoSPC espone diverse interfacce per realizzare le funzioni di cooperazione:

  • Web-services, realizzati con protocollo SOAP;
  • SFTP, per il trasferimento sicuro di file che non necessitano di essere elaborati contestualmente;
  • WISP, web app (protocollo HTTPS) che realizza un wizard interattivo per la scelta del PSP con cui effettuare il pagamento da parte dell’Utilizzatore finale.

image1

Figura 2: Diagramma delle interfacce di comunicazione

Le interfacce web services e SFTP rappresentate nella figura precedente sono ricapitolate in tabella:

Denominazione Formato Protocollo Descrizione
NodoPerEc WSDL SOAP Raccolta di metodi e parametri di interfaccia esposti dal NodoSPC fruibili dagli EC
EcPerNodo WSDL SOAP Raccolta di metodi e parametri di interfaccia esposti dagli EC fruibili dal NodoSPC
NodoPerPSP WSDL SOAP Raccolta di metodi e parametri di interfaccia esposti dal NodoSPC fruibili dai PSP
PspPerNodo WSDL SOAP Raccolta di metodi e parametri di interfaccia esposti dai PSP fruibili dal NodoSPC
       
SFTP Testo SFTP Raccolta di regole per la ricezione di file massivi e/o elementi dal NodoSPC.

Tabella 1: Interfacce di comunicazione

Le caratteristiche tecniche dei servizi utilizzati all’interno dei casi d’uso sono disponibili all’interno del progetto gitHub in formato WSDL (per le chiamate SOAP). I dati per la configurazione dei servizi SFTP sono messi a disposizione ai soggetti aderenti, in forma testuale, mediante canali riservati.

Per l’interfaccia WISP nei confronti dell’Utilizzatore finale sono resi disponibili per gli EC degli SDK per lo sviluppo di applicazioni mobile.

7.2. Architettura Funzionale

Per descrivere l’interazione tra EC, NodoSPC e PSP questa sezione è stata articolata nei seguenti capitoli:

  • Modello dei Dati: documenta le strutture dei dati scambiati all’interno dei servizi tra i diversi attori ed il NodoSPC.
  • Pagamento Attivato presso EC: documenta i metodi messi a disposizione dei soggetti aderenti per realizzare il modello di pagamento attivato presso l’EC.
  • Pagamento Attivato presso PSP: documenta i metodi messi a disposizione dei soggetti aderenti per realizzare un pagamento di una posizione debitoria presso un PSP.
  • Avvisatura Digitale: documenta i metodi messi a disposizione dei soggetti aderenti per realizzare la generazione e la distribuzione di un avviso di pagamento digitale.
  • Back-Office: documenta le funzioni accessorie che possono essere invocate per gestire scenari secondari del ciclo di vita del pagamento (es. storno, revoca).
  • Ausiliarie: documenta le funzioni di controllo che contribuiscono a monitorare lo stato di esecuzione di un pagamento (es. richiesta stato RPT, richiesta stato RT), al fine di attuare eventuali azioni di recupero.

Le funzioni del sistema sono descritte attraverso i casi d’uso secondo lo standard UML (Use Cases, da ora in avanti UC). In particolare per ogni funzione, verrà fornita:

  • la descrizione degli attori coinvolti ed i loro obiettivi;
  • la descrizione del caso d’uso nominale, cioè il workflow che termina in assenza di errori

Nel dettaglio, ogni UC verrà descritto attraverso:

  • una condizione iniziale dello stato del pagamento che definisce il pre-requisito per l’attuazione del caso d’uso;
  • un trigger, cioè l’evento che scatena il caso d’uso;
  • una descrizione testuale del workflow;
  • una condizione finale che identifica lo stato del pagamento a conclusione dello UC;
  • uno (o più) sequence diagram che descrivono le interazioni nel tempo tra i diversi attori e le interfacce utilizzate.

Ogni messaggio contenuto all’interno dei sequence diagram sarà:

  • numerato in base all’ordine temporale di invio/ricezione del messaggio;
  • caratterizzato dalla notazione riportata in tabella;
  • corredato da una descrizione; nel caso di messaggio di risposta (response), indicherà l’esito della richiesta (request) effettuata.

La tabella seguente illustra le notazioni grafiche utilizzate nei sequence diagrams.

Elemento Simbolo Vincoli / Note
Attore image3 Rappresenta uno degli attori del Sistema pagoPA
Richiesta SOAP   Freccia rossa linea continua, che rappresenta la richiesta entrante nell’interfaccia dell’attore che espone i servizi
Risposta SOAP   Freccia blu linea tratteggiata, che rappresenta la risposta uscente dall’interfaccia dell’attore che espone i servizi; appare sempre in corrispondenza di una richiesta SOAP
GET HTTP   Freccia verde linea continua, che rappresenta le chiamate effettuate dall’utilizzatore finale per la fruizione delle applicazioni WEB fornite dagli attori del processo
Azione SFTP   Freccia viola linea continua, che rappresenta un’azione mediata dal protocollo SFPT
SFTP response   Freccia viola linea tratteggiata, che rappresenta la risposta ad un comando SFTP
Stato Pagamento   Losanga fondo giallo bordo rosso, che rappresenta lo stato del pagamento sul NodoSPC

Tabella 2: Notazioni grafiche utilizzate nei sequence diagram

Con l’obiettivo di favorire l’attuazione di strategie di ripristino, automatiche o manuali, da mettere in atto direttamente da parte degli attori connessi al sistema (EC, PSP) i possibili errori saranno classificati in base alle categorie riportate nella figura sottostante.

image4

Figura 3: Raggruppamento delle possibili tipologie di errori

Le tipologie di errori con relativa descrizione e macro-categoria di appartenenza sono descritte nella tabella sottostante.

Categoria Tipologia Descrizione
Errori Infrastrutturali Superamento Soglie Il soggetto fruitore ha superato i limiti di interazione applicativa (frequenza di richieste troppo elevata) con il soggetto erogatore di cui al documento “Indicatori di qualità per i soggetti aderenti”
  Connessione Impossibilità di interagire con la Controparte applicativa raggiunta mediante il NodoSPC
  Timeout/Congestioni Superamento delle soglie temporali previste per la risposta del soggetto erogatore di cui al documento “Indicatori di qualità per i soggetti aderenti”
Errori Configurazione Configurazione Chiamante Errore nei dati di configurazione da parte del soggetto fruitore del servizio applicativo invocato
  Configurazione Controparte Errore nei dati di configurazione della controparte applicativa raggiunta mediante il NodoSPC
Errori Controparte Timeout Controparte Superamento delle soglie temporali previste per la risposta della controparte applicativa di cui al documento “Indicatori di qualità per i soggetti aderenti”
  Errore response Controparte Errore nella risposta da parte della controparte applicativa
Errori Validazione Validazione Sintattica Errore nella sintassi dei messaggi scambiati
  Duplicazione Messaggi Duplicazione dei messaggi scambiati tra soggetto erogatore e fruitore
  Validazione Semantica Errore di validazione semantica nell’esercizio del processi del sistema

Tabella 3: Descrizione delle categorie di errore

Per gli errori che causano l’emanazione di un faultBean da parte del NodoSPC, in riferimento a ogni caso d’uso, saranno trattate le possibili strategie di risoluzione ed evidenziati i percorsi critici per cui è necessario l’instaurazione del Tavolo Operativo di cui alla sezione IV.

7.3. Stato del Pagamento

Nei processi di business descritti nella sezione II, il processo di pagamento può essere definito da un insieme discreto di transazioni fra stati stabili del sistema, caratterizzati da un set di informazioni/condizioni di entrata e un set di informazioni/condizioni di uscita.

Gli stati tracciati nei sequence diagram dei casi d’uso e riportati nel presente documento, sono unicamente quelli in cui il workflow attraversa l’interfaccia applicativa del NodoSPC. Quando un soggetto non può essere autonomo nella diagnosi di una anomalia, verranno fornite indicazioni per l’attivazione del Tavolo Operativo con il NodoSPC e/o con la controparte interessata.

Il seguente diagramma evidenzia la successione temporale degli stati del processo di pagamento, la cui descrizione è riportata nella tabella successiva.

image5

Figura **4: Stati del pagamento **

Stato Descrizione Tracciato su pagoPA
S1 - “In attesa generazione PD” Stato iniziale in cui permane il sistema se fallisce l’avvio di un processo di pagamento Si
S2 – “PD in attesa”

L’EC ha generato una Posizione Debitoria, di propria iniziativa o in conseguenza di un’azione spontanea dell’Utilizzatore Finale.

Sono in questo stato tutti i pagamenti per cui esiste un IUV, un numero Avviso di Pagamento, ma ancora nessuna RPT associata è stata generata.

Si
S3 – “RPT Attivata”

Nel dominio dell’EC è stata generata una RPT a causa della scelta da parte dell’Utilizzatore Finale del PSP che gestirà il pagamento.

Sono in questo stato tutti i pagamenti per cui è stata generata una RPT. È stato generato un CCP che distingue il tentativo di pagamento. La RPT risulta validata e presa in carico dal NodoSPC.

Si
S4 – “Pagamento autorizzato”

Il pagamento risulta autorizzato dall’Utilizzatore Finale attraverso i meccanismi previsti dal sistema pagoPA

Sono in questo stato tutti i pagamenti per cui la RPT risulta presa in carico da un PSP. Il PSP non ha ancora generato la RT corrispondente.

Si (solo per i pagamenti autorizzati su WISP)
S5 – “RPT Pagata”

Il pagamento risulta andato a buon fine ed il PSP scelto dall’Utilizzatore Finale incassa la somma e genera la RT.

Sono in questo stato tutti i pagamenti andati a buon fine, per cui il PSP ha generato la RT.

Si
S6 – “RT Nodo”

La RT generata dal PSP scelto dall’Utilizzatore Finale è consegnata al NodoSPC

Sono in questo stato tutti i pagamenti andati a buon fine, per cui il NodoSPC ha preso in carico la RT.

Si
S7 – “RT EC”

La RT è consegnata all’Ente Creditore dal NodoSPC

Sono in questo stato tutti i pagamenti andati a buon fine, per cui l’EC ha preso in carico la RT.

Si
S8 – “RT Accreditata”

Il PSP scelto dall’Utilizzatore Finale ha accreditato il pagamento sul conto indicato nella RPT dall’Ente Creditore.

Sono in questo stato tutti i pagamenti la cui RT può essere messa in relazione a SCT disposto dal PSP.

No
S9 – “RT Rendicontata PSP”

Il PSP genera e mette a disposizione il flusso di rendicontazione per l’EC sul Nodo SPC.

Sono in questo stato tutti i pagamenti per il quali il PSP ha disposto un PSP cumulativo e possono essere messi in relazione a un flusso di rendicontazione.

Si
S10 – “Pronto per riconciliazione”

Il pagamento è pronto per essere riconciliato sui sistemi di back-office dell’EC

Sono in questo stato tutti i pagamenti i cui flussi di rendicontazione, acquisiti dall’EC, quadrano con i corrispondenti SPC

Si
S11 – “PD annullata”

L’EC ha annullato una Posizione Debitoria, precedentemente generata.

Sono in questo stato tutti i pagamenti disposti al di fuori del sistema pagoPA

No

Tabella 4: Descrizione degli stati del pagamento

La seguente tabella ha lo scopo di associare a ciascuno dei task dei modelli di business di cui alla sezione II le primitive SOAP coinvolte, evidenziando le transizioni di stato causate dall’esecuzione degli stessi task.

Task Primitiva Stato di Ingresso Stato di Uscita Pre-condizioni Post-condizioni Note
T2.2.1
n.a. S1 - “In attesa generazione PD” n.a. L’EC ha ricevuto la richiesta di generazione della Posizione Debitoria da parte del PSP Lo stato S1 è il primo stato presente a sistema in caso di pagamento spontaneo
T1.1.1 nodoInviaAvvisoDi gitale n.a. S2 – “PD in attesa” n.a. L’EC ha effettuato la generazione della Posizione Debitoria, che è pronta per essere lavorata Lo stato S2 è il primo stato presente a sistema in caso di pagamento con avviso
T2.1.1
n.a S2 – “PD in attesa” n.a. L’EC ha effettuato la generazione della Posizione Debitoria, che è pronta per essere lavorata  
T2.2.2
S1 - “In attesa generazione PD” S2 – “PD in attesa” L’EC ha ricevuto la richiesta di generazione della posizione debitoria da parte del PSP L’EC ha effettuato la generazione della Posizione Debitoria, che è pronta per essere lavorata  
T1.1.1
S2 – “PD in attesa” S11 – “PD Annullata” L’EC riceve il pagamento al di fuori del circuito pagoPA oppure vuole annullare la posizione debitoria perché errata La Posizione Debitoria non è più lavorabile  
T2.1.2 nodoInviaRPT S2 – “PD in attesa” S3 – “RPT Attivata”

E’ stata generata una Posizione Debitoria.

L’Utilizzatore finale genera un carrello di RPT e avvia la procedura di pagamento

L’EC ha indirizzato su WISP e pagoPA ha preso in carico il carrello di RPT  
T2.2.7 nodoInviaRPT S2 – “PD in attesa” S3 – “RPT Attivata”

È stata generata una Posizione Debitoria.

L’EC riceve una richiesta di attivazione RPT da parte del PSP oppure l’Utilizzatore finale accede direttamente ai canali messi a disposizione dall’EC ed ha scelto la Posizione Debitoria da pagare

L’EC ha attivato l’RPT e l’ha inoltrata al PSP  
T2.1.5
S3 – “RPT Attivata” S4 – “Pagamento autorizzato” La RPT è stata attivata L’Utilizzatore finale ha approvato il pagamento  
T2.2.8
S3 – “RPT Attivata” S4 – “Pagamento autorizzato” La RPT è stata attivata L’Utilizzatore finale ha approvato il pagamento  
T2.1.9 pspInviaRPT S4 – “Pagamento autorizzato” S5 – “RPT Pagata” L’Utilizzatore finale ha approvato il pagamento Il PSP ha incassato il pagamento  
T2.2.9
S4 – “Pagamento autorizzato” S5 – “RPT Pagata” L’Utilizzatore finale ha approvato il pagamento Il PSP ha incassato il pagamento In caso di pagamento attraverso PSP è possibile che il pagamento da parte dell’Utente finale avvenga prima del ricevimento dell’RPT da parte dello stesso PSP, per questo si raccomanda di effettuare sempre la verifica dell’RPT (Gateway G2.5)
T2.1.12 nodoInviaRT S5 – “RPT Pagata” S6 – “RT Nodo” Il PSP ha ricevuto la RPT ed ha incassato il pagamento La RT è stata ricevuta da pagoPA  
T2.2.11 nodoInviaRT S5 – “RPT Pagata” S6 – “RT Nodo” Il PSP ha ricevuto la RPT ed ha incassato il pagamento La RT è stata ricevuta da pagoPA  
T2.1.13 paaInviaRT S6 – “RT Nodo” S7 – “RT EC” La RT è stata ricevuta da pagoPA L’EC ha ricevuto l’RT  
T2.2.12 paaInviaRT S6 – “RT Nodo” S7 – “RT EC” La RT è stata ricevuta da pagoPA L’EC ha ricevuto l’RT  
T2.1.16
S7 – “RT EC” S8 – “Accreditata” Il PSP ha incassato il pagamento Il PSP ha accreditato il pagamento sul conto dell’EC  
T2.2.15
S7 – “RT EC” S8 – “Accreditata” Il PSP ha incassato il pagamento Il PSP ha accreditato il pagamento sul conto dell’EC  
T2.1.17 nodoInviaFlussi S8 – “Accreditata” S9 – “RT Rendicontata PSP” Il PSP ha accreditato il pagamento sul conto dell’EC Il PSP ha inviato il rendiconto degli accrediti effettuati a pagoPA  
T2.2.16 nodoInviaFlussi S8 – “Accreditata” S9 – “RT Rendicontata PSP” Il PSP ha accreditato il pagamento sul conto dell’EC Il PSP ha inviato il rendiconto degli accrediti effettuati a pagoPA In caso di pagamento di singola RT, il PSP potrebbe non inviare il rendiconto
T2.1.18 nodoChiediFlussoR endicontazione S9 – “RT Rendicontata PSP” S10 – “Pronto per riconciliazione” Il PSP ha inviato il rendiconto degli accrediti effettuati a pagoPA pagoPA ha fornito i rendiconti ricevuti all’EC  
T2.2.17 nodoChiediFlussoR endicontazione S9 – “RT Rendicontata PSP” S10 – “Pronto per riconciliazione” Il PSP ha inviato il rendiconto degli accrediti effettuati a pagoPA pagoPA ha fornito i rendiconti ricevuti all’EC  

Tabella 5: Quadro sinottico delle transazioni di stato