Servizi Antifrode¶
Il sistema Antifrode comprende l'insieme delle funzionalità di Procredito relative all'inserimento e alla gestione delle richieste Antifrode di diverse tipologie (report, certificato, etc). Per consultare l’elenco delle tipologie disponibili consultare l’Appendice B. Per visionare lo schema dei JSON di tutte le possibili tipologie di richiesta presenti nel sistema consultare l’Appendice D.
Info
Assicurarsi di inserire solo tipi di richiesta abilitati per il proprio profilo utente.
Verifica informazioni base sul soggetto (Step 1) ¶
Per validare i campi Nome, Cognome e Codice Fiscale invocare:
inviando il seguente JSON nel body della POST
Il sistema Antifrode provvederà a verificare i dati immessi restituendo una collezione di campi nel JSON "Data" che possono essere utilizzati nel processo di inserimento della richiesta
{
"Data": {
"SESSO": "M",
"LUOGONASCITA": "ROMA",
"PROVINCIANASCITA": "RM",
"DATANASCITA": "19750101",
"NAZIONALITA": "I"
},
"IsFiscalCodeDaForzare": false
}
"Data": rappresenta un frammento precompilato che è possibile utilizzare nel file JSON della richiesta antifrode.
"IsFiscalCodeDaForzare": se nome e cognome immessi sono difformi dai valori calcolati dal sistema a partire dal codice fiscale fornito andrebbe inviato un alert all'utente per confermare di procedere con CF forzato altrimenti tornare all'immissione del nome e cognome e CF.
Nel caso l'utente acconsenta ad utilizzare un codice fiscale forzato bisogna impostare a TRUE il campo FLAG_COD_FISCALE nel modello dati finale del JSON della richiesta.
Gli operatori che lavoreranno la pratica, in questo modo, sapranno che l'utente ha avuto consapevolezza che il CF immesso è stato forzato.
Verifica preliminare sui restanti dati del soggetto (Step 2) ¶
A seguito dello step 1 si può procedere alla chiamata GET a:
con i campi NAZIONALITA, PROVINCIANASCITA, LUOGONASCITA eventualmente modificati.
Esempio JSON della request per lo step 2:
{
"CODICEFISCALE": "RSSMRA75A01H501X",
"NAZIONALITA": "I",
"LUOGONASCITA": "ROMA",
"PROVINCIANASCITA": "RM"
}
Esempio JSON di risposta:
{
"IsValidNazionalita": true,
"IsValidProvinciaDiNascita": true,
"IsValidLuogoDiNascita": true,
"IsFiscalCodeDaForzare": false
}
dove:
"NAZIONALITA"è uno tra i seguenti valori:"I": Italiana"E": Comunità UE"S": Extra comunitaria"PROVINCIANASCITA"è uno tra i seguenti valori:"EE": nel caso di nascita all'estero"RM": (esempio RM) due lettere rappresentanti la province italiane, due lettere"LUOGONASCITA":"GERMANIA": (esempio GERMANIA) nome della nazione nel caso di nascita all'estero"ROMA": (esempio ROMA) nome della città Italiana.
Per ottenere l'elenco dei comuni, delle province e delle nazionalità disponibili v. paragrafo "Elenchi nazionalità, città e provincia".
Non deve essere possibile procedere con gli step successivi se uno dei parametri IsValidNazionalita, IsValidProvinciaDiNascita, IsValidLuogoDiNascita risulta FALSE, la procedura finale di inserimento richiesta restituirà un errore.
Le condizioni che possono presentarsi sono le seguenti:
IsValidNazionalita, IsValidProvinciaDiNascita, IsValidLuogoDiNascita sono tutte TRUE, si può procedere con le operazioni successive.
Nel caso IsFiscalCodeDaForzare venisse restituito a TRUE è necessario chiedere all'utente se si desidera procedere con il codice fiscale in modalità forzata, come descritto per lo STEP 1.
Elenchi nazionalità, città e provincia ¶
A seguito del completamento delle validazioni delle Personal Info si può procedere a personalizzare i campi NAZIONALITA, PROVINCIANASCITA, LUOGONASCITA.
"NAZIONALITA"è uno tra i seguenti valori:"I": Italiana"E": Comunità UE"S": Extra comunitaria"PROVINCIANASCITA"è uno tra i seguenti valori:"EE": nel caso di nascita all'estero"RM": (esempio RM) due lettere rappresentanti la province italiane, due lettere"LUOGONASCITA":"GERMANIA": (esempio GERMANIA) nome della nazione nel caso di nascita all'estero"ROMA": (esempio ROMA) nome della città Italiana.
Per recuperare l'elenco delle città italiane passando come parametro la provincia precedentemente selezionata invocare:
Per ulteriori specifiche sui campi chiusi di una "Richiesta" v. Appendice B.
Campi ISTAT utilizzabili nel json delle richieste¶
CODICE_ISTAT_LUOGO_NASCITACODICE_ISTAT_CITTA_RESIDENZACODICE_ISTAT_CITTA_RESIDENZA_REALCODICE_ISTAT_COMUNE_RILASCIOCODICE_ISTAT_COMUNE_RILASCIO_SOGCODICE_ISTAT_CITTA_SEDE_ATC
che affiancano o sostituiscono, rispettivamente, i seguenti:
LUOGONASCITA+PROVINCIANASCITACITTA_RESIDENZA+PROVINCIA_RESIDENZACITTA_RESIDENZA_REAL+PROVINCIA_RESIDENZA_REALCOMUNE_RILASCIO+PROVINCIA_RILASCIOCOMUNE_RILASCIO_SOG+PROVINCIA_RILASCIO_SOGCITTA_SEDE_ATC+PROVINCIA_SEDE_ATC
I campi con prefisso CODICE_ISTAT_ sovrascrivono eventuali informazioni passate nei relativi campi senza il prefisso, se discordanti.
Tuttavia è sempre bene passare anche i descrittivi (quindi i campi senza il prefisso, ad es. LUOGONASCITA, PROVINCIANASCITA, CITTA_RESIDENZA etc) dal momento che anche i codici istat non sono univoci ed il descrittivo potrebbe comunque aiutare a ritrovare il match esatto.
Se neanche con codice istat e descrittivo è possibile determinare univocamente il comune e la provincia verrà restituito un messaggio di errore.
In appendice è disponibile un esempio di JSON di un report plus con i campi ISTAT.
Creazione di una "Richiesta Antifrode" ¶
Creazione di una "Richiesta Antifrode" utilizzando la validazione dati¶
La creazione di una Richiesta Antifrode per mezzo degli strumenti di validazione forniti dal controller Validate garantisce che i dati vengano validati prima dell’inserimento vero e proprio.
Per effettuare l’inserimento di una richiesta Antifrode è comunque sufficiente effettuare una request http con enctype "multipart/form-data" e method POST all’indirizzo:
per tutte le tipologie richieste ad eccezione dell’Analisi Datore e delle richieste automatiche oppure
per la sola richiesta di Analisi Datore (v. nuovo JSON “Analisi Datore” in Appendice D)
Se l’inserimento di una richiesta va a buon fine il server risponderà con HTTP STATUS CODE 200 e restituirà un messaggio di avvenuta creazione e l’id della richiesta appena creata.
Info
Per inserire una richiesta è necessario allegare alla chiamata, oltre al JSON relativo alla tipologia della richiesta desiderata, gli eventuali allegati previsti.
Durante la creazione di una nuova richiesta, o in fase di completamento da precaricata, è possibile:
- includere una chiave opzionale negli headers denominata "RealUserKey" di tipo GUID contenente l’identificativo di un particolare utente (agente, mediatore, filiale) a cui si vuole associare la richiesta in fase di inserimento.
Per ottenere la userkey di un’agenzia è possibile invocare le seguenti API: -
GET v2/Societa/ElencoAgenzieRestituisce l’elenco delle agenzie di un utente di tipo società *
GET v2/Agenzia/ElencoAgenzieVisibiliRestituisce l’elenco delle agenzie visibili di un utente di tipo agenzia * includere una chiave opzionale negli headers denominata “RealUserMail” da valorizzare con un indirizzo email aggiuntivo a cui notificare il cambio stato delle richieste oltre ai destinatari già previsti (ad es. indirizzo email associato all’account che ha effettuato l’inserimento), del se cambio stato uguale a
3(evasa),6(in attesa di doc. corretta),12(lavorazione respinta) o14(sospesa per dati errati ed in attesa di correzione. * è altresì possibile assegnare un’etichetta arbitraria per contraddistinguere una richiesta indicando un testo qualsiasi nella chiave header opzionale denominataRealUserLabel(indicando ad esempio il nome di una filiale o il nome utente di un sistema esterno non censito in Procredito).
Per conoscere i valori consentiti nei campi del JSON per l’inserimento di una richiesta e le modalità ammesse relative agli allegati consultare le tabelle in Appendice B e Appendice C.
Riepilogo delle modalità per specificare i destinatari per la ricezione email di evasione delle pratiche:
- Di default viene utilizzato, senza necessità di specificarlo, l’indirizzo inserito in fase di registrazione dell’utente società, agenzia o collaboratore che sta inserendo la pratica.
- Può essere inviata una ulteriore notifica ad un indirizzo email a scelta che può essere indicato in fase di inserimento richiesta valorizzando la chiave header `RealUserMail`
- In aggiunta alle modalità descritte nei punti a. e b. può essere allegato anche un file JSON (jsonEmails) contenente una lista di id relativi agli indirizzi email salvati nella propria rubrica, ottenibili tramite una chiamata
GETalla webAPI /v1/Richiesta/GetCompanyEmails.
E’ possibile richiedere l’annullamento di una richiesta in stato 1 (in richiesta), 19 (precaricata) chiamando la seguente web API:
Integrazione con SIC ¶
Gli utenti abilitati ad un SIC, ad es. consorziati con CTC, su una o più tipologie di report potranno inoltrare un blocco di campi aggiuntivi nel JSON delle richieste, i campi saranno tutti obbligatori eccetto "IBAN" (v. esempio "Verifica Identità con SIC CTC" in appendice). Il servizio è al momento disponibile per i test solo in ambiente di collaudo. Per verificare quali tipi di richieste sono abilitati a CTC invocare
Dettaglio dei campi per CTC¶
HAS_CTC: bool (valorizzare a true se si desidera richiedere anche il report CTC )COD_ANAGRAFICA: varchar(16) (Codice Anagrafica CTC)COD_RAPPORTO: varchar(18) (Codice Rapporto CTC)NUMERO_RATE: int (Numero Rate)IMP_RATA_ATTUALE: decimal(9,2) (Importo rata attuale)IMP_MONTANTE: decimal(9,2) (Importo montante)DT_INIZIO_RAPPORTO: varchar(8) (Data inizio rapporto)IBAN: varchar(50) (IBAN, opzionale)
Una volta che la pratica sarà evasa il pdf verrà reso disponibile per il download tramite l'API
L'api /v2/RichiesteReport/DettaglioRichiesta/idRichiesta restituisce le informazioni inserite integrative per CTC e può essere utilizzata anche per ottenere l'idRichiestaCtc.
Warning
Il parametro idrichiestaCTC e idRichiesta (id della richiesta AF) sono due valori distinti.
Configurazione delle Personal Info¶
Ogni "Richiesta Antifrode" è prevista una parte comune identificata come "Personal Info". Collezionare e verificare tali dati come descritto nel paragrafo "Personal Info".
Configurazione delle informazioni per le sole "Richieste di Certificato"¶
Invocare via
per recuperare le informazioni riguardanti il costo delle richieste di tipo certificato (ID_TIPO_RICHIESTA = 10) in base al proprio account.
Esempio JSON di risposta:
Info
Nel caso in cui PrezzoFisso viene restituito come TRUE, nel JSON della richiesta di certificato bisogna impostare necessariamente a TRUE i campi ALLEGA_EC, EC_DOPPIO, ALLEGA_EC_OPZIONALE, SOLO_EC eccetto i flag opzionali ALLEGA_CUD e ALLEGA_EC4.
Nel caso in cui PrezzoFisso viene restituito come FALSE deve essere valorizzata a TRUE almeno una delle chiavi ALLEGA_EC, EC_DOPPIO, ALLEGA_EC_OPZIONALE,SOLO_EC, ALLEGA_EC4, ALLEGA_CUD.
Warning
EC_DOPPIO non più disponibile dal gg 11/06/2020 per accorpamento con estratto unificato, utilizzare solo `ALLEGA_EC`
Una volta che tutte le informazioni personali saranno state compilate si potrà procedere con la selezione dei certificati da richiedere:
Esempio di un frammento del JSON della "Richiesta di Certificato":
{
...
"ALLEGA_EC": false, //Estratto INPS
"ALLEGA_EC_OPZIONALE":false, //OBISM
"SOLO_EC": false, //Dettaglio pensionistico
"ALLEGA_CUD": false, //CUD
"ALLEGA_EC4": false, //ALTRO
...
}
Calcolo del credito richiesto per una richiesta Antifrode¶
Se la chiave PrezzoFisso è TRUE significa che il proprio contratto prevede un prezzo fisso per qualunque tipo di richiesta di certificato che sarà quindi equivalente al valore della chiave PrezzoBase.
Se la chiave PrezzoFisso è FALSE, per calcolare il costo del certificato occorrerà moltiplicare il valore della chiave PrezzoBase per il valore della chiave Moltiplicatore a tale somma va aggiunto il valore del PrezzoBase moltiplicato il numero di FLAG attivi tra tutti quelli disponibili meno uno.