Passa al contenuto principale

API Pass AIS

Fabrick Pass, tramite le API esposte, consente agli FPP di accedere ai conti dei propri clienti, ovviamente dopo aver ottenuto il loro consenso. Per questo motivo, il primo passo è la fase di onboarding del cliente.

Introduzione​

L’immagine seguente mostra il flusso ad alto livello:

aispOnboardingSeqDiagram

Flusso consigliato​

Questa sezione mostra il diagramma del flusso API consigliato. Tutte le API verranno descritte nelle sezioni successive.

aispFppFlowChart

Onboarding​

Per avviare il processo di onboarding, l’FPP deve invocare l’endpoint POST CreateOnBoardingUser, che consente di inizializzare il flusso di onboarding Fabrick per l’utente. Come mostrato di seguito, il body di input della request contiene una serie di informazioni relative all’utente e alcuni parametri utili alla procedura, nello specifico:

  • mode: la modalità del workflow. Per questo prodotto sarà sempre "REDIRECT".

  • CustomerInfo

    • Informazioni anagrafiche dell’utente (nome, cognome, ecc.);
    • companyUserCode: stringa libera con cui l’FPP identifica in modo univoco ciascun cliente e grazie alla quale sarà possibile mappare le informazioni dell’utente in Fabrick;
    • companyContractCode: stringa libera aggiuntiva e opzionale; è un codice che identifica il contratto tra l’utente e l’FPP.
    • subjectType: tipologia utente; per questo prodotto il valore è sempre NATURAL_PERSON. Non è possibile creare onboarding per persone giuridiche.

  • CompletionRedirectUrls: parametro che contiene i link ai quali l’utente deve essere reindirizzato al termine della fase di onboarding; in particolare, l’FPP deve inserire un link in caso di successo e uno in caso di errore.

I parametri richiesti della request sono: entrambe le URI dell’oggetto completionRedirectUrls, subjectType, companyUserCode, name, surname, fiscalCode, birthDate, birthPlace, homeAddress.country.

Assicurati che nome e cognome siano corretti e completi, perché verranno utilizzati per la fase di riconoscimento. Devono quindi coincidere con quelli indicati nello SPID, nel conto bancario o nel documento, a seconda del metodo scelto dal PSU.

Infine, citizenship, birthCountryCode e country devono essere valorizzati secondo lo standard ISO 3166-1 alpha-2.

POST /v4.0/access/users

{
    "mode": "REDIRECT",
    "completionRedirectUrls": {
        "onSuccess": "http://fpp-app.com?onb=ok",
        "onFailure": "http://fpp-app.com?onb=ko"
    },
    "customerInfo": {
        "subjectType": "NATURAL_PERSON",
        "companyUserCode": "abc123",
        "name": "Mauro",
        "surname": "Rossi",
        "fiscalCode": "RSSMRA63R30F205H",
        "birthDate": "1963-11-30",
        "birthPlace": "Milano",
        "citizenship": "IT",
        "birthCountryCode": "IT",
        "homeAddress": {
           "address": "via Rossi",
           "buildingNumber": 187,
           "postalCode": "20100",
           "city": "Milano",
           "province": "MI",
           "country": "IT"
        },
        "currentAddress": {
          "address": "via Rossi",
          "buildingNumber": 187,
          "postalCode": "20100",
          "city": "Milano",
          "province": "MI",
          "country": "IT"
        },
        "contacts": {
          "mobile": "3331234567",
          "mail": "m.rossi@gmail.com"
        } 
     }
}

In caso di luogo di nascita estero, sarà necessario impostare il parametro birthPlace con il nome del Paese in italiano secondo lo standard ISO_3166-1 (es. Stati Uniti, Cina, Egitto, …).

Il parametro mobile è utile solo in ambiente di pre-produzione. Il valore +393334445555 consente di saltare il controllo del codice fiscale.

L’output sarà simile al seguente:

{
    "status": "OK",
    "payload": {
        "mode": "REDIRECT",
        "completionRedirectUrls": {
            "onSuccess": "http://fpp-app.com?onb=ok",
            "onFailure": "http://fpp-app.com?onb=ko"
        },
        "customerInfo": {
            "subjectType": "NATURAL_PERSON",
            "companyUserCode": "",
            "name": "Mauro",
            "surname": "ROSSI",
            "fiscalCode": "RSSMRA63R30F205H",
            "birthDate": "1963-11-30",
            "birthPlace": "Milano",
            "citizenship": "IT",
            "homeAddress": {
                "address": "via Rossi",
                "buildingNumber": 187
                "postalCode": "20100",
                "city": "Milano",
                "province": "MI",
                "country": "IT"
            },
            "currentAddress": {
                "address": "via Rossi",
                "buildingNumber": 187
                "postalCode": "20100",
                "city": "Milano",
                "province": "MI",
                "country": "IT"
            },
            "contacts": {
                "mobile": "3331234567",
                "mail": "m.rossi@gmail.com"
            }
        },
        "userOnboardingId": "f118f1f1-...dfb3282",
        "initiationRedirectUrl": "https://fabrick.com/pass/..."
    }
}

In output l’FPP otterrà due informazioni fondamentali:

  • initiationRedirectUrl: URL a cui reindirizzare l’utente per avviare la procedura di onboarding. Il link ha una durata di 3 giorni.
  • userOnboardingId: codice che identifica l’onboarding di un determinato utente.

Non è necessario, né consigliato, salvare il link initiationRedirectUrl, perché Fabrick memorizza gli step effettuati dall’utente. Quando lo stesso utente prova un nuovo onboarding, riprenderà dal punto in cui si era fermato e/o aveva abbandonato la volta precedente.

La procedura di onboarding Fabrick include tutte le fasi necessarie affinché l’utente possa aggregare i propri prodotti bancari. In particolare, verranno eseguiti i seguenti passaggi:

  • Creazione credenziali Fabrick Pass e verifica email;
  • Conferma dei dati personali;
  • Riconoscimento utente tramite uno dei servizi disponibili, ossia Strong Customer Authentication, SPID o Verifica documentale;
  • Compilazione del questionario AML (anti-money laundering);
  • Firma del contratto con Fabrick.

Una volta completati i passaggi descritti sopra, l’utente avrà fornito il consenso all’FPP per accedere a uno o più dei propri conti.

In termini tecnici, questo step creerà un Contract tra l’utente appena registrato e il Service esposto dall’FPP e, in seconda battuta, un’Authorization su uno o più conti specifici.

Passiamo a un esempio per chiarire i concetti appena citati. Supponiamo che Digitopolis Spa, azienda leader nel settore digitale, voglia lanciare due nuovi progetti per i propri clienti: MyAccounts e TaacDiscount. Entrambi i progetti prevedono lo sviluppo di applicazioni web e mobile. La prima applicazione consentirà a un cliente di aggregare e visualizzare i propri conti anche se appartengono a banche diverse, permettendo all’utente di avere una panoramica completa. TaacDiscount, invece, è pensata per i dipendenti di front office e per i sales manager: questi ultimi, previa autorizzazione del cliente ad accedere a uno dei suoi conti, potranno offrire uno sconto e una modalità di finanziamento personalizzata per il prodotto appena acquistato. La stessa applicazione sarà poi inclusa anche nel sito e-commerce, così che l’utente possa procedere autonomamente. Per realizzare questi progetti, Digitopolis contatta Fabrick per sfruttare le potenzialità di Fabrick Pass.

In un caso come questo, Digitopolis Spa rappresenta la Company che Fabrick inserirà in anagrafica, a cui verrà associato un companyId:

Company: Digitopolis Spa
CompanyId: 1

Inoltre, Digitopolis Spa intende sviluppare due app diverse e ciascun cliente può decidere liberamente se utilizzare o aderire a una, all’altra o a entrambe; per questo motivo ciascuno dei due progetti corrisponderà a un Service Fabrick Pass. Ogni service sarà referenziato dal proprio serviceId e ad esso verrà associata una apiKey. Quindi il primo service sarà configurato come segue:

Service: MyAccounts
serviceId: 1
apiKey: 123abc456def123abc456def
apiKeyId: 1234

mentre il secondo service:

Service: TaacDiscount
serviceId: 2
apiKey: fed654cba321fed654cba321
apiKeyId: 4321

In questo modo, ciascun service sarà totalmente indipendente dall’altro; proseguiamo quindi l’esempio considerando TaacDiscount.

Il cliente Carlo Rossi acquista tutto ciò che gli serve per lo smart working sul sito online di Digitopolis. Al momento del pagamento, entra in gioco TaacDiscount offrendo uno sconto e una modalità di finanziamento personalizzata; per accettare, Carlo deve fornire a Digitopolis Spa il consenso a visualizzare le informazioni relative a uno dei suoi conti bancari. A questo punto, il cliente compilerà il form mostrato dalla UI inserendo i propri dati personali e, una volta completato, verrà reindirizzato alla Fabrick Dashboard, la pagina che gli consentirà di completare la fase di autenticazione e SCA (Strong Customer Authentication). In questa fase l’utente creerà un Contract, cioè un contratto tra il cliente e il service su cui si sta registrando:

companyId: 1
serviceId: 2
companyUserCode: carlo.rossi@email.it
userId: "1001"

Ogni contratto è identificato univocamente da un contractId, nel nostro esempio:

contractId: 50

Proseguendo nella fase di onboarding, il sig. Carlo dovrà scegliere quale conto (in caso di conti su banche diverse o più conti sulla stessa banca) autorizzare all’accesso da parte di Digitopolis Spa: questa selezione è definita Authorization. Infatti, verrà creata un’autorizzazione tra il contratto creato e il conto in questione, identificato da un accountId.

contractId: 55
accountId: 372

Ogni authorization è anch’essa identificata univocamente tramite un authorizationId:

authorizationId: 678

Una volta completata la fase di onboarding, l’utente verrà reindirizzato al sito di Digitopolis Spa e potrà procedere con l’acquisto usufruendo dello sconto e del finanziamento offerti dall’azienda.

Dettagli degli step di onboarding​

Riconoscimento PSU​

La fase di onboarding consente di registrare un utente (PSU) sulla piattaforma Fabrick. Se il PSU è già presente, verrà reindirizzato alla pagina di login: per quanto riguarda l’Italia, il controllo avviene tramite codice fiscale.

Per tutti gli altri Paesi, invece, il controllo avviene direttamente sui dati anagrafici del PSU. In futuro entrambi i casi verranno gestiti nello stesso modo grazie a un codice identificativo univoco.

Facilitazioni per i test​

In ambiente di pre-produzione, per facilitare i test, è stato creato un workaround per saltare la validazione del codice fiscale. Inserendo il numero di telefono "+393334445555" sarà possibile inserire qualsiasi CF senza rispettare la corrispondenza con i dati anagrafici del PSU. La lunghezza del CF deve essere in ogni caso rispettata. Naturalmente è sempre possibile inserire anche dati reali.

SuperUser e TechUser​

SuperUser e TechUser, per ovvie ragioni, risulteranno già registrati su Fabrick; per questo motivo, la prima volta che provano la fase di onboarding verranno reindirizzati alla pagina di login. Per accedere è sufficiente inserire le stesse credenziali utilizzate per accedere alla console https://www.platfr.io/#/platfr/login.

Per lo stesso motivo non è possibile utilizzare i dati di SuperUser e TechUser per testare la fase di onboarding o gli step di login in pre-produzione.

PSU registrato in ambiente di produzione​

Una volta che un PSU completa con successo la fase di onboarding in ambiente di produzione, non potrà più completare un nuovo onboarding né accedere alla dashboard dell’ambiente di pre-produzione. Per i test è sempre possibile utilizzare i dati mock indicati sopra.

Aggiornamento dati PSU​

Una volta completato l’onboarding, non è più possibile modificare i dati anagrafici del PSU, in particolare tutte le informazioni utili al calcolo del codice fiscale. Il PSU può invece aggiornare in qualsiasi momento tutte le altre informazioni, come residenza, indirizzo ed email per ricevere comunicazioni, direttamente dalla dashboard Fabrick. I dati aggiornati non vengono trasmessi all’FPP, quindi in questo caso potrebbe verificarsi un disallineamento tra Fabrick e FPP.

Onboarding sospeso​

La fase di onboarding può essere interrotta in qualsiasi momento; la volta successiva il PSU riprenderà esattamente dal punto in cui si era fermato. Il flusso ripartirà da zero solo fino alla conferma dell’indirizzo email.

companyUserCode vs indirizzo email​

Come indicato in precedenza, il servizio POST CreateOnBoardingUser accetta in input l’indirizzo email e il companyUserCode. Quest’ultimo serve esclusivamente a creare un mapping tra Fabrick e l’FPP per il PSU: può quindi essere, ad esempio, il codice meccanografico del cliente dell’FPP oppure può coincidere con l’indirizzo email.

L’indirizzo email, invece, ha una doppia finalità:

  • username per accedere alla dashboard Fabrick
  • contatto per le comunicazioni da parte di Fabrick verso il PSU

Sebbene inizialmente i due campi possano essere valorizzati con lo stesso indirizzo email, potrebbe accadere che in seguito differiscano. Il PSU, infatti, può aggiornare e cambiare l’email a cui ricevere le comunicazioni dalla propria dashboard, ma non può (ad oggi) cambiare lo username usato per accedere alla dashboard. Per esigenze specifiche, contattare Fabrick.

In caso di recupero password (funzionalità mostrata dalla UI), Fabrick invia un’email all’indirizzo corrispondente allo username e non a quello di contatto.

Va inoltre notato che l’indirizzo email preso in considerazione da Fabrick non è necessariamente quello passato tramite API, ma quello confermato dal PSU nella prima pagina di onboarding, che può essere modificato immediatamente dal PSU.

Infine, segnaliamo che companyUserCode e indirizzo email saranno sempre distinti, anche se valorizzati con lo stesso valore.

Esempio:

L’FPP invia tramite il servizio POST CreateOnBoardingUser:

Il PSU viene reindirizzato alla pagina Fabrick, dove come primo step deve confermare l’email e, supponiamo, la modifica in paolo2@mail.com; avremo quindi:

Dopo aver completato l’onboarding, il PSU si autentica sulla dashboard e cambia l’email di contatto in paolo3@mail.com; la situazione sarà quindi:

Esempio di errori​

ErroreDescrizioneSoluzione
Fiscal code is not validIl codice fiscale è errato o non è coerente con i dati anagrafici inseritiVerificare la correttezza del codice fiscale utilizzando, ad esempio, un generatore online di codice fiscale
Cannot validate fiscal code [x] with user [y]Il cliente è già registrato, ma il codice fiscale e l’email inseriti non corrispondono a quelli presenti nell’anagrafica FabrickContattare Fabrick con i dettagli (correlationId o workflowId). Un esempio potrebbe essere l’aggiunta di un SuperUser o TechUser al di fuori del portale: in tal caso l’utente verrà aggiunto a Fabrick ma senza alcun codice fiscale

Ottenere la lista clienti​

Per ottenere la lista clienti è sufficiente invocare l’API POST Search Users.

Ottenere i dettagli utente​

L’endpoint GET getUserDetails consente di recuperare informazioni su un singolo utente.

Nel path dell’endpoint è necessario specificare lo userId, che è il codice che identifica univocamente un utente all’interno di Fabrick.

GET api/fabrick/pass/v4.0/access/users/{{userId}}

Ad esempio:

GET api/fabrick/pass/v4.0/access/users/1234

{
    "status": "OK",
    "payload": {
        "userCompanyCode": "m.rossi99@fabrick.com",
        "userId": "1234",
        "companyId": "22",
        "hasActiveContract": true,
        "hasActiveAuthorizations": true,
        "hasValidKyc": true
    }
}

Nei dettagli utente è possibile verificare anche se l’utente ha un KYC valido (hasValidKyc). Nel prodotto Fabrick Pass (versione standard) si tratta di un vincolo: se il KYC dell’utente non è valido, l’FPP non può ottenere i dati dei conti dell’utente.

Solo se hasValidKyc = false, il parametro userStatus è presente nel body della response. Questo parametro fornisce maggiori informazioni sul KYC non valido e può assumere i seguenti valori:

  • DATA_CHECK: sono in corso verifiche lato Fabrick; l’utente riceverà comunicazioni per proseguire una volta completati i controlli
  • USER_ACTION: l’utente ha ricevuto istruzioni per completare il processo dopo un KO (es. deve ricaricare documenti o foto)
  • REJECTED: l’utente non è idoneo a utilizzare il servizio

In caso di USER_ACTION il cliente riceverà un’email da Fabrick. All’interno dell’email sarà presente un link alle pagine Fabrick per consentire al cliente di regolarizzare la propria posizione. Il link ha una durata di 168 ore (7 giorni).

Potrebbe inoltre essere presente il parametro aggiuntivo detailsKycMessage, un array che contiene informazioni extra relative allo stato KYC e/o AML del cliente.

In tutti i casi sarà sempre possibile reindirizzare il cliente alla pagina di onboarding dell’FPP: Fabrick riconoscerà il cliente e lo riporterà allo step da completare.

Nel caso in cui il link sopra citato, inviato via email da Fabrick, sia scaduto, un nuovo onboarding sarà l’unica soluzione per consentire all’utente di completare il processo con successo.

È quindi importante considerare questo aspetto durante lo sviluppo della UX dell’applicazione.

Modificare il companyUserCode​

E' sempre possibile modificare il parametro companyUserCode tramite la seguente API:

PUT /v4.0/access/users/{{userId}
{
  "userCompanyCode": "test@gmail.com"
}

Ottenendo in risposta il nuovo campo aggiornato come mostra il seguente esempio:

{
  "status": "OK",
  "payload": {
    "userCompanyCode": newTest@gmail.com,
    "userId": "1234"
  }
}

Disabilitare un utente​

L’FPP può disabilitare un utente semplicemente invocando l’API PUT DisableUser:

PUT /v4.0/access/users/{{userId}/inactive

L’utente verrà disabilitato solo per il service indicato (quindi in base alla apiKey utilizzata). Questo significa che l’utente rimarrà attivo sia per eventuali altri servizi dell’FPP sia per eventuali altri FPP a cui è associato.

È sempre possibile riabilitarlo in qualsiasi momento tramite gli step di onboarding, che verranno ovviamente semplificati poiché molti passaggi sono già salvati. Lo userId rimarrà naturalmente lo stesso.

L’utente può eseguire la stessa operazione in autonomia dalla propria dashboard Fabrick.

Un utente disabilitato non potrà più visualizzare le informazioni sui conti dalla dashboard Fabrick.

Ottenere lo stato dell’onboarding​

In qualsiasi momento l’FPP può conoscere lo stato di un determinato flusso di onboarding invocando la GET getOnBoardingUser e valutando il parametro status.

GET /v4.0/access/users/onboardings/{{userOnboardingid}}

Nella response il parametro status si riferisce esclusivamente alla navigazione, cioè è legato solo alla parte grafica e all’esperienza utente (vedi Workflow Details).

Per questo motivo gli FPP possono evitare di integrare questa API e invocare solo il servizio GET getUserDetails.

Gestione consensi e autorizzazioni​

Questa sezione descrive il workflow UpdateAggregation che consente ai clienti dell’FPP di rinnovare il proprio consenso e, in caso di nuova aggregazione, di concedere autorizzazioni direttamente all’FPP.

Il workflow può essere inizializzato dall’FPP tramite l’API POST UpdateAggregation, come mostrato nell’esempio seguente:

POST /v4.0/access/update-aggregation

{
    "mode": "REDIRECT",
    "completionRedirectUrls": {
        "onSuccess": "http://google.it",
        "onFailure": "http://yahoo.it"
    },
    "userId":"123123" 
}

Come noto, lo userId viene recuperato tramite il servizio POST SearchUsers.

La response sarà simile alla seguente:

{
    "status": "OK",
    "payload": {
        "initiationRedirectUrl": "https://fabrick.com/../pass/v4.0/update-aggregation/d2a4...8?jwtToken=eyJr...0HU",
        "status": "WORK_IN_PROGRESS",
        "workflowId": "d2a4afde-1234-5678-9876-796ecad2b8b8",
        "createdDatetime": "2023-12-13T09:29:59.030+0000"
    }
}

La durata di initiationRedirectUrl è 72 ore.

Il workflow consiste nei seguenti step:

  • Login PSU
  • La UI mostra una panoramica di conti e banche del PSU (step REN0)
  • Flussi di aggregazione conto o rinnovo consenso (step ProductAggregation)
  • Step in cui il PSU gestisce le autorizzazioni dei conti appena aggregati (step REN1)

Dopo il login, il PSU potrà visualizzare e gestire tutti i propri conti:

  • eliminare uno o più conti;
  • revocare un consenso a Fabrick e di conseguenza anche all’FPP;
  • rinnovare un consenso (indipendentemente dal fatto che sia scaduto o meno);
  • aggregare uno o più nuovi conti.

Ottenere la lista dei consensi (deprecata)​

È possibile verificare la data di scadenza di tutti i consensi per utente tramite il servizio POST SearchConsents. Questo servizio restituisce la lista dei consensi con una data di scadenza compresa tra la data corrente e la data corrente + expiringInDays, indipendentemente dal loro stato. I consensi scaduti prima del giorno della richiesta non verranno quindi mostrati.

POST /v4.0/access/consents/search HTTP/1.1

{
  "expiringInDays": 10
}

In questo esempio otterrò tutti i consensi in scadenza nei prossimi 10 giorni.

Di seguito un esempio di risposta:

{
    "status": "OK",
    "payload": {
        "list": [
            {
                "consentId": "48ec3dc6-1234-5678-9101-68ee6e253253",
                "userId": "1",
                "createdDatetime": "2022-10-24T15:52:33.436+0200",
                "startDatetime": "2022-10-24T15:52:33.436+0200",
                "endDatetime": "2023-01-21T00:00:00.000+0100",
                "status": "EXPIRED"
            },
            ...
            {
                "consentId": "008ab1ce-9876-5432-1234-11eefaf8776b",
                "userId": "2",
                "createdDatetime": "2022-10-24T16:35:59.440+0200",
                "startDatetime": "2022-10-24T16:35:59.440+0200",
                "endDatetime": "2023-01-21T23:59:59.000+0100",
                "status": "EXPIRED"
            }
        ]
    }
}

dove:

  • consentId: indica l’id univoco relativo al consenso
  • userId: indica lo userId
  • createdDatetime: indica la data di creazione del consenso
  • startDatetime: indica la data di inizio del consenso (coincide sempre con createdDatetime)
  • endDatetime: indica la data di scadenza del consenso
  • status: indica lo stato del consenso (vedi doc Consent details)

Consents scheduler​

Ogni giorno, alle 4:00 del mattino, vengono controllate le date di scadenza di tutti i consensi e, se queste corrispondono alla data corrente, lo stato del consenso viene aggiornato a «SCADUTO».