DevPortalPagoPA

SoluzioniWebinar
Tabella dei contenuti

Richiediamo informazioni sull'indirizzo digitale

L'e-service “Attestazione - Verifica indirizzo digitale” pubblicato sul catalogo, consente di verificare la presenza e la correttezza di un determinato indirizzo digitale, simulando un ente che possiede tutte le informazioni anagrafiche legate agli indirizzi digitali dei soggetti.
In questo tutorial vedremo un caso reale di applicazione di questo servizio.

Il caso d'uso

L'e-service in oggetto mi permette di recuperare tali dati grazie all’invocazione del seguente set di API:
1POST /digital-address-verification/list
2GET /digital-address-verification/list/state/{id}
3GET /digital-address-verification/list/response/{id}
4
I metodi sopra esposti permettono di effettuare un’estrazione massiva degli indirizzi, a partire dagli id soggetto indicati all’interno della request.

Data preparation

La prima cosa da fare è la configurazione dei dati: procediamo alla fase di Data Preparation.
Supponiamo di avere la seguente base dati all’interno della nostra applicazione:
IDNomeCognomePEC
RSSMRA80A01H501UMarioRossiNULL
LGUBCH80A01H501BLuigiBianchiNULL
In accordo a questa effettuiamo la Data Preparation simulando il seguente scenario:
  • L’id RSSMRA80A01H501U è un soggetto noto a cui è associata una PEC ancora valida
  • L’id LGUBCH80A01H501B è un soggetto noto a cui è associata una PEC non più valida
Replichiamo la configurazione desiderata nel seguente modo:
1POST /digital-address-verification/data-preparation
2
Header:
1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4apikey: {{apikey}}
5

Payload:

1{
2    "idSubject": "RSSMRA80A01H501U",
3    "from": "2017-07-21T17:32:28Z",
4    "digitalAddress": [
5        {
6            "digitalAddress": "example_1@pec.it",
7            "profession": "Doctor",
8            "information": {
9                "reason": "CESSAZIONE_UFFICIO",
10                "endDate": "2999-12-31T17:32:28Z"
11            }
12        }
13    ]
14}
15
Response:
Status codes:
  • 201 - Configurazione salvata con successo
  • 400 - Errore formato dati input
Abbiamo configurato il primo soggetto, procediamo alla configurazione del secondo:

Header:

1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4apikey: {{apikey}}
5

Payload:

1{
2    "idSubject": "LGUBCH80A01H501B",
3    "from": "2017-07-21T17:32:28Z",
4    "digitalAddress": [
5        {
6            "digitalAddress": "example_2@pec.it",
7            "profession": "Doctor",
8            "information": {
9                "reason": "CESSAZIONE_VOLONTARIA",
10                "endDate": "2004-12-31T17:32:28Z"
11            }
12        }
13    ]
14}
15

Response:

Status codes:

  • 201 - Configurazione salvata con successo
  • 400 - Errore formato dati input
Abbiamo configurato anche il secondo soggetto, specificando che la data di fina validità della PEC è antecedente alla data odierna.
Di seguito gli altri end-point per la gestione dei record presenti nella base dati:

Ottenimento dei dati

Con questa chiamata è possibile ottenere la lista delle organizzazioni presenti all'interno della base dati.
1GET /digital-address-verification/data-preparation
2

Header:

1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4apikey: {{apikey}}
5

Response

  • Status code: 200
1{
2  "data": [
3    {
4      "idSubject": "VRANGL74M28R701X",
5      "from": "2017-07-21T17:32:28Z",
6      "digitalAddress": [
7        {
8          "digitalAddress": "example@pec.it",
9          "profession": "Doctor",
10          "information": {
11            "reason": "CESSAZIONE_VOLONTARIA",
12            "endDate": "2017-07-21T17:32:28Z"
13          }
14        }
15      ]
16    }
17  ]
18}
19
  • Status code: 400, 401, 403, 404, 500, 503
1{  
2  "status": "<HTTP_CODE>",
3  "type": "<HTTP_STATUS>",
4  "detail": "<detail_error>"
5}
6

Eliminazione dei dati

1DELETE /digital-address-verification/data-preparation
2

Header:

1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4apikey: {{apikey}}
5

Response

  • Status code: 202 - Richiesta completata con successo
  • Status code: 400, 401, 403, 404, 500, 503
1{  
2  "status": "<HTTP_CODE>",
3  "type": "<HTTP_STATUS>",
4  "detail": "<detail_error>"
5}
6

Ottenimento di un singolo record

1GET /digital-address-verification/data-preparation/:idSubject
2

Header:

1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4apikey: {{apikey}}
5

Response

  • Status code: 200
1{
2  "data": [
3    {
4      "idSubject": "VRANGL74M28R701X",
5      "from": "2017-07-21T17:32:28Z",
6      "digitalAddress": [
7        {
8          "digitalAddress": "example@pec.it",
9          "profession": "Doctor",
10          "information": {
11            "reason": "CESSAZIONE_VOLONTARIA",
12            "endDate": "2017-07-21T17:32:28Z"
13          }
14        }
15      ]
16    }
17  ]
18}
19
  • Status code: 400, 401, 403, 404, 500, 503
1{  
2  "status": "<HTTP_CODE>",
3  "type": "<HTTP_STATUS>",
4  "detail": "<detail_error>"
5}
6

Eliminazione di un singolo record

1DELETE /digital-address-verification/data-preparation/:idSubject
2

Header:

1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4apikey: {{apikey}}
5

Response

  • Status code: 200 - Richiesta completata con successo
  • Status code: 400, 401, 403, 404, 500, 503
1{  
2  "status": "<HTTP_CODE>",
3  "type": "<HTTP_STATUS>",
4  "detail": "<detail_error>"
5}
6
Procediamo a questo punto all’invocazione delle API messe a disposizione dell’e-service.

Invocazione e-service per estrazione massiva

Effettuo la seguente chiamata per l’id soggetto di Mario Rossi e Lugi Bianchi.
1POST /digital-address-verification/list
2
1curl --location '{host}/digital-address-verification/list' 
2--header 'Content-Type: application/json' 
3--header 'Accept: application/json' 
4--header 'x-correlation-id: 123456' 
5--header 'Authorization: Bearer xxx' 
6--data '{
7  "idSubjects": [
8    "RSSMRA80A01H501U",
9    "LGUBCH80A01H501B"
10  ],
11  "idRequest": "00001"
12}'
13

Response:

1{ 
2  "state": "PRESA_IN_CARICO", 
3  "message": "PRESA_IN_CARICO", 
4  "id": "20d0c1e1-b9c2-460b-8f8a-c8c6f264bb81", 
5  "requestTimestamp": "2024-10-15T14:36:24.028Z" 
6}
7

Status codes:

  • 200 - Richiesta effettuata con successo
La response ci indica che la nostra richiesta di estrazione massiva è stata presa in carico. Utilizzeremo l’id presente all’interno della response per invocare la successiva API.

Invocazione e-service per Verifica stato esportazione massiva

Effettuiamo la seguente chiamata, utilizzando l’id ricevuto nella chiamata precedente:
1POST /digital-address-verification/list/state/:id
2
1curl --location '{host}/digital-address-verification/list/state/20d0c1e1-b9c2-460b-8f8a-c8c6f264bb81' 
2--header 'Accept: application/json' 
3--header 'x-correlation-id: 1' 
4--header 'Authorization: Bearer xxx'
5

Response:

1application/json
2{
3    "status": "IN_ELABORAZIONE",
4    "message": "IN_ELABORAZIONE"
5}
6

Status codes:

  • 200 - Richiesta effettuata con successo
La response ci indica che la nostra richiesta di estrazione massiva è ancora in fase di elaborazione.
Effettuiamo nuovamente la chiamata, finché non riceviamo una response che indichi che l’estrazione è terminata con successo.
Per verificarlo, bisogna controllare il campo "status" della risposta. Può essere valorizzato con PRESO_IN_CARICO, IN_ELABORAZIONE e DISPONIBILE. Non appena diventa DISPONIBILE, procediamo con la successiva invocazione.
Effettuiamo la seguente chiamata, utilizzando l’id ricevuto nella richiesta di estrazione massiva
1POST /digital-address-verification/list/response/:id
2
1curl --location 'host}/digital-address-verification/list/response/20d0c1e1-b9c2-460b-8f8a-c8c6f264bb81' 
2--header 'Accept: application/json' 
3--header 'x-correlation-id: 1' 
4--header 'Authorization: Bearer xxx'
5

Response:

1{
2    "list": [
3        {
4            "idSubject": "RSSMRA80A01H501U",
5            "from": "2017-07-21T17:32:28Z",
6            "digitalAddress": [
7                {
8                    "digitalAddress": "example_1@pec.it",
9                    "profession": "Doctor",
10                    "information": {
11                        "reason": "CESSAZIONE_UFFICIO",
12                        "endDate": "2999-12-31T17:32:28Z"
13                    }
14                }
15            ]
16        },
17        {
18            "idSubject": "LGUBCH80A01H501B",
19            "from": "2017-07-21T17:32:28Z",
20            "digitalAddress": [
21                {
22                    "digitalAddress": "example_2@pec.it",
23                    "profession": "Doctor",
24                    "information": {
25                        "reason": "CESSAZIONE_VOLONTARIA",
26                        "endDate": "2004-12-31T17:32:28Z"
27                    }
28                }
29            ]
30        }
31    ]
32}
33

Status codes:

  • 200 - Richiesta effettuata con successo
La response ci restituisce i dati presenti nella base dati dell’ente.

Esito finale

Dopo aver interrogato l’e-service possiamo procedere all’aggiornamento della nostra base dati con le informazioni che abbiamo recuperato.
Di seguito una panoramica della situazione a seguito dell’aggiornamento
IDNomeCognomePec
RSSMRA80A01H501UMarioRossiexample_1@pec.it
LGUBCH80A01H501BLuigiBianchiNULL
La nostra base dati è stata correttamente aggiornata. Non abbiamo inserito l’indirizzo digitale per il soggetto Luigi Bianchi, essendo ormai obsoleto.

Diagramma di flusso

An image

In questa pagina

Il caso d'uso

Data preparation

Ottenimento dei dati

Eliminazione dei dati

Ottenimento di un singolo record

Eliminazione di un singolo record

Invocazione e-service per estrazione massiva

Invocazione e-service per Verifica stato esportazione massiva

Esito finale

Diagramma di flusso

Hai bisogno di aiuto?

Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata

Dicci cosa ne pensi

Per segnalare problemi o dare feedback, puoi aprire una segnalazione su Github