# SPID

Servizi per l'avvio e il monitoraggio delle procedure di censimento di una identità SPID

# Introduzione

Il servizio SPID permette di inizializzare sessioni di riconoscimento ai fini del rilascio di un'identità digitale per persone **fisiche** o **giuridiche**.

Il flusso interno a TSDigital si limita alla raccolta delle **informazioni di base** sull'entità da riconoscere (nome, cognome, ecc.), alla scelta della **tipologia di identità** (persona fisica/giuridica, uso privato/professionale) e alla scelta della **tipologia di riconoscimento**. Una volta avviato un flusso di riconoscimento, esso potrà essere concluso esternamente alla piattaforma Digital tramite le proprie modalità specifiche.

Dopo aver avviato una procedura di riconoscimento, è possibile monitorarne lo **stato d'avanzamento** tramite apposite API di lettura.

# Metodi di riconoscimento

È possibile avviare **5 metodi** differenti di riconoscimento per il rilascio di un'identità SPID:

- Carta d'Identità Elettronica (**cie**)
- Carta Nazionale dei Servizi (**cns**)
- Firma Elettronica Qualificata (**feq**)
- Video riconoscimento (**video**)
- Riconoscimento di persona (**rao**)

Le quali sono suddivise fra **riconoscimenti remoti** e **riconoscimenti di persona**.

### Riconoscimento remoto

Queste metodologie sono accomunate dal fatto che, per portarle a termine, l'utente deve recarsi su un portale web dedicato il cui link fornito dalla pagina di avviamento del flusso o tramite email.

#### CIE/CNS/FEQ

Questi tre metodi di riconoscimento richiedono che l'utente sia dotato di specifici supporti fisici (**cie**, **cns**) o virtuali (**feq**) per poter portare a termine la procedura.

#### VIDEO

Questa tipologia di riconoscimento richiede che l'utente effettui una videochiamata con un operatore/registrazione video per poter portare a termine la procedura. Per poter utilizzare la modalità di riconoscimento video, è necessario effettuare un **acquisto separato** rispetto a quello già effettuato per il servizio SPID. Tale acquisto viene effettuato dall'item prima dell'avvio della procedura.

### Riconoscimento di persona

<p class="callout warning">Il riconoscimento di persona è ancora in fase di sviluppo, e non tutte le sue parti sono attualmente disponibili</p>

Il riconoscimento di persona richiede che la persona fisica che deve effettuarlo si rechi fisicamente in uffici **RAO** (Registration Authority Officer) partner di TeamSystem. Gli uffici RAO disponibili sono ricercabili tramite un'apposita API, e possiedono un identificativo univoco anagrafico all'interno di TSDigital.

# 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:

<p class="callout info">[\[POST\] /api/v1/spid](https://spid-write-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-write-controller/initSpid)</p>

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Body

Il body della richiesta è un JSON con il seguente formato (i parametri <span style="text-decoration: underline;">sottolineati</span> sono obbligatori):

```JSON
{
  "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
}
```

- <span style="text-decoration: underline;">**itemId**</span>: l'identificativo anagrafico univoco dell'item che sta effettuando la richiesta ed è una stringa in formato UUIDV4
- <span style="text-decoration: underline;">**name**</span>: nome della persona per la quale sta venendo inizializzata la sessione
- <span style="text-decoration: underline;">**surname**</span>: cognome della persona per la quale sta venendo inizializzata la sessione
- <span style="text-decoration: underline;">**taxId**</span>: codice fiscale della persona per la quale sta venendo inizializzata la sessione
- <span style="text-decoration: underline;">**email**</span>: email di contatto della persona per la quale sta venendo inizializzata la sessione
- **phoneNumber**: numero di telefono della persona per la quale sta venendo inizializzata la sessione
- <span style="text-decoration: underline;">**channels**</span>: canali di riconoscimento da rendere disponibili per il riconoscimento
- <span style="text-decoration: underline;">**spidType**</span>: tipologia di SPID, ha i seguenti valori: 
    - **INDIVIDUAL**: SPID per persona fisica, uso privato
    - **PROFESSIONAL\_INDIVIDUAL**: SPID per persona fisica, uso professionale
    - **LEGAL\_ENTITY**: SPID per persona giuridica, uso privato
    - **PROFESSIONAL\_LEGAL\_ENTITY**: SPID per persona giuridica, uso professionale
- **<span style="text-decoration: underline;">spidLevel</span>**: [livello di sicurezza](https://helpdesk.spid.gov.it/knowledgebase.php?article=14) dell'identità SPID richiesta. Attualmente, sono disponibili i livelli 1 e 2
- **raoId**: identificativo anagrafico univoco di un RAO. <span style="text-decoration: underline;">Obbligatorio</span> nel caso in cui sia stato selezionato il canale rao, ignorato altrimenti
- **sendNotification**: se impostato a false, disabilita l'invio dell'email contenente il link di sessione. In questo caso, sta all'applicativo chiamante fornire correttamente all'utente il link per poter proseguire con l'identificazione. <span style="text-decoration: underline;">Il link inviato ha una valenza di 24h</span>.

### Risposte

#### Successo

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

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

- **itemId/taxId**: echo dei valori passati in ingresso
- **spidId**: identificativo univoco della richiesta all'interno di Digital, utilizzabile per effettuare operazioni di lettura/scrittura specifiche
- **sessionLink**: link utilizzabile per iniziare il processo di riconoscimento. Corrisponde al link inviato tramite email se sendNotification è true. <span style="text-decoration: underline;">Il link ha una valenza di 24h</span>. <span style="text-decoration: underline;">Non viene generato in caso di riconoscimento RAO</span>.

#### Errore

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

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **409**: il codice fiscale specificato è già associato ad un'altra richiesta in corso, oppure l'item non ha il servizio SPID attivo
- **500**: si è verificato un errore inaspettato
- **502**: si è verificato un errore inaspettato nella comunicazione con altri servizi

### 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

<p class="callout info">[\[POST\] /api/v1/spid/{spidId}/sendSessionLink](https://spid-write-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-write-controller/sendSessionLink)</p>

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](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Path Parameter

- <span style="text-decoration: underline;">**spidId**</span>: identificativo univoco della sessione di riconoscimento SPID, ottenuto al termine del [processo di creazione](https://digital-docs.ts-paas.com/books/spid/page/creazionemodifica-di-una-sessione-di-riconoscimento "Creazione/Modifica di una sessione di riconoscimento") o dalle API di lettura

### 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:

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **404**: non esiste una sessione con l'ID specificato
- **409**: la sessione specificata non ha un link di sessione (riconoscimento solo di persona)
- **500**: si è verificato un errore inaspettato
- **502**: si è verificato un errore inaspettato nella comunicazione con altri servizi

# Rigenerazione di una sessione

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

<p class="callout info">[\[POST\] /api/v1/spid/{spidId}/refreshSession](https://spid-write-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-write-controller/refreshSession)</p>

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Path parameter

- **spidId**: identificativo univoco della sessione di riconoscimento SPID, ottenuto al termine del [processo di creazione](https://digital-docs.ts-paas.com/books/spid/page/creazionemodifica-di-una-sessione-di-riconoscimento "Creazione/Modifica di una sessione di riconoscimento") o dalle API di lettura

### 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:

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

- **itemId/taxId**: echo dei valori presenti nella sessione SPID
- **spidId**: identificativo univoco della richiesta all'interno di Digital, utilizzabile per effettuare operazioni di lettura/scrittura specifiche
- **sessionLink**: nuovo link utilizzabile per iniziare il processo di riconoscimento. <span style="text-decoration: underline;">Il link ha una valenza di 24h</span>.

#### Errore

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

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **404**: non esiste una sessione associata all'ID specificato
- **500**: si è verificato un errore inaspettato
- **502**: si è verificato un errore inaspettato nella comunicazione con altri servizi

# Eliminazione di una sessione

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

<p class="callout info">[\[DELETE\] /api/v1/spid/{spidId}](https://spid-write-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-write-controller/deleteSession)</p>

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Path Parameter

- <span style="text-decoration: underline;">**spidId**</span>: identificativo univoco della sessione di riconoscimento SPID, ottenuto al termine del [processo di creazione](https://digital-docs.ts-paas.com/books/spid/page/creazionemodifica-di-una-sessione-di-riconoscimento "Creazione/Modifica di una sessione di riconoscimento") o dalle API di lettura

### 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:

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **404**: non esiste una sessione con l'ID specificato
- **409**: la sessione specificata non è in uno stato diverso da quello iniziale (INITIALIZED/SESSION\_EXPIRED)
- **500**: si è verificato un errore inaspettato
- **502**: si è verificato un errore inaspettato nella comunicazione con altri servizi

# API di lettura

# Ricerca di SPID

È possibile effettuare una ricerca di tutte le richieste collegate ad un dato item tramite l'API

<p class="callout info">[\[GET\] /api/v1/spid](https://spid-read-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-controller/getAll)</p>

I risultati dell'API sono **paginati**.

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Query Parameter

Campi <span style="text-decoration: underline;">sottolineati</span> sono obbligatori

- **<span style="text-decoration: underline;">itemId</span>**: identificativo anagrafico univoco dell'item associato alle richiesta SPID ricercate. Obbligatorio per le utenze personali o tecniche
- **userTaxId**: codice fiscale associato con le richieste SPID ricercate
- **fullName**: stringa che indica il nome e cognome della persona associata alle richieste SPID da ricercare. Può essere un valore parziale.
- **email**: email associata alle richieste SPID da ricercare. Può essere un valore parziale
- **channels**: elenco di canali di riconoscimento disponibili nelle richieste SPID da ricercare. Valori possibili: 
    - **CIE**
    - **CNS**
    - **FEQ**
    - **VIDEO**
    - **RAO**
- **identityTypes**: elenco di tipologie di identità disponibili nelle richieste SPID da ricercare. Valori possibili: 
    - **INDIVIDUAL**
    - **LEGAL\_ENTITY**
    - **PROFESSIONAL\_INDIVIDUAL**
    - **PROFESSIONAL\_LEGAL\_ENTITY**
- **requestedAt**: data di emissione della richiesta SPID, sotto forma di stringa. Se fornita, la porzione temporale della stringa non viene considerata
- **statsuses**: elenco di stati in cui può essere la richiesta SPID ricercata
- **fullNameOrTaxId**: campo che combina la ricerca fullName con la ricerca taxId. Ammette valori parziali
- **sortBy**: campo per il quale ordinare la richiesta. Valore di default: **requestedAt**.
- **sortDirection**: direzione di sorting. Valori possibili: **ASC**, **DESC**
- **size**: dimensione della pagina restituita. Default: **10**
- **page**: numero di pagina. Default: 0

### Body

La richiesta non ha body.

### Risposte

#### Successo

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

```JSON
{
  "totalPages": 0,
  "totalElements": 0,
  "size": 0,
  "content": [
    {
      "id": "string",
      "itemId": "string",
      "type": "INDIVIDUAL",
      "status": "PENDING",
      "requestedAt": "2022-04-14T09:53:28.029Z",
      "updatedAt": "2022-04-14T09:53:28.029Z",
      "user": {
        "id": "string",
        "name": "string",
        "surname": "string",
        "email": "string",
        "taxId": "string",
        "ncsId": "string"
      },
      "slotId": 0,
      "videoSlotId": 0,
      "sessionId": "string",
      "sessionLink": "string",
      "cie": true,
      "cns": true,
      "feq": true,
      "video": true,
      "rao": true,
      "sessionExpirationDate": "2022-04-14T09:53:28.029Z",
      "raoId": "string",
      "level": "SPID_LEVEL_1"
    }
  ],
  "number": 0,
  "sort": {
    "empty": true,
    "sorted": true,
    "unsorted": true
  },
  "pageable": {
    "page": 0,
    "size": 1,
    "sort": [
      "string"
    ]
  },
  "numberOfElements": 0,
  "first": true,
  "last": true,
  "empty": true
}
```

- **totalPages**: numero totale di pagine disponibili data la **size** e i filtri correnti
- **totalElements**: numero totale di richieste SPID disponibili con i filtri forniti
- **size**: dimensione della pagina ritornata. Coincide con il parametro **size** fornito in input
- **content**: richieste SPID presenti nella pagina corrente. Vedi [Lettura di un singolo SPID](https://digital-docs.ts-paas.com/books/spid/page/lettura-di-un-singolo-spid "Lettura di un singolo SPID") per dettagli.
- **number**: numero di pagina attuale. Corrisponde con il parametro **page** fornito in input
- **sort**: informazioni sul sorting attuale
- **pageable**: informazioni sulla paginazione attuale
- **numberOfElement**: elementi presenti nella pagina attuale
- **first/last/empty**: booleani che indicano se si tratta della prima/ultima pagina o se la pagina è vuota

#### Errore

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

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **500**: si è verificato un errore inaspettato

# Lettura di un singolo SPID

Dato l'identificativo univoco di una sessione di riconoscimento SPID, è possibile recuperarne i dati tramite l'API

<p class="callout info">[\[GET\] /api/v1/spid/{spidId}](https://spid-read-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-controller/getOne)</p>

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Path parameter

- **<span style="text-decoration: underline;">spidId</span>**: identificativo univoco della richiesta SPID

### Body

La richiesta non ha body.

### Risposte

#### Successo

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

```JSON
{
  "id": "string",
  "itemId": "string",
  "type": "INDIVIDUAL",
  "status": "PENDING",
  "requestedAt": "2022-04-14T10:58:13.409Z",
  "updatedAt": "2022-04-14T10:58:13.409Z",
  "user": {
    "id": "string",
    "name": "string",
    "surname": "string",
    "email": "string",
    "taxId": "string",
    "ncsId": "string"
  },
  "slotId": 0,
  "videoSlotId": 0,
  "sessionId": "string",
  "sessionLink": "string",
  "cie": true,
  "cns": true,
  "feq": true,
  "video": true,
  "rao": true,
  "sessionExpirationDate": "2022-04-14T10:58:13.409Z",
  "raoId": "string",
  "level": "SPID_LEVEL_1"
}
```

- **id**: identificativo univoco della richiesta SPID
- **itemId**: identificativo univoco dell'item associato alla richiesta
- **type**: tipologia della richiesta SPID
- **status**: stato attuale della richiesta SPID
- **requestedAt**: stringa che esprime data e ora della richiesta
- **updatedAt**: string che esprime data e ora dell'ultimo aggiornamento della richiesta
- **user**: dati sulla persona censita nella richiesta SPID 
    - **id**: identificativo univoco della persona
    - **name**: nome della persona
    - **surname**: cognome della persona
    - **email**: indirizzo email della persona
    - **taxId**: codice fiscale della persona
    - **ncsId**: identificativo univoco dell'utente lato NCS
- **slotId**: identificativo univoco dello slot occupato lato metering dalla richiesta. Nullo nel caso di richieste di tipo INDIVIDUAL
- **videoSlotId**: identificativo univoco dello slot occupato lato metering dalla richiesta. Valorizzato solo nel caso di canale di riconoscimento video
- **sessionId**: identificativo univoco della sessione di riconoscimento SPID. Nullo in caso di richieste il cui unico canale di riconoscimento è RAO.
- **sessionLink**: URL verso cui reindirizzare l'utente per iniziare la sessione di riconoscimento. Coincide con la URL inviata via mail quando viene inoltrata la richiesta. Nullo in caso di richieste il cui unico canale di riconoscimento è RAO.
- **cie/cns/feq/video/rao**: booleani che indicano se uno specifico canale di riconoscimento è stato selezionato
- **sessionExpirationDate**: data di scadenza del link di sessione. Nullo in caso di richieste il cui unico canale di riconoscimento è RAO.
- **raoId**: identificativo anagrafico univoco del RAO scelto per il riconoscimento. Valorizzato solo se il canale RAO è stato selezionato.
- **level**: livello della richiesta SPID. Attualmente sono disponibili i livelli 1 e 2

#### Errore

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

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **404**: richiesta SPID con l'ID fornito non trovata
- **500**: si è verificato un errore inaspettato

# Lettura storico stati di una richiesta

Ogniqualvolta una richiesta SPID cambia stato, il vecchio stato viene memorizzato nello storico. È possibile recuperare lo storico degli stati tramite l'API

<p class="callout info">[\[GET\] /api/v1/spid/{id}/history](https://spid-read-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-controller/getHistory)</p>

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Path Parameter

- <span style="text-decoration: underline;">**id**</span>: identificativo univoco della sessione di riconoscimento SPID, ottenuto al termine del [processo di creazione](https://digital-docs.ts-paas.com/books/spid/page/creazionemodifica-di-una-sessione-di-riconoscimento "Creazione/Modifica di una sessione di riconoscimento") o dalle API di lettura

### Body

La richiesta non ha body.

### Risposte

#### Successo

In caso di successo, l'API risponde con il codice **HTTP 200** con body

```JSON
{
  "totalPages": 0,
  "totalElements": 0,
  "size": 0,
  "content": [
    {
      "id": "string",
      "spidId": "string",
      "requestedAt": "2022-04-14T12:07:44.026Z",
      "status": "PENDING"
    }
  ],
  "number": 0,
  "sort": {
    "empty": true,
    "sorted": true,
    "unsorted": true
  },
  "pageable": {
    "page": 0,
    "size": 1,
    "sort": [
      "string"
    ]
  },
  "numberOfElements": 0,
  "first": true,
  "last": true,
  "empty": true
}

```

- **totalPages**: numero totale di pagine disponibili data la **size** e i filtri correnti
- **totalElements**: numero totale di richieste SPID disponibili con i filtri forniti
- **size**: dimensione della pagina ritornata. Coincide con il parametro **size** fornito in input
- **content**: storico degli stati SPID passati 
    - **id**: identificativo entry dello storico
    - **spidId**: identificativo univoco della richiesta SPID, coincide con il pathParameter **id**
    - **requestedAt**: data del cambio di stato
    - **status**: stato storicizzato
- **number**: numero di pagina attuale. Corrisponde con il parametro **page** fornito in input
- **sort**: informazioni sul sorting attuale
- **pageable**: informazioni sulla paginazione attuale
- **numberOfElement**: elementi presenti nella pagina attuale
- **first/last/empty**: booleani che indicano se si tratta della prima/ultima pagina o se la pagina è vuota

#### Errore

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

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato ad effettuare l'operazione
- **404**: non esiste una sessione con l'ID specificato
- **500**: si è verificato un errore inaspettato

# Lettura SPID di un RAO

Dato l'identificativo anagrafica di un RAO, un utente con permesso su di esso può recuperare tutte le sessioni SPID che gli son state attribuite tramite l'API:

<p class="callout info">[\[GET\] /api/v1/spid/rao/{raoId}](https://spid-read-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-controller/getAllByRao)</p>

Il ruolo minimo necessario per la lettura è `SPID:raoId:READ`

### Header

Gli header richiesti dalla chiamata sono gli [header standard di TSDigital](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital "Linee guida Generali API TS-Digital").

Il `Content-Type` deve essere `application/json`

### Path parameter

- **<span style="text-decoration: underline;">raoId</span>**: identificativo anagrafico univoco del RAO

### Body

La richiesta non ha body.

### Risposte

#### Successo

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

```JSON
{
  "totalPages": 0,
  "totalElements": 0,
  "size": 0,
  "content": [
    {
      "id": "string",
      "itemId": "string",
      "type": "INDIVIDUAL",
      "status": "PENDING",
      "requestedAt": "2022-04-14T15:01:15.176Z",
      "updatedAt": "2022-04-14T15:01:15.176Z",
      "user": {
        "id": "string",
        "name": "string",
        "surname": "string",
        "email": "string",
        "taxId": "string",
        "ncsId": "string"
      },
      "slotId": 0,
      "videoSlotId": 0,
      "sessionId": "string",
      "sessionLink": "string",
      "cie": true,
      "cns": true,
      "feq": true,
      "video": true,
      "rao": true,
      "sessionExpirationDate": "2022-04-14T15:01:15.176Z",
      "raoId": "string",
      "level": "SPID_LEVEL_1"
    }
  ],
  "number": 0,
  "sort": {
    "empty": true,
    "sorted": true,
    "unsorted": true
  },
  "pageable": {
    "page": 0,
    "size": 1,
    "sort": [
      "string"
    ]
  },
  "numberOfElements": 0,
  "first": true,
  "last": true,
  "empty": true
}
```

- **totalPages**: numero totale di pagine disponibili data la **size** e i filtri correnti
- **totalElements**: numero totale di richieste SPID disponibili con i filtri forniti
- **size**: dimensione della pagina ritornata. Coincide con il parametro **size** fornito in input
- **content**: richieste SPID presenti nella pagina corrente. Vedi [Lettura di un singolo SPID](https://digital-docs.ts-paas.com/books/spid/page/lettura-di-un-singolo-spid "Lettura di un singolo SPID") per dettagli.
- **number**: numero di pagina attuale. Corrisponde con il parametro **page** fornito in input
- **sort**: informazioni sul sorting attuale
- **pageable**: informazioni sulla paginazione attuale
- **numberOfElement**: elementi presenti nella pagina attuale
- **first/last/empty**: booleani che indicano se si tratta della prima/ultima pagina o se la pagina è vuota

#### Errore

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

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

- **code**: rappresentazione sotto forma di stringa del codice d'errore HTTP. Coincide con l'errore HTTP ritornato
- **tiemstamp**: data e ora della risposta, espresso sotto forma di stringa
- **message**: messaggio che esprime l'errore

Gli errori possibili sono:

- **400**: la richiesta è malformata (parametri con formato errato, parametri invalidi o inconsistenti fra loro)
- **401**: non è stato fornito un token autorizzativo o il token autorizzativo fornito non è valido (es: è scaduto)
- **403**: il token fornito è valido, ma l'utente non è autorizzato a leggere gli SPID associati al RAO
- **500**: si è verificato un errore inaspettato