API di scrittura

Creazione/Modifica di una sessione di riconoscimento

Prerequisiti

L'avviamento di una sessione di riconoscimento è sottoposto a dei prerequisiti di licenza che variano a seconda della tipologia di riconoscimento selezionata e dalla tipologia di entità che deve ricevere l'identità.

Identità per persone fisiche ad uso privato

Nel caso di identità SPID destinate a persone fisiche per uso privato, l'avvio di una sessione di riconoscimento è completamente gratuita. Non ci sono vincoli su item, licenze o servizi attivi, e non vengono registrati consumi sui servizi di metering. 

L'unico requisito richiesto per l'avvio della procedura è quindi un token utente TSDigital valido al quale sia associato almeno un item.

Identità per persone fisiche ad uso professionale o persone giuridiche

Nel caso di identità SPID per persone fisiche (ad uso professionale) o per persone giuridiche, è richiesto che l'utente che avvia la richiesta stia operando per un item che abbia acquistato il servizio SPID.

Ogni pacchetto del servizio include un certo numero di slot SPID, i quali vengono consumati con ogni richiesta avviata. Nel caso in cui una richiesta venga annullata prima che venga portato avanti il data entry aggiuntivo richiesto, lo slot viene liberato ed è liberamente riutilizzabile.

Riconoscimento Video

In aggiunta a quanto detto sopra, per effettuare un riconoscimento video è necessario che l'item effettui l'acquisto di un pacchetto aggiuntivo che gli fornisca degli slot SPID Video. Ogni riconoscimento video avviato consuma sia uno slot regolare che uno slot video. Come nel caso degli altri tipi di riconoscimento, se la richiesta viene annullata prima di essere portata avanti, lo slot viene liberato ed è liberamente riutilizzabile.

Permessi

L'utente deve avere il permesso SPID:itemId:* o superiore per poter avviare una richiesta. Alle utenze personali o tecniche non è permesso creare richieste di riconoscimento SPID che non siano legate ad un item.

API

L'avvio di una sessione di riconoscimento viene effettuato tramite la seguente API:

[POST] /api/v1/spid

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Body

Il body della richiesta è un JSON con il seguente formato (i parametri sottolineati sono obbligatori):

{
  "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Mario",
  "surname": "Rossi",
  "taxId": "RSSMRA80A01I829Y",
  "email": "mario.rossi@agyo.io",
  "phoneNumber": "0342424242",
  "channels": {
    "cie": true,
    "cns": true,
    "feq": true,
    "video": true,
    "rao": true
  },
  "spidType": "INDIVIDUAL",
  "spidLevel": "SPID_LEVEL_1",
  "raoId": "159bc2f6-2b55-4dcc-abcd-7929e56d3bb7",
  "sendNotification": false
}

Risposte

Successo

In caso di successo, l'API risponde con il codice HTTP 200 e con il seguente body:

{
  "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "spidId": "10aa555a-4ef4-41ca-b2ee-d07fac773898",
  "taxId": "RSSMRA80A01I829Y",
  "sessionLink": "http://example-link.agyo.io/spid-session"
}

Errore

In caso di errore, l'API risponde con un body JSON avente il seguente formato:

{
  "code": "string",
  "timestamp": "2022-04-13T13:35:16.678Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}

Gli errori possibili sono:

Modifica di una richiesta

Fintanto che la sessione di riconoscimento non è stata avviata, è possibile modificarne i parametri rieffettuando la chiamata di creazione. Nel caso di SPID che prevedono consumi, non verranno bloccati slot aggiuntivi. Il link di avvio sessione inviato al momento della creazione/ultima modifica viene invalidato e ne viene generato uno nuovo, con valenza di 24h dalla data della modifica.

Reinvio del link di sessione

Qualora si volesse far reinviare l'email contenente il link di avvio della sessione di riconoscimento, è possibile farlo tramite l'API

[POST] /api/v1/spid/{spidId}/sendSessionLink

Alternativamente, è possibile recuperare il link tramite le API di lettura e inviarlo/mostrarlo all'utente in altro modo.

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Path Parameter

Body

La richiesta non ha body.

Risposte

Successo

In caso di successo, l'API risponde con il codice HTTP 204 con nessun body.

Errore

In caso di errore, l'API risponde con un body JSON avente il seguente formato:

{
  "code": "string",
  "timestamp": "2022-04-13T13:35:16.678Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}

Gli errori possibili sono:

Rigenerazione di una sessione

Nel caso in cui il link per la sessione di riconoscimento sia scaduto, è possibile rigenerarlo tramite l'API

[POST] /api/v1/spid/{spidId}/refreshSession

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Path parameter

Body

L'API non ha body.

Risposte

Successo

In caso di successo, l'API risponde con il codice HTTP 200 e con il seguente body:

{
  "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "spidId": "10aa555a-4ef4-41ca-b2ee-d07fac773898",
  "taxId": "RSSMRA80A01I829Y",
  "sessionLink": "http://example-link.agyo.io/spid-session"
}

Errore

In caso di errore, l'API risponde con un body JSON avente il seguente formato:

{
  "code": "string",
  "timestamp": "2022-04-13T13:35:16.678Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}

Gli errori possibili sono:

Eliminazione di una sessione

Nel caso in cui una sessione di riconoscimento non sia avanzata oltre allo stato iniziale, è possibile eliminarla con l'API:

[DELETE] /api/v1/spid/{spidId}

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Path Parameter

Body

La richiesta non ha body.

Risposte

Successo

In caso di successo, l'API risponde con il codice HTTP 204 con nessun body.

Errore

In caso di errore, l'API risponde con un body JSON avente il seguente formato:

{
  "code": "string",
  "timestamp": "2022-04-13T13:35:16.678Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}

Gli errori possibili sono: