Definizione API PDND Connector

Endpoint del `pdnd-connector`

Il pdnd-connector espone endpoint specifici per ciascun e-service integrato, con diverse operazioni supportate tramite verbi HTTP.

Endpoint di Chiamata

Gli endpoint seguono una struttura che identifica l'erogatore e il servizio specifico. Ad esempio, per gli e-service ANPR (ANPR è l'erogatore), si utilizzano path come /e-services/anpr/<nome-e-service>. Esempi di <nome-e-service> includono accertamento-cittadinanza, stato-famiglia, accertamento-residenza.

Verbi HTTP Utilizzati

GET: Utilizzato per la fruizione degli e-service, ovvero per richiedere e ottenere i dati dal pdnd-connector, che a sua volta li recupera dagli enti erogatori (es. ANPR, INPS).
POST: Utilizzato per la validazione dei dati precedentemente ottenuti tramite GET. Questa operazione verifica che i dati non siano stati alterati prima di essere inviati dal Core.
Parametri Richiesti (Payload per POST, URL per GET):
- Per GET (Fruizione): I parametri sono inclusi nella URL (query parameters). Esempi includono:
  - fiscalCode: Il codice fiscale dell'utente di cui si richiedono i dati.
  - format: Un parametro che specifica il formato in cui i dati devono essere restituiti dal pdnd-connector. Questo formato deve essere compatibile con il Nested Form di OpenCity che riceverà i dati.
  - Esempio URL: GET /e-services/anpr/stato-famiglia?fiscalCode=ABCDEF01G23H456I&format=statoFamigliaArchetipo
- Per POST (Validazione): Il payload della richiesta POST deve contenere due campi principali:
  - data: L'oggetto JSON contenente i dati esatti (incluso il loro formato) così come ricevuti dalla risposta GET precedente, senza i metadati di isFromPdnd, isReadonly, isUpdatedToday.
  - meta: Un oggetto contenente la firma digitale (signature) dei dati, così come restituita dalla risposta GET.
Header Necessari: Per tutte le chiamate agli endpoint del pdnd-connector, è necessario includere un token JWT nell'header Authorization.
- Authorization: Bearer <JWT_TOKEN>. Il pdnd-connector effettua una validazione del token. Per le API di configurazione (non direttamente usate da OpenCity per fruizione), è richiesto un admin token. Per le API di fruizione e validazione, è richiesto un user token, e il codice fiscale contenuto nel token viene verificato con quello eventualmente presente nella URL.

Esempi di chiamate API

Di seguito, alcuni esempi di richieste e risposte per chiarire il flusso di integrazione.

Accertamento Residenza

Richiesta:

GET /anpr/accertamento-residenza
Headers:
  Authorization: Bearer <token_jwt>
Query Parameters:
  fiscal_code: RSSMRA80A01H501U
  config_id: a6fcd036-f1a2-4df5-b986-7410e9e0e97a
  format: residenza

Risposta:

{
  "data": {
    "address": "Via Roma",
    "house_number": "123",
    "municipality": "Roma",
    "county": "RM",
    "postal_code": "00100"
  },
  "meta": {
    "signature": "base64_encoded_signature",
    "format": "residenza",
    "created_at": "2024-03-26T10:00:00Z",
    "source": "ANPR",
    "call_url": "https://api.example.com/anpr/accertamento-residenza?config_id=a6fcd036-f1a2-4df5-b986-7410e9e0e97a&fiscal_code=RSSMRA80A01H501U&format=residenza"
  }
}

È disponibile anche il formato "residenza_archetipo" che include campi aggiuntivi:

{
  "data": {
    "address": "Via Roma",
    "house_number": "123",
    "municipality": "Roma",
    "county": "RM",
    "postal_code": "00100",
    "municipality_istat_code": "058091",
    "locator_within": "int1"
  },
  "meta": {
    // ... stessi campi meta ...
  }
}

Stato Famiglia

Richiesta:

GET /anpr/stato-famiglia
Headers:
  Authorization: Bearer <token_jwt>
Query Parameters:
  fiscal_code: RSSMRA80A01H501U
  config_id: c88d7efe-84a1-43c5-9edc-07f18a577289
  format: famiglia

Risposta (esempio con coniuge e figli):

{
  "data": {
    "birth_date": "1980-01-01",
    "birth_place": "Roma",
    "family_name": "Rossi",
    "given_name": "Maria",
    "gender": "femmina",
    "tax_id": "RSSMRA80A41H501U",
    "children": [
      {
        "birth_date": "2010-02-25",
        "birth_place": "Roma",
        "family_name": "Rossi",
        "given_name": "Marco",
        "gender": "maschio",
        "tax_id": "RSSMRC10B25H501U"
      },
      {
        "birth_date": "2012-03-15",
        "birth_place": "Roma",
        "family_name": "Rossi",
        "given_name": "Laura",
        "gender": "femmina",
        "tax_id": "RSSLRA12C55H501U"
      }
    ]
  },
  "meta": {
    "signature": "base64_encoded_signature",
    "format": "famiglia",
    "created_at": "2024-03-26T10:00:00Z",
    "source": "ANPR",
    "call_url": "https://api.example.com/anpr/stato-famiglia?config_id=c88d7efe-84a1-43c5-9edc-07f18a577289&fiscal_code=RSSMRA80A01H501U&format=famiglia"
  }
}

Validazione delle risposte

Per validare l'autenticità di una risposta, si utilizza il relativo l'endpoint di validazione:

Richiesta:

POST /validate/anpr/accertamento-residenza
Headers:
  Authorization: Bearer <token_jwt>
Query Parameters:
  fiscal_code: RSSMRA80A01H501U
  config_id: a6fcd036-f1a2-4df5-b986-7410e9e0e97a
  format: residenza
Body:
{
  "data": {
    // ... dati ricevuti ...
  },
  "meta": {
    // ... meta ricevuti con la firma ...
  }
}

Risposta:

{
  "result": true  // o false se la validazione fallisce
}

Definizione OpenAPI

PreviousIntegrazione tecnica tra OpenCity, PDND Connector e PDND NextIntegrazioni con il Sito Istituzionale

Last updated 1 day ago

Was this helpful?

Definizione API PDND Connector

Endpoint del `pdnd-connector`

Il pdnd-connector espone endpoint specifici per ciascun e-service integrato, con diverse operazioni supportate tramite verbi HTTP.

Endpoint di Chiamata

Verbi HTTP Utilizzati

GET: Utilizzato per la fruizione degli e-service, ovvero per richiedere e ottenere i dati dal pdnd-connector, che a sua volta li recupera dagli enti erogatori (es. ANPR, INPS).
POST: Utilizzato per la validazione dei dati precedentemente ottenuti tramite GET. Questa operazione verifica che i dati non siano stati alterati prima di essere inviati dal Core.
Parametri Richiesti (Payload per POST, URL per GET):
- Per GET (Fruizione): I parametri sono inclusi nella URL (query parameters). Esempi includono:
  - fiscalCode: Il codice fiscale dell'utente di cui si richiedono i dati.
  - format: Un parametro che specifica il formato in cui i dati devono essere restituiti dal pdnd-connector. Questo formato deve essere compatibile con il Nested Form di OpenCity che riceverà i dati.
  - Esempio URL: GET /e-services/anpr/stato-famiglia?fiscalCode=ABCDEF01G23H456I&format=statoFamigliaArchetipo
- Per POST (Validazione): Il payload della richiesta POST deve contenere due campi principali:
  - data: L'oggetto JSON contenente i dati esatti (incluso il loro formato) così come ricevuti dalla risposta GET precedente, senza i metadati di isFromPdnd, isReadonly, isUpdatedToday.
  - meta: Un oggetto contenente la firma digitale (signature) dei dati, così come restituita dalla risposta GET.
Header Necessari: Per tutte le chiamate agli endpoint del pdnd-connector, è necessario includere un token JWT nell'header Authorization.
- Authorization: Bearer <JWT_TOKEN>. Il pdnd-connector effettua una validazione del token. Per le API di configurazione (non direttamente usate da OpenCity per fruizione), è richiesto un admin token. Per le API di fruizione e validazione, è richiesto un user token, e il codice fiscale contenuto nel token viene verificato con quello eventualmente presente nella URL.

Esempi di chiamate API

Di seguito, alcuni esempi di richieste e risposte per chiarire il flusso di integrazione.

Accertamento Residenza

Richiesta:

GET /anpr/accertamento-residenza
Headers:
  Authorization: Bearer <token_jwt>
Query Parameters:
  fiscal_code: RSSMRA80A01H501U
  config_id: a6fcd036-f1a2-4df5-b986-7410e9e0e97a
  format: residenza

Risposta:

{
  "data": {
    "address": "Via Roma",
    "house_number": "123",
    "municipality": "Roma",
    "county": "RM",
    "postal_code": "00100"
  },
  "meta": {
    "signature": "base64_encoded_signature",
    "format": "residenza",
    "created_at": "2024-03-26T10:00:00Z",
    "source": "ANPR",
    "call_url": "https://api.example.com/anpr/accertamento-residenza?config_id=a6fcd036-f1a2-4df5-b986-7410e9e0e97a&fiscal_code=RSSMRA80A01H501U&format=residenza"
  }
}

È disponibile anche il formato "residenza_archetipo" che include campi aggiuntivi:

{
  "data": {
    "address": "Via Roma",
    "house_number": "123",
    "municipality": "Roma",
    "county": "RM",
    "postal_code": "00100",
    "municipality_istat_code": "058091",
    "locator_within": "int1"
  },
  "meta": {
    // ... stessi campi meta ...
  }
}

Stato Famiglia

Richiesta:

GET /anpr/stato-famiglia
Headers:
  Authorization: Bearer <token_jwt>
Query Parameters:
  fiscal_code: RSSMRA80A01H501U
  config_id: c88d7efe-84a1-43c5-9edc-07f18a577289
  format: famiglia

Risposta (esempio con coniuge e figli):

{
  "data": {
    "birth_date": "1980-01-01",
    "birth_place": "Roma",
    "family_name": "Rossi",
    "given_name": "Maria",
    "gender": "femmina",
    "tax_id": "RSSMRA80A41H501U",
    "children": [
      {
        "birth_date": "2010-02-25",
        "birth_place": "Roma",
        "family_name": "Rossi",
        "given_name": "Marco",
        "gender": "maschio",
        "tax_id": "RSSMRC10B25H501U"
      },
      {
        "birth_date": "2012-03-15",
        "birth_place": "Roma",
        "family_name": "Rossi",
        "given_name": "Laura",
        "gender": "femmina",
        "tax_id": "RSSLRA12C55H501U"
      }
    ]
  },
  "meta": {
    "signature": "base64_encoded_signature",
    "format": "famiglia",
    "created_at": "2024-03-26T10:00:00Z",
    "source": "ANPR",
    "call_url": "https://api.example.com/anpr/stato-famiglia?config_id=c88d7efe-84a1-43c5-9edc-07f18a577289&fiscal_code=RSSMRA80A01H501U&format=famiglia"
  }
}

Validazione delle risposte

Per validare l'autenticità di una risposta, si utilizza il relativo l'endpoint di validazione:

Richiesta:

POST /validate/anpr/accertamento-residenza
Headers:
  Authorization: Bearer <token_jwt>
Query Parameters:
  fiscal_code: RSSMRA80A01H501U
  config_id: a6fcd036-f1a2-4df5-b986-7410e9e0e97a
  format: residenza
Body:
{
  "data": {
    // ... dati ricevuti ...
  },
  "meta": {
    // ... meta ricevuti con la firma ...
  }
}

Risposta:

{
  "result": true  // o false se la validazione fallisce
}

Definizione OpenAPI

PreviousIntegrazione tecnica tra OpenCity, PDND Connector e PDND NextIntegrazioni con il Sito Istituzionale

Last updated 1 day ago

Was this helpful?

Endpoint del pdnd-connector

Endpoint di Chiamata

Verbi HTTP Utilizzati

Esempi di chiamate API

Accertamento Residenza

Stato Famiglia

Validazione delle risposte

Definizione OpenAPI

Endpoint del pdnd-connector

Endpoint di Chiamata

Verbi HTTP Utilizzati

Esempi di chiamate API

Accertamento Residenza

Stato Famiglia

Validazione delle risposte

Definizione OpenAPI

Accertamento Cittadinanza

Accertamento Residenza

Stato Famiglia

Get e-services

Options e-services

Status health-check

Options Tenant

Get Tenant Configuration

delete Tenants Configuration

Options Tenant by id

Get Clients list

Options Clients

Get client pdnd Configuration

Delete client pdnd Configuration

Options Clients

Get Config list of specific tenant

Options Config

Get Config

Disable Config

Options Config

Get Key

Delete Key

Accertamento Cittadinanza

Accertamento Residenza

Stato famiglia

Save Tenant Configuration

Update tenant Configuration

Update tenant Configuration

store client pdnd Configuration

Update client pdnd Configuration

Update client pdnd Configuration

Save Service Configuration

Update Config

Patch Config

Endpoint del `pdnd-connector`

Endpoint del `pdnd-connector`