Tabella dei contenuti

Verifichiamo la correttezza dell'Identificativo organizzazione

L'e-service “Demo - Identificativo organizzazione” pubblicato sul catalogo offre un servizio mediante il quale è possibile verificare la presenza e la correttezza di un determinato id legato a un'organizzazione o un'azienda, simulando un ente che possiede le informazioni aggiornate e centralizzate di tutte le anagrafiche delle organizzazioni/aziende.

In questo tutorial viene mostrato un caso reale di applicazione di questo servizio.

Il caso d'uso

Problema: Come fruitore, ho la necessità di verificare che gli id delle Organizzazioni che ho sulla mia base dati sia corretto e ancora valida.

Soluzione: Effettuo la sottoscrizione all’e-service “Demo - Identificativo organizzazione” che consente di recuperare questi dati grazie all’invocazione della seguente API:

1POST /organization-id-verification/check
2

Data preparation

La prima cosa da fare è la configurazione dei dati. Procediamo dunque alla fase di Data Preparation.

Scambio certificati

L'e-service che desideriamo invocare prevede un ulteriore livello di sicurezza per il quale è prevista una fase di handshake.

Questa fase prevede lo scambio di un certificato tra fruitore ed erogatore ed è permessa dalla seguente API

1POST /organization-id-verification/data-preparation/handshake 
2

Input

1Authorization: Bearer {{bearerToken}} apikey: {{apikey}}
2

Payload:

1multipart/form-data
2form: 'certificate=@"/myLocation/cert.pem"'
3

Output

Response:

1{ 
2  "message": "string" 
3}
4

Status codes:

200 - Certificato salvato con successo
400 - Errore formato dati input

L'apikey previsto tra gli header rappresenta un identificativo per il chiamante.

La valorizzazione è a carico del chiamante.

Non sono previsti controlli di validazione se non quello sulla sua obbligatorietà.

Di seguito alcune informazioni sulla creazione del certificato.

Come generare il certificato

Il primo passo da fare è quello di generare un certificato client, utilizzando, per esempio, il tool OpenSSL. Lanciamo il comando per la generazione della chiave privata che nel nostro esempio è a 2048 bit:

1openssl genrsa -out private-key.pem 2048
2

a questo punto possiamo procedere alla creazione del certificato, contenente al suo interno la chiave pubblica (della durata di 365 giorni nell’esempio):

1openssl req -new -x509 -key private-key.pem -out cert.pem -days 365
2

Il certificato è pronto per essere condiviso con l’erogatore nella fase di handshake e successive chiamate.

Inserimento dati

Supponiamo di avere la seguente base dati all’interno della nostra applicazione:

ID	Nome	Data fine validità
Org-1	Organizzazione 1	NULL
Org-2	Organizzazione 2	2022-12-31

Effettuiamo quindi la data preparation simulando il seguente scenario:

L’id Org-1 è un'organizzazione ancora valido
L’id Org-2 è un'organizzazione obsoleta e che quindi deve essere rimossa dalla nostra base dati

Replichiamo la configurazione desiderata nel seguente modo:

1POST /organization-id-verification/data-preparation
2

Input

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

Payload:

1{ 
2  "idOrganization": "Org-1" 
3}
4

Output

Response:

Status codes:

200 - Configurazione salvata con successo

1{
2  "message": "string"
3}
4

400 - Errore formato dati input

1{
2  "detail": "Request took too long to complete.",
3  "instance": "string",
4  "status": 503,
5  "title": "string",
6  "type": "about:blank"
7}
8

Ottenimento dei dati

Con questa chiamata è possibile ottenere la lista delle organizzazioni presenti all'interno della base dati.

1GET /organization-id-verification/data-preparation
2

Input

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

Output

Response:

Status codes:

200 - Operazione eseguita con successo

1[
2  {
3    "organizationId": "Org-1"
4  }
5]
6

400 - Errore formato dati input

1{
2  "detail": "Request took too long to complete.",
3  "instance": "string",
4  "status": 503,
5  "title": "string",
6  "type": "about:blank"
7}
8

Eliminazione di tutti i dati

Con questo end-point è possibile eliminare una specifica organizzazione tramite il suo id dalla base dati.

1POST /organization-id-verification/data-preparation/remove
2

Input

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

Payload:

1{ 
2  "idOrganization": "Org-1" 
3}
4

Output

Response:

Status codes:

200 - Operazione eseguita con successo

1[
2  {
3    "message": "string"
4  }
5]
6

400 - Errore formato dati input

1{
2  "detail": "Request took too long to complete.",
3  "instance": "string",
4  "status": 503,
5  "title": "string",
6  "type": "about:blank"
7}
8

Procediamo a questo punto all’invocazione delle API messe a disposizione dell’e-service.

Invocazione E-Service

Completata la fase di configurazione non resta che procedere all’invocazione del servizio effettuando la verifica per i due soggetti presenti nella nostra base dati.

Ripetiamo dunque la seguente chiamata prima per l’id organizzazione di Org-1 e dopo per Org-2.

1POST /organization-id-verification/check 
2

Curl:

curl --location '{host}/organization-id-verification/check' --cert '/myLocation/cert.pem' --key '/myLocation/private-key.pem' --header 'x-correlation-id: myUniqueCorrelationId' --header 'Content-Encoding: identity' --header 'apikey: {{apikey}}' --header 'Content-Type: application/json' --header 'Authorization: Bearer {{bearerToken}}' --data '{ "organizationId": "Org-1" }' -k

Output:

Response:

1{
2  "organizationId": "Org-1",
3  "valid": true,
4  "status": "ATTIVA",
5  "denomination": "Organizzazione 1",
6  "dateStartActivity": "2001-01-02"
7}
8

Ciò che otterremo a seguito delle due invocazioni è il seguente risultato:

Org-1: l'organizzazione è stata trovata e abbiamo ottenuto una risposta positiva che ci indica la validità dell’id inviato
Org-2: l'organizzazione non è stata trovata. Il servizio ci ha risposto con successo indicandoci però che l’id inviato non è più valido

Esito Finale

Dopo aver interrogato l’e-service possiamo procedere all’aggiornamento della nostra base dati in base alle informazioni che abbiamo recuperato.

Di seguito una panoramica della situazione a seguito dell’aggiornamento

Id	Nome	Data fine validità
Org-1	Organizzazione 1	NULL
Org-2	Organizzazione 2	01/09/2024

La nostra base dati è stata correttamente aggiornata.

Diagramma di Flusso:

In questa pagina

Il caso d'uso

Data preparation

Invocazione E-Service

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

PDND Interoperabilità

Tabella dei contenuti

Verifichiamo la correttezza dell'Identificativo organizzazione

Il caso d'uso

Data preparation

Header:

Payload:

Response:

Status codes:

Come generare il certificato

Inserimento dati

Header:

Payload:

Response:

Status codes:

Ottenimento dei dati

Header:

Response:

Status codes:

Eliminazione di tutti i dati

Header:

Payload:

Response:

Status codes:

Invocazione E-Service

Response:

Esito Finale

Diagramma di Flusso:

Hai bisogno di aiuto?

Dicci cosa ne pensi

Italiano