Integrazione tramite API sincrone
Per la gestione degli errori fare riferimento a Gestione degli errori
Fase di richiesta di creazione della posizione debitoria
La paDemandPaymentNotice è utilizzata per richiedere all’EC la creazione della posizione debitoria in base ai dati dello specifico servizio inviati, l'EC invia in risposta le informazioni necessarie per avviare il processo di pagamento, in particolare:
il numero avviso;
il codice fiscale dell'EC da utilizzare nella fase di attivazione;
l'importo parziale di ogni singolo versamento;
il codice fiscale dell’EC beneficiario di ogni singolo versamento.
Durante questa fase la posizione debitoria deve rimanere nello stato aperta.
Gli EC mettono a disposizione i dati dello specifico servizio tramite il Catalogo dei servizi.
Fase di verifica
La paVerifyPaymentNotice è utilizzata per richiedere all’EC la verifica dell’opzione di pagamento identificata dal numero avviso, che invia le informazioni di pagamento relative al numero avviso, in particolare:
importo parziale;
codice fiscale dell’EC beneficiario;
il parametro allCCP, che indica se l’opzione di pagamento è associabile a tutti conti correnti postali o meno
allCCP = true: l’opzione è associabile a tutti conti correnti postali;
allCCP = false: l’opzione non è associabile a tutti conti correnti postali.
Durante questa fase la posizione debitoria deve rimanere nello stato aperta.
Il Nodo effettua una verifica semantica sulla response:
deve essere presente la paymentList;
il tag officeName è opzionale, tutti i restanti tags sono obbligatori.
Fase di attivazione
La richiesta di attivazione del pagamento giunge all’EC per mezzo della paGetPayment, l'EC invia l’importo del pagamento ed i dati necessari per il riversamento della somma, in particolare per ogni versamento:
importo parziale;
codice fiscale dell’EC beneficiario;
IBAN da usare per il riversamento.
Durante questa fase la posizione debitoria deve rimanere nello stato aperta, sarà cura del Nodo inibire altri tentativi di pagamento per lo stesso numero avviso.
Il Nodo effettua una verifica semantica sulla response:
verifica la corrispondenza tra il valore di paymentAmount e la somma di tutti gli amount presenti nei transfer;
ci deve essere almeno un'occorrenza di transfer;
controllo semantico degli IBAN in ogni transfer;
viene verificata l'esistenza sul Nodo dell'associazione tra fiscalCodePA e IBAN;
nel caso di presenza di un'EC secondario viene verificato che sia abilitato sul Nodo.
Fase di invio della ricevuta
Tramite la primitiva paSendRT viene inoltrata agli n EC interessati al pagamento la receipt (ricevuta) solo se il pagamento è stato effettuato, la receipt è un oggetto generato dalla piattaforma pagoPA.
In questa fase, dopo la ricezione della receipt, la posizione debitoria deve essere posta nello stato chiusa.
Recupero ricevuta
Il servizio è rivolto a tutti gli EC che, in casi particolari, hanno la necessità di recuperare una receipt non disponibile all’interno del proprio sistema a causa di specifiche anomalie tecniche e/o di processo.
Come verrà ampiamente chiarito nelle sezioni successive, il servizio non è pensato per essere fruito durante tutte le fasi del processo di pagamento, ma soltanto in casi specifici e in modo particolare a valle della ricezione dei flussi di rendicontazione. A protezione della natura del servizio sono state implementate delle politiche di throttling che limitano il numero di chiamate n in un intervallo di tempo t da parte dello stesso EC.
Qualora durante la lavorazione del flusso una receipt non fosse disponibile, l’eccezione può essere gestita tentando di recuperarla mediante l’invocazione del servizio getOrganizationReceipt.
Il diagramma seguente riporta invece uno use case non consentito
E' assolutamente vietato inserire l’invocazione del servizio getOrganizationReceipt all’interno di un loop in modo indiscriminato senza l’insorgere di un evento di errore che ne giustifichi l’utilizzo.
La procedura di adesione al servizio è descritta in Adesione ai servizi con subscription key.
Dopo aver ottenuto la subscription key, è possibile iniziare ad utilizzare il servizio mediante l’invocazione della API getOrganizationReceipt.
Di seguito i dettagli della signature del servizio:
GET /organizations/{organizationfiscalcode}/receipts/{iur}/paymentoptions/{iuv}
Come è possibile osservare il servizio effettua la ricerca della receipt utilizzando come filtro tre parametri ricevuti in input tramite la valorizzazione dei seguenti path parameters:
organizationalfiscalcode: codice fiscale EC;
iur: identificativo univoco riscossione, presente all’interno del flusso di rendicontazione ricevuto dal nodo pagoPA mediante l’invocazione della primitiva nodoChiediFlussoRendicontazione;
iuv: Identificativo univoco versamento, anch’esso presente all’interno del flusso di rendicontazione.
Come accennato nei precedenti capitoli, il servizio non è pensato per un utilizzo massivo, a protezione di questa caratteristica sono state attivate delle politiche di throttling che prevedono, per ogni sottoscrizione al servizio, un massimo di 10 chiamate nell’arco di 60 minuti.
Last updated
