Passa al contenuto principale

API di Affiliazione

Gestione delle sottoscrizioni​

Come anticipato, ogni TTPP dovrà gestire la parte di affiliazione con terze parti per consentire a queste ultime di utilizzare i servizi esposti.

Creazione della sottoscrizione​

Per avviare una fase di affiliazione, il TTPP dovrà invocare il servizio POST CreateAffiliatedSubscription come mostrato di seguito:

POST /api/fabrick/platform/v4.0/affiliations/{affiliationCode}/affiliated-subscriptions

{
    "affiliatedSubscriptionCode": "testGrantorCode",
    "customerMetadata": {
        "grantorFiscalCode": "12345678910",
        "grantorCode": "testGrantorCode",
        "grantorCountryCode": "IT",
        "grantorName": "Gianni",
        "grantorSurname": "Rossi",
        "grantorBusinessName": "Idraulico Rossi srl",
        "grantorEmail": "gianni.rossi@fabrick.com"
    },
    "completionRedirectUrls": {
        "onSuccess": "https://www.fabrick.com/",
        "onFailure": "https://www.google.com/"
    }
}

dove:

  • affiliationCode: è un codice univoco fornito e comunicato al TTPP durante la fase di setup
  • affiliatedSubscriptionCode: è una stringa valorizzabile liberamente per facilitare eventuali mappature o per identificarla più facilmente in seguito
  • grantorFiscalCode: indica il codice fiscale del garante (il codice fiscale della persona giuridica, non della persona fisica)
  • grantorCode: è una stringa associabile al garante. Ad esempio, può coincidere con il parametro affiliatedSubscriptionCode. Per poter riutilizzare lo stesso grantorCode, è necessario prima annullare la richiesta di sottoscrizione affiliata.
  • grantorCountryCode: indica il codice paese secondo lo standard ISO 3166-1 alpha-2
  • grantorName: indica il nome del garante
  • grantorSurname: indica il cognome del garante
  • grantorBusinessName: indica la ragione sociale del garante
  • grantorEmail: indica l'indirizzo email del garante
  • completionRedirectUrls: questo oggetto contiene i due URL ai quali il cliente verrà reindirizzato al termine della creazione della sottoscrizione: l'URL indicato in onSuccess in caso di successo e quello indicato in onFailure in caso contrario.

La risposta sarà:

{
    "affiliatedSubscriptionId": 1,
    "affiliatedSubscriptionCode": "subCode",
    "redirectUrl": "https://www.fabrick.com/affiliation/...",
    "createdDatetime": "2022-07-15T09:55:46.865Z",
    "acceptedDatetime": "2022-07-15T09:55:46.865Z",
    "declinedDatetime": "2022-07-15T09:55:46.865Z",
    "cancelledDatetime": "2022-07-15T09:55:46.865Z",
    "expiredDatetime": "2022-07-15T09:55:46.865Z",
    "status": "WAITING_ACCEPTANCE",
    "customerMetadata": {
      ...
    }
}

dove:

  • affiliatedSubscriptionId: identifica univocamente la richiesta di sottoscrizione appena creata
  • redirectUrl: è l'URL al quale il consumer deve essere reindirizzato per completare la fase di affiliazione. Questo link ha una durata di 30 giorni, ovvero sarà sempre possibile interrompere la procedura di onboarding e riprenderla dallo stesso link creato in precedenza. Anche nel caso in cui il FPP crei un nuovo link, Fabrick ricorderà tutti i passi già eseguiti in precedenza (ad esempio registrazione utente, registrazione azienda, AML, ecc.), ovviamente dopo il login dell'utente.
  • createdDatetime: indica la data di creazione della richiesta
  • acceptedDatetime: indica la data di accettazione della richiesta da parte del consumer
  • declinedDatetime: indica la data di rifiuto della richiesta da parte del consumer
  • expiredDatetime: indica la data di scadenza della richiesta se il consumer non ha intrapreso alcuna azione (accettazione o rifiuto)
  • cancelledDatetime: indica la data di annullamento della sottoscrizione
  • status: identifica lo stato dell'operazione, può assumere i seguenti valori:
    • ACCEPTED: il consumer accetta la richiesta di affiliazione del TTPP;
    • EXPIRED: la richiesta di affiliazione scade prima del rifiuto/accettazione da parte del consumer;
    • CANCELLED: il TTPP ha annullato l'affiliazione;
    • WAITING_ACCEPTANCE: la richiesta deve essere accettata o rifiutata dal consumer;
    • WAITING_ACCEPTANCE_BY_FABRICK: la richiesta deve essere accettata o rifiutata da Fabrick (può richiedere fino a 2 settimane).

Dettagli sull'onboarding​

SuperUser e TechUser​

I SuperUser e i TechUser, per ovvie ragioni, saranno già registrati su Fabrick; per questo motivo, la prima volta che accedono alla 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 la stessa ragione, non è possibile utilizzare i dati di SuperUser e TechUser per testare le fasi di onboarding o di login in pre-produzione.

PSU registrati nell'ambiente di produzione​

Una volta che un PSU completa con successo la fase di onboarding nell'ambiente di produzione, non sarà più in grado di completare un nuovo onboarding né di accedere alla dashboard dell'ambiente di pre-produzione. Per i test è sempre possibile utilizzare dati mock come indicato in precedenza.

Una volta completato l'onboarding, il nuovo affiliato riceverà un'email da Fabrick di conferma del flusso completato (non riceverà email successive a seguito degli aggiornamenti di stato).

Ricerca sottoscrizioni​

In qualsiasi momento, un TTPP potrà sempre visualizzare l'elenco delle proprie sottoscrizioni o effettuare una ricerca specifica tramite il servizio POST SearchAffiliatedSubscriptions come mostrato di seguito:

POST /api/fabrick/platform/v4.0/affiliations/{affiliationCode}/affiliated-subscriptions/search

Come si evince dal modello di input, è possibile filtrare per qualsiasi parametro. La paginazione è obbligatoria; di seguito un esempio di corpo della richiesta:

{
  "pagination": {
    "limit": 10,
    "offset": 0
  }
}

In risposta si otterrà una lista di sottoscrizioni:

{
    "list": [
      {
        "affiliatedSubscriptionId": 1,
        "affiliatedSubscriptionCode": "affCode",
        "redirectUrl": "string",
        ...
        "status": "WAITING_ACCEPTANCE",
        "customerMetadata": {
          ...
        }
      }
    ]
  }

Dettaglio di una sottoscrizione​

Se l'ID della sottoscrizione è noto in anticipo, sarà possibile invocare direttamente il servizio GET Affiliated Subscription:

GET /api/fabrick/platform/v4.0/affiliations/{affiliationCode}/affiliated-subscriptions/{affiliatedSubscriptionId}

A differenza dell'API di ricerca, in questo caso la risposta conterrà un solo elemento.

Annullamento di una sottoscrizione​

Il TTPP potrà ovviamente annullare una sottoscrizione in qualsiasi momento. Questa operazione deve essere effettuata tramite il servizio PUT cancelAffiliatedSubscription:

/api/fabrick/platform/v4.0/affiliations/{affiliationCode}/affiliated-subscriptions/{affiliatedSubscriptionId}/cancelled

In risposta si riceveranno i dettagli della sottoscrizione appena annullata.

Grant​

Una volta attivata una sottoscrizione e quindi abilitato un servizio per un Garante, il TTPP dovrà effettuare richieste alla piattaforma Fabrick per conto del Garante stesso; questo processo è denominato Personificazione. Il Personification Core consente di gestire i processi di Personificazione.

La Personificazione è quindi la gestione delle autorizzazioni e delle richieste di impersonificazione, ovvero la possibilità concessa a un soggetto tecnico (TTPP) di utilizzare i servizi della piattaforma per conto del Garante.

Nello specifico, un soggetto tecnico (TTPP) invia a un Garante una richiesta di Impersonificazione per un Prodotto specifico. Accettando tale richiesta (previa attivazione dell'onboarding e della sottoscrizione al prodotto da parte del Garante), il TTPP ottiene un token con cui può operare al posto del Consumer, entro il perimetro funzionale abilitato dal token.

A tale scopo, il garante deve aver abilitato i relativi grant. Prima di effettuare una richiesta di personificazione, i grant devono quindi essere gestiti tramite le seguenti API.

Questo passaggio è al momento opzionale poiché i grant vengono inclusi automaticamente durante la fase di sottoscrizione.

Ricerca grant​

Il TTPP dispone del servizio POST SearchPersonificationGrants per visualizzare e/o ricercare i grant emessi, ciascuno con i relativi dettagli.

POST /api/fabrick/platform/v4.0/personification/grants/search

{
  "pagination": {
    "limit": 0,
    "offset": 0
  },
  "sorting": [
    {
      "customFieldName": "string",
      "direction": "ASCENDING"
    }
  ],
  "grantedDatetime": {
    "from": "2022-07-15T10:51:30.631Z",
    "to": "2022-07-15T10:51:30.631Z"
  },
  "lastRevokedDatetime": {
    "from": "2022-07-15T10:51:30.631Z",
    "to": "2022-07-15T10:51:30.631Z"
  },
  "grantorCode": {
    "contains": "string",
    "equals": "string",
    "in": [
      "string"
    ],
    "equalsIgnoreCase": true,
    "isEmpty": true
  },
  "status": {
    "contains": "string",
    "equals": "string",
    "in": [
      "string"
    ],
    "equalsIgnoreCase": true,
    "isEmpty": true
  },
  "lastGrantedDatetime": {
    "from": "2022-07-15T10:51:30.631Z",
    "to": "2022-07-15T10:51:30.631Z"
  },
  "grantId": {
    "contains": "string",
    "equals": "string",
    "in": [
      "string"
    ],
    "equalsIgnoreCase": true,
    "isEmpty": true
  },
  "requestId": {
    "contains": "string",
    "equals": "string",
    "in": [
      "string"
    ],
    "equalsIgnoreCase": true,
    "isEmpty": true
  }
}

L'API restituisce una lista di elementi come mostrato nell'esempio:

{
    "list": [
      {
        "grantId": "string",
        "grantorCode": "string",
        "grantorSubscriptionId": "string",
        "lastGrantedDatetime": "2022-07-15T13:21:30.597Z",
        "lastRevokedDatetime": "2022-07-15T13:21:30.597Z",
        "requestId": "string",
        "status": "GRANTED"
      }
    ],
    "pagination": {
      "limit": 0,
      "offset": 0,
      "pageCount": 0,
      "resultCount": 0
    }
}

Dove:

  • grantId: identifica univocamente l'oggetto grant associato;
  • grantorCode: v. sezioni precedenti;
  • grantorSubscriptionId: ID che identifica univocamente la sottoscrizione al prodotto per cui è stata richiesta la personificazione;
  • lastGrantedDatetime: indica la data più recente in cui il grant ha assunto lo stato GRANTED. Il garante può infatti revocarlo in qualsiasi momento;
  • lastRevokedDatetime: indica la data più recente in cui il grant ha assunto lo stato REVOKED;
  • requestId: indica l'ID della richiesta; può essere ignorato in questo prodotto;
  • status: indica lo stato del grant. Gli stati del grant di personificazione sono:
    • Granted: se il TTPP dispone dei permessi;
    • Revoked: se il consumer revoca il grant (dalla dashboard/portale);
    • Waiting_renewal: nel caso in cui il garante voglia successivamente riabilitare il grant inizialmente nello stato Revoked, il TTPP può inviare una richiesta di rinnovo grant (vedi Rinnovo di un grant). A seguito di tale richiesta, in attesa dell'accettazione da parte dell'utente, lo stato sarà Waiting_renewal.

Dettaglio di un grant​

In alternativa, è possibile ottenere i dettagli di un grant specifico invocando semplicemente il servizio GET GetPersonificationGrantDetails:

GET /api/fabrick/platform/v4.0/personification/grants/{grantId}

A differenza dell'API POST SearchPersonificationGrants, la risposta sarà un singolo elemento.

Rinnovo di un grant​

È infine possibile rinnovare un grant tramite il servizio PUT RenewPersonificationGrant:

/api/fabrick/platform/v4.0/personification/grants/{grantId}/requested-renewal

Anche in questo caso la risposta conterrà l'elemento grant appena rinnovato.

Questa richiesta genera semplicemente una notifica sulla dashboard dell'utente, affinché al primo accesso possa decidere se confermare o meno.

Personificazione​

Creazione di un token di personificazione​

Una volta verificati i grant, sarà possibile effettuare una richiesta di personificazione. A tale scopo, il TTPP dovrà richiedere a Fabrick un token di autorizzazione per il garante desiderato tramite il servizio POST CreatePersonificationToken come mostrato di seguito:

POST /api/fabrick/platform/v4.0/auth/personification/tokens

{
  "grantorCode": "agenzia1"
}

Per questa richiesta è necessario aggiungere il seguente header:

X-Producers: fabrick

Il parametro grantorCode è il valore passato dal TTPP in fase di creazione dell'Affiliazione tramite l'API POST Create Affiliated Subscription. È quindi sufficiente passare solo il grantorCode come indicato. In alternativa, è possibile passare come parametro di input anche grantorProductSubscriptionId. Se entrambi venissero passati, dovranno ovviamente essere coerenti tra loro.

In risposta si otterrà:

{
"payload": {
    "personificationToken": "6c82....6cac5",
    "grantId": "1",
    "grantorId": "1",
    "grantorCode": "Customer1",
    "grantorProductSubscriptionId": "subId"
  }
 }

Una volta ottenuto il personificationToken, dovrà essere utilizzato per tutte le successive richieste ai servizi Fabrick. Il personificationToken ha una durata di 3 ore.

È ovviamente necessario disporre di almeno una sottoscrizione e di un grant attivo, altrimenti la richiesta restituirà il seguente errore:

{"code":"WOP016","description":"Failed to get provider's accounts"}

Il TTPP dispone ovviamente di ulteriori API che gli consentiranno di gestire tutte le richieste di Personificazione inviate con il relativo stato: il primo gruppo di API descritto di seguito riguarda le richieste completate con successo, mentre il gruppo successivo consente di gestire tutte le richieste in generale.

Linee guida​

In questa sezione riportiamo uno schema semplice che mostra tutte le richieste effettuate dall'Affiliatore:

affiliation_schema_drawio

Di seguito invece un paio di sequence diagram che mostrano l'utilizzo più comune dei servizi descritti fino a questo punto, con l'indicazione di un semplice esempio:

affiliation impersonification

Effettuare richieste ai servizi​

Come precedentemente anticipato, ogni richiesta del TTPP deve contenere il personificationToken. Questo parametro sarà inserito negli header della richiesta come mostrato nell'esempio seguente.

Per i dettagli sui servizi illustrati, si prega di fare riferimento alla relativa documentazione. L'unica differenza sarà sostituire i due header in tutte le richieste:

--header 'Auth-Schema: S2S'
--header 'Api-Key: fppApiKey'

con

--header 'Auth-Schema: S2S-AUTH'
--header 'Auth-Token: personificationToken'

poiché il TTPP non dovrà presentarsi con l'apiKey, ma con il token del Garante che andrà a sostituire.

Dati di test​

In questo paragrafo sono indicate le informazioni per poter eseguire un onboarding durante le fasi di test (vedi doc Affiliation - Psu Guide).

Il processo di onboarding si divide in 3 fasi principali:

  • Inserimento dati anagrafici

  • Inserimento dati KYC

  • Firma dei contratti, Delega e Configurazione IBAN

Inserimento dati anagrafici​

Lo step di inserimento dati anagrafici si divide, a sua volta, in anagrafica del Legale Rappresentante e anagrafica dell’Azienda. Come dati del Legale Rappresentante è possibile inserire ad esempio:

Verdi Pier Paolo - 01/01/1980 - Milano - M
CF: VRDPPL80A01F205C

Il controllo tra i dati anagrafici e il codice fiscale viene effettuato anche in ambiente di test; per questo motivo è necessario disporre di un codice fiscale reale e valido. È ad esempio possibile utilizzare un generatore di CF online. Si noti che il controllo sugli utenti esistenti si basa sul CF, se si desidera procedere con una nuova registrazione, sarà quindi necessario modificare il CF (ad es. +1 sul giorno di nascita). Lo stesso vale per l'indirizzo email, che dovrà essere nuovo per ogni onboarding, in quanto è utilizzato come username per l’accesso all’Onboarding. Infine, il numero di telefono deve essere reale perché, anche in ambiente di test, un messaggio viene inviato al numero indicato, per lo step di firma FEA sui contratti. Dopo aver inserito i dati del Legale Rappresentante, la procedura richiederà l’inserimento di due OTP (di Conferma di Autorizzazione). Sarà necessario inserire il seguente OTP per due volte:

1111

Una volta eseguito un primo onboarding completo, è possibile, per gli onboarding successivi, effettuare il login con le precedenti credenziali piuttosto che una nuva regostrazione da zero. E' possibile inoltre riutilizzare l’azienda già creata in precedenza oppure una nuova.

Inserimento dati KYC – Identificazione​

In questo processo, è necessario eseguire un’identificazione del Legale Rappresentante . È possibile identificarsi tramite le modalità SPID, SCA bancaria o documentale.

SPID

In ambiente di test, è possibile selezionare nel menu a tendina, il provider Fabrick AGID. Una volta selezionato, è possibile inserire username e password dalla seguente lista ufficiale https://demo.spid.gov.it/users e scegliendo tra gli utenti di Livello 2. Nome e cognome del Legale Rappresentante devono essere gli stessi associati all’utenza utilizzata in quanto la verifica avviene basandosi sull'uguaglianza del nome completo. Se non il provider Fabrick AGID non fosse possibile si prega di rihicedere la riabilitazione ramite ticket al Service Desk.

SCA

Assicurandosi che il nome del Legale Rappresentante sia Pier Paolo Verdi si potrà selezionare la Banca Mock e utilizzare le seguenti credenziali

Username: use03
Password: passwd03
OTP: 34567890

Documentale

Per quanto rigaurda questa modalità, nel solo ambiente di pre-produzione, è possibile anche caricare dei documenti dal desktop.

Per quanto riguarda la sezione sul titolare effettivo, è necessario registrarne almeno uno. In questo caso non è presente alcun controllo sul codice fiscale, che può quindi essere inserito casualmente. Se si vuole saltare la parte di inserimento Titolari Effettivi, si può scegliere “Ditta Individuale” come tipo di azienda.

Firma dei contratti, Delega e Configurazione IBAN​

Nel passaggio successivo si riceverà un OTP reale via SMS (da Infocert). Successivamente nuovamente un OTP per la Delega di Personificazione, ma stavolta sarà sempre 1111. Per quanto riguarda l'IBAN, sarà possibile utilizzare uno degli account sandbox indicati

In ambiente di pre-produzione, il servizio Infocert a volte può risultare indisponibile momentaneamente. Purtroppo in casi come questi suggeriamo di attendere e riprovare più tardi. Se il problema persiste si rega di contattare il nostro Service Desk.

Verifica censimento IBAN (caso Pay By Bank)​

Nel caso di prodotti Pass, se l'affiliato esce dal flusso prima di completare l'ultimo passaggio, ovvero prima di inserire il proprio conto di accredito, la sottoscrizione risulterà comunque attiva (stato ACCEPTED).

L'affiliato avrà quindi la possibilità di invocare tutte le API di pagamento, inclusa POST SearchCreditors, che restituirà però un vettore vuoto.

A questo punto sarà necessario reindirizzare l'affiliato al link di onboarding affinché possa completare anche l'ultimo passaggio ed inserire l'IBAN desiderato. Il link non deve ovviamente essere scaduto; in caso contrario sarà necessario contattare Fabrick tramite il Service Desk,