Integrazione tramite API sincrone
Last updated
Last updated
Per la gestione degli errori fare riferimento a Gestione degli errori
Gli Intermediari Tecnologici, i Partner Tecnologici, o gli Enti Creditori che utilizzano l’integrazione tramite API sincrone sono tenuti al conferimento di tutte le posizioni debitorie gestite all'Archivio Centralizzato Avviso (ACA) al fine di assicurare le misure di continuità operativa che devono essere adottate dai gestori di sistemi di pagamento e dai fornitori critici di infrastrutture o servizi tecnici in conformità con gli obblighi derivanti dall'assoggettamento ex art. 146 T.U.B. di PagoPA alla Sorveglianza svolta dalla Banca d'Italia.
Ogni EC al momento delle creazione di una nuova posizione debitoria deve effettuare il censimento della stessa sull’ACA tramite la paCreatePosition, per mezzo della stessa API è possibile aggiornare la posizione.
Per la procedura di abilitazione all'utilizzo della paCreatePosition è necessario fare riferimento a Adesione ai servizi con subscription key.
La richiesta di creazione di una nuova posizione giunge all’ACA per mezzo della paCreatePosition, fornendo in input i seguenti dati:
fiscalCodePA: codice fiscale dell’EC;
entityUniqueIdentifierType: tipologia del debitore (F = persona fisica, G = persona giuridica);
entityUniqueIdentifierValue: codice fiscale del debitore
fullName: Nome e Cognome del debitore
IUV: identificativo univoco versamento
amount: importo
description: causale
dueDate: data di scadenza della posizione debitoria
ACA effettua una verifica semantica sulla response:
viene verificata la presenza di tutti i campi
viene verificata l'esistenza dell'EC nella piattaforma pagoPA
Non è possibile censire una posizione con un importo uguale a zero.
Si sottolinea che il servizio non permette la gestione di pagamenti multibenificiario.
In risposta viene inviato l’esito del censimento e in caso positivo l'identificativo della posizione debitoria in ACA.
E' possibile richiamare la stessa API paCreatePosition per effettuare un aggiornamento della posizione nei seguenti casi:
aggiornamento dell’importo
aggiornamento dello stato, per comunicare la chiusura della posizione, impostando il valore del campo importo a zero.
Nel caso non venisse riscontrata l’esistenza sul DB della posizione debitoria aggiornata la richiesta viene rigettata.
In risposta viene inviato l’esito dell'aggiornamento e in caso positivo l'identificativo della posizione debitoria in ACA.
Nel caso Pagamento spontaneo presso PSP 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.
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.
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;
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.
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.
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.
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.
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.
Per i tutti i dettagli tecnici relativi al corretto utilizzo del servizio è possibile fare riferimento alle specifiche della primitiva in getOrganizationReceipt.
