Controllers¶
Ciascun controller contiene un insieme di funzionalità legate ad una specifica entità logica. Segue una panoramica dei controller disponibili attualmente nel sistema.
Controller Authenticate ¶
Contiene le API per il login ed il logout di un utente registrato (v. capitolo "Autenticazione") e per l'inizializzazione dell'ambiente.
Controller Init ¶
Contiene le API per l'inizializzazione del sistema
Controller Societa ¶
Contiene le API per la gestione di un account utente di tipo società
Controller Agenzia ¶
Contiene le API per la gestione di un account utente di tipo sotto-societa (ex agenzia)
Controller User (v.1.x) o Collaboratore (dalla v.2.x) ¶
Contiene le API per la gestione di un account utente di tipo collaboratore
Controller Geo ¶
Contiene le API per ottenere l’elenco di nazioni, città e province del sistema Security.
Controller Richiesta ¶
Le API del controller Richiesta sono utili per la gestione delle richieste Antifrode.
Permettono di inserire, precaricare, riallegare, modificare, visualizzare lo stato di una richiesta.
GET /v2/GetStatoRichiestaById/idRichiesta?noteGenerali=true¶
Restituisce lo stato di una richiesta e altre informazioni sintetiche.
{
"NoteGenerali": "4001 - Il soggetto non è titolare di trattamenti pensionistici.",
"IdRichiestaAF": 123123,
"IdStatoRichiesta": 3,
"DataAggiornamentoStato": "20220519142852"
}
GET /v2/Richiesta/GetRichiestaFullbyId/{idRichiestaAF}¶
e¶
GET /v2/RichiesteReport/DettaglioRichiesta/{idRichiestaAF}¶
Restituiscono il dettaglio in formato JSON della richiesta specificata nel parametro idRichiestaAF.
Vedi esempio in Appendice E.
GET /v2/Richiesta/Richieste?pageSize=10&$skip=0&$orderby=ID_RICHIESTA%20desc&$inlinecount=allpages\&dataRichiesta=NULL\&dataInizio=20240501\&dataFine=20240520¶
Restituisce le ultime 10 richieste (pageSize=10) inserite nel periodo indicato in dataInizio e dataFine. E’ possibile aggiungere ulteriori filtri per selezionare ad es. solo le richieste di una certa tipologia (\&tipoRating=ID_TIPO_RICHIESTA) o in un determinato stato (ad es. \&statoRichiesta=ID_STATO_RICHIESTA per ottenere le sole richieste evase). Contattaci per eventuali ulteriori dettagli su questa chiamata.
POST /v2/Richiesta/ModificaRichiesta/{idRichiestaAF}
Aggiorna una richiesta già esistente in stato 14 “Sospesa per dati errati ed in attesa di correzione” e la cambia in stato 1 'Richiesta' (entro i termini ammessi). Inviare come input il JSONFile e gli allegati relativi alla modulistica e ai documenti come in fase di inserimento nuova richiesta (quindi utilizzando i file container JSONfile, cfdocFile, etc).
Controller KYC ¶
Le API esposte nel controller KYC consentono di gestire i report ad evasione automatica detti anche report KYC (o KYB in caso di persone giuridiche), report automatici o richieste automatiche.
I singoli controlli automatici disponibili vengono o meno effettuati in base ad alcuni fattori come ad esempio la tipologia del documento di identità presente nella richiesta, la tipologia di contratto di lavoro, etc.
In caso un campo non obbligatorio utile per un determinato controllo non venisse inviato sarà possibile procedere comunque all’inserimento della richiesta ma il controllo non verrà effettuato ed il suo risultato non sarà quindi visibile nel report.
E’ possibile accedere via Swagger all’elenco delle api relative ai controlli automatici KYC digitando “KYC” al posto di “v1” e cliccando su “Explore”
Configurazione KYC ¶
Ogni richiesta automatica deve essere associata ad una configurazione KYC. Una configurazione è identificata da un ID_CONFIGURAZIONE (intero). Una configurazione raccoglie un insieme di parametrizzazioni tra cui i controlli automatici, il loro peso sul reting ed i campi di input necessari (fields).
A ciascun controllo è associato un peso da 10 a 100 per l’esito negativo (semaforo rosso) ed una percentuale del peso dell’esito negativo per ottenere un peso in caso di semaforo giallo.
Al termine dell’elaborazione di tutti i controlli previsti per un determinato report, il punteggio finale viene calcolato scalando dal valore 100 iniziale (semaforo verde) la somma degli esiti negativi (sia rossi che gialli), oppure sottraendo solo il peso più grande di un qualunque esito non positivo riscontrato (sia rosso che giallo).
Per il tipo di richiesta KYC (ID_TIPO_RICHIESTA = 20) i campi minimi obbligatori sono ID_TIPO_RICHIESTA, ID_CONFIGURAZIONE (in caso si abbiano attive più di una configurazione), NOME, COGNOME, CODICEFISCALE e TIPOLOGIA_FINANZIAMENTO (default "C") .
Per il tipo KYB (ID_TIPO_RICHIESTA = 24) sono ID_TIPO_RICHIESTA, ID_CONFIGURAZIONE (in caso si abbiano attive più di una configurazione), CODICE_FISCALE_ATC e TIPOLOGIA_FINANZIAMENTO (default "C").
Inserimento di una richiesta automatica¶
Per effettuare l’inserimento di una richiesta KYC è sufficiente effettuare una request http con method POST all’indirizzo:
\ v2/KYC/NuovaRichiestaKYC
includendo nell’apposito campo header un token valido e nel body della request un modello KYC debitamente compilato (v. esempio in Appendice D).
oppure in caso di richiesta KYC Aziende:
v2/KYC/NuovaRichiestaAzienda
includendo nell’apposito campo header un token valido e in un file allegato alla request, con nome container “JsonFile”, un modello KYB Azienda debitamente compilato (v. esempi in Appendice D).
Recupero di un report KYC in formato JSON e PDF¶
Una volta inserita la richiesta verrà evasa automaticamente dopo alcuni secondi.
A lavorazione ultimata sarà possibile richiedere il risultato del report in formato JSON o PDF invocando le rispettive API:
GET v2/KYC/GetReport/idRichiesta (vedi JSON di esempio in Appendice E).
oppure
GET v2/KYC/GetReportPDF/idRichiesta (per il download del PDF)
Nel caso sia stata richiesta una Visura XML, per ottenere il relativo file, chiamare:
GET /v2/Faro/Aziende/Scarica_VisuraOrdinariaXML/idRichiestaAF¶
Nel caso sia stata richiesta una Visura PDF, per ottenere il relativo file, chiamare:
GET /v2/Faro/Aziende/Scarica_VisuraOrdinariaPDF/idRichiestaAF
¶
Nel caso sia stata richiesto un Bilancio XBRL chiamare
GET /v2/Faro/Aziende/Scarica_BilancioXBRL¶
specificando in tutti e quattro i casi nel parametro idRichiestaAF l’id della richiesta KYB ottenuto a seguito della chiamata a v2/KYC/NuovaRichiestaAzienda
Validazione di una richiesta ¶
In caso di anomalie in fase di validazione della richiesta o di rilevamento conflitti rispetto alla configurazione dell'utenza del sistema Lending Security,
gli errori, ove previsto, saranno restituiti come nel seguente formato di esempio:
{
"StatusCode": 4009,
"StatusMessage": "Correggere le informazioni indicate nell'elenco degli errori di validazione della richiesta e riprovare.",
"ReasonPhrase": "Conflict",
"CompleteValidationCodesAndDescription": {
"ValidationList": [
{
"FieldName": "NUM_DOCUMENTO",
"ErrorDescription": "Il campo NUM_DOCUMENTO è obbligatorio per il controllo 3 : Controllo numerazione Carta d'Identità cartacea.",
"Field": 130,
"ErrorCode": 80
}
]
},
"ScipafiOnlyValidationList": [
{
"FieldName": "NUM_DOCUMENTO",
"ErrorDescription": "Il campo NUM_DOCUMENTO è obbligatorio per il controllo 7 : Verifica Scipafi",
"Field": 130,
"ErrorCode": 80
}
]
}
Controller FARO_Aziende¶
Le API esposte nel controller FARO_Aziende consentono il download del relativo output (xml, pdf o XBRL) richiesto in fase di inserimento in base alla configurazione utilizzata.
Controller File ¶
Le API esposte nel controller File consentono di effettuare l'upload dei file ed il download dell’esito della lavorazione di una richiesta in formato pdf o in formato zip (in caso di richiesta di tipo Certificato) , permettono inoltre il download dei documenti LS (modulistica, allegati, etc.).
POST /v2/File/AllegaDocumentazioneAggiornaStato/{idRichiestaAF}¶
Carica gli allegati associati ad una richiesta in stato 6 “In attesa di documentazione corretta” e la cambia in stato 1 'Richiesta' (entro i termini ammessi). Inviare in allegato i file relativi alla modulistica e ai documenti (non inviare il JSONFile) come in fase di inserimento nuova richiesta.
E’ possibile individuare i file mancanti utilizzando il JSON restituito dall'API v2/Richiesta/Richieste nel quale sono presenti, per ciascuna richiesta in quello stato, due oggetti relativi agli allegati, v. esempio:
"allegati": {
"codiceFiscaleDocumentoIdentita": true,
"privacyFirmata": false,
"delegaLSMandato": true,
"permSog": true,
"altro": true,
"noteGenerali": "SI RIMANE IN ATTESA DELLA PRIVACY FIRMATA."
},
"allegatiDigitali": {
"privacyDigFirmata": true,
"delegaDig": true,
"mandato1Dig": true,
"mandato2Dig": true
}
Il valore false indica che il file può essere allegato mediante \~/v2/File/AllegaDocumentazioneAggiornaStato/{idRichiestaAF}
GET v2/File/DownloadEsitoRichiestaAF/{idRichiestaAF}¶
Consente di scaricare l’esito della lavorazione in formato zip (in caso di richieste di tipo “Certificato”) o pdf (negli altri casi) della richiesta associata all’id passato come parametro. In ambiente di test è possibile simulare il download dell’esito di una richiesta con idRichiestaAF = 123
GET v2/File/GetAllegatiReportAntifrode/idRichiesta/Allegato/idAllegato¶
Consente il download di un singolo file per le richieste di tipo certificato.
V. tabella in appendice B per le tipologie di file disponibili (idAllegato).
GET v2/File/DownloadModulistica/{idModulo}?{isDigital}&{idModPat}¶
Consente di scaricare un file in base all’idModulo passato come parametro.
Possibili valori di idModulo:
- Privacy = 1
- DelegaEMandato = 2
- SoloMandato = 4
- SoloDelega = 8
Se il parametro query string “isDigital” viene valorizzato ad 1 verrà scaricato il relativo file da firmare digitalmente:
Es. Download del primo mandato (idModPat =1) da firmare digitalmente
v1/Modulistica/DownloadModulistica/SoloMandato?isDigital=true&idModPat=1
Es. Download del secondo mandato (idModPat =2) da firmare digitalmente
v1/Modulistica/DownloadModulistica/SoloMandato?isDigital=true&idModPat=1
Controller Validate ¶
Validazione del JSON di una richiesta Antifrode
POST v1/Validate/Richiesta ¶
(passare il JSON della richiesta nel body della Request)
Restituisce l’elenco dei codici dei campi non validi con i relativi errori di validazione.
GET v1/Validate/GetAllValidationErrorCodes¶
Restituisce l’elenco dei codici di errore di validazione disponibili nel sistema di validazione.
GET v1/Validate/GetAllFields¶
Restituisce l’elenco dei codici dei campi disponibili nel sistema di validazione.
Controller Modulistica ¶
Le API esposte nel controller Modulistica permettono il download della modulistica LS precompilata a seguito precaricamento richiesta.