# 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](https://spid-write-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/spid-write-controller/initSpid)

### 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 sottolineati 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 } ``` - **itemId**: l'identificativo anagrafico univoco dell'item che sta effettuando la richiesta ed è una stringa in formato UUIDV4 - **name**: nome della persona per la quale sta venendo inizializzata la sessione - **surname**: cognome della persona per la quale sta venendo inizializzata la sessione - **taxId**: codice fiscale della persona per la quale sta venendo inizializzata la sessione - **email**: 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 - **channels**: canali di riconoscimento da rendere disponibili per il riconoscimento - **spidType**: 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 - **spidLevel**: [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. Obbligatorio 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. Il link inviato ha una valenza di 24h. ### 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. Il link ha una valenza di 24h. Non viene generato in caso di riconoscimento RAO. #### 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

[\[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)

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

[\[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)

### 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. Il link ha una valenza di 24h. #### 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:

[\[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)

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