Vai al contenuto

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:

v2/Richiesta/Common/Validate/PersonalInfoValidateStep1

inviando il seguente JSON nel body della POST

{
    "NOME": "Mario",
    "COGNOME": "Rossi",
    "CODICEFISCALE": "RSSMRA75A01H501X"
}

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:

v2/Richiesta/Common/Validate/PersonalInfoValidateStep2

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:

/v2/GEO/GetCitiesByProvince/{SiglaProvincia}

Per ulteriori specifiche sui campi chiusi di una "Richiesta" v. Appendice B.

Campi ISTAT utilizzabili nel json delle richieste

  1. CODICE_ISTAT_LUOGO_NASCITA
  2. CODICE_ISTAT_CITTA_RESIDENZA
  3. CODICE_ISTAT_CITTA_RESIDENZA_REAL
  4. CODICE_ISTAT_COMUNE_RILASCIO
  5. CODICE_ISTAT_COMUNE_RILASCIO_SOG
  6. CODICE_ISTAT_CITTA_SEDE_ATC

che affiancano o sostituiscono, rispettivamente, i seguenti:

  1. LUOGONASCITA + PROVINCIANASCITA
  2. CITTA_RESIDENZA + PROVINCIA_RESIDENZA
  3. CITTA_RESIDENZA_REAL + PROVINCIA_RESIDENZA_REAL
  4. COMUNE_RILASCIO + PROVINCIA_RILASCIO
  5. COMUNE_RILASCIO_SOG + PROVINCIA_RILASCIO_SOG
  6. CITTA_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:

v2/Richiesta/NuovaRichiesta

per tutte le tipologie richieste ad eccezione dell’Analisi Datore e delle richieste automatiche oppure

v2/Richiesta/NuovaRichiestaDatore

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/ElencoAgenzie

    Restituisce l’elenco delle agenzie di un utente di tipo società * GET v2/Agenzia/ElencoAgenzieVisibili

    Restituisce 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) o 14 (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 denominata RealUserLabel (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:

  1. 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.
  2. 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`
  3. 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 GET alla web API /v1/Richiesta/GetCompanyEmails.

E’ possibile richiedere l’annullamento di una richiesta in stato 1 (in richiesta), 19 (precaricata) chiamando la seguente web API:

POST /v2/Richiesta/AnnullaRichiesta/{idRichiestaAF}

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

GET ~v2/RichiesteReport/DettaglioTipiRichiesta

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

GET ~/v2/Ctc/DownloadReport/{idRichiestaCtc}

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

GET v2/Richiesta/Certificate/SubscriptionInfo

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:

{
    "PrezzoBase": 1,
    "PrimoMoltiplicatore": 2,
    "PrezzoFisso": false
}

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.