Online - Modello API
Last updated
Last updated
Nel caso in cui l’Operatore abbia scelto di aderire al Programma attraverso il proprio sito web e/o e-commerce e tramite il Modello API, l’identificazione del Beneficiario quale avente diritto all’agevolazione coincide con l’applicazione o il riconoscimento dell’agevolazione medesima in fase di acquisto, attraverso i seguenti passaggi:
Il Beneficiario seleziona il bene/servizio, oggetto dell’agevolazione, sull’e-commerce dell’Operatore e arriva alla pagina di “checkout”;
Al momento dell’acquisto, il Beneficiario accede alla sua CGN sull’App IO, apre la schermata relativa all’agevolazione e genera un codice sconto temporaneo (OTP) per quella agevolazione, della durata di 10 minuti o fino a completamento della transazione, se precedente;
Il Beneficiario inserisce il codice generato nell’apposito campo predisposto dall’Operatore sul proprio e-commerce per l’applicazione di sconti e agevolazioni;
I sistemi dell’Operatore interrogano le API messe a disposizione da PagoPA S.p.A. per verificare la validità del codice.
In caso di risposta positiva (codice 200), l’agevolazione viene applicata alla transazione e il corrispondente OTP utilizzato viene invalidato per impedirne un ulteriore uso. In caso di risposta negativa (codice 404), l’Operatore visualizza il relativo messaggio di errore e l’agevolazione non verrà applicata.
Gli errori collegati al fallimento della fase di validazione consistono nei seguenti stati:
codice OTP scaduto (in caso di non utilizzo entro i 10 minuti di validità);
codice OTP invalido (codice 400);
codice OTP inesistente.
I sistemi dell’App IO che si occupano della validazione, controllo automaticamente, inoltre, che non esista già un codice OTP in corso di validità per il Beneficiario richiedente per la specifica agevolazione. Nel caso in cui esista un OTP ancora valido per quella agevolazione (perchè non utilizzato o non scaduto), viene restituito all’Operatore il codice di errore 409, che indica il conflitto con un OTP ancora valido.
Gli Operatori che intendono aderire utilizzando il Modello API, devono attenersi strettamente a quanto descritto nella presente documentazione tecnica reperibile al seguente link, da ritenersi come parte integrante e sostanziale della Convenzione in virtù del presente riferimento.
Una volta approvata la richiesta di Convenzione da parte del Dipartimento, gli Operatori che hanno scelto il Modello API, potranno trovare le proprie API key all’interno della sezione “Profilo” nel Portale. Per qualsiasi necessità, nella medesima sezione gli Operatori possono generare nuove API key.
Importante: Non appena le API key vengono rigenerate, quelle precedenti non saranno più utilizzabili.
Fig. 2 Esempio di carrello di un operatore con il campo di testo per l’inserimento del codice sconto
Fig.3 Dal dettaglio dell'agevolazione, l'utente genera un codice OTP
Fig. 4 Il codice OTP può essere direttamente incollato nel campo dell’e-commerce. Se risulta valido, lo sconto verrà applicato al carrello
I codici OTP generati dall’App IO per CGN sono formati da 11 caratteri alfanumerici e utilizzano l’alfabeto maiuscolo inglese. Un'OTP identifica univocamente un tentativo di acquisto online e pertanto può essere utilizzato una sola volta.
