20.3. PDND e-Service Template

La PDND fornisce uno strumento specializzato che migliora i processi di co-progettazione delle API ottimizzando la pubblicazione e il riutilizzo dei servizi elettronici. Questa funzionalità è definita e regolamentata nel presente documento.

  • "Linee Guida sull'infrastruttura tecnologica della Piattaforma Digitale Nazionale Dati per l'interoperabilità dei sistemi informativi e delle basi di dati" (PDND).

Il template del servizio elettronico serve come modello standardizzato contenente tutti i metadati tecnici e descrittivi necessari per un servizio elettronico. I Gestori delle API, che possono essere sia Fornitori che Consumatori all'interno dell'ecosistema PDND, POSSONO creare e mantenere questi template.

Una volta che un e-service template è pubblicato, è accessibile attraverso il Catalogo Template PDND che è un repository centralizzato che facilita il riutilizzo. Questo catalogo consente a qualsiasi Partecipante PDND autorizzato di sfogliare i template disponibili e istanziare nuovi servizi elettronici basati su progetti esistenti.

20.3.1. Definizione e linee guida dell'e-service template PDND

L'infrastruttura PDND supporta la gestione del ciclo di vita dei Servizi Elettronici Template, simile a quella dei servizi elettronici tradizionali. Gli stati del ciclo di vita includono: Draft, Active, Supsended e Deprecated. Come per i servizi elettronici tradizionali, PDND applica il controllo degli accessi basato sui ruoli per governare le transizioni di stato.

20.3.1.1. Gestione dei Servizi Elettronici Template

20.3.1.1.1. Creazione del Servizio Elettronico Template

I Partecipanti sono abilitati a creare Servizi Elettronici Template tramite una procedura guidata accessibile attraverso l'interfaccia web PDND (le API saranno disponibili in futuro). Il flusso di lavoro di creazione rispecchia da vicino quello della creazione standard di servizi elettronici, con le seguenti distinzioni:

  • Un campo aggiuntivo identifica il destinatario previsto del template.

  • Il campo "Audience" è omesso.

  • Le soglie sono opzionali e servono come raccomandazioni per i Partecipanti che implementano il template.

Ai Partecipanti è vietato creare più template con lo stesso nome: i nomi dei template DEVONO essere unici per partecipante. Alla creazione, un template è inizialmente impostato sullo stato Draft. I template possono quindi essere pubblicati nel Catalogo Template, rendendoli così accessibili a tutti i Partecipanti.

20.3.1.1.2. Modifica del Servizio Elettronico Template

I Partecipanti che hanno creato un template possono modificarlo. La portata dei campi modificabili dipende dallo stato del ciclo di vita del template:

  • Se il template è in stato Draft, tutti i campi sono modificabili.

  • Per i template in altri stati, solo un sottoinsieme limitato di campi può essere modificato direttamente.

  • I campi che non possono essere modificati nei template pubblicati richiedono la creazione di una nuova versione del template per applicare le modifiche.

Il versionamento dei template funziona in modo simile a quello dei servizi elettronici, dato che le modifiche al modello possono impattare i servizi istanziati e quindi i Partecipanti che consumano quell'istanza.

I seguenti campi possono essere modificati senza attivare una nuova versione del template:

  • Name

  • Intended Recipient

  • Description

  • Voucher Time Limit

  • Documentation (escludendo la specifica OpenAPI)

  • Attributes

20.3.1.1.3. Sospensione del e-service Template

I template, come i servizi elettronici, possono essere Sospesi. Quando sospesi:

  • Il template viene rimosso dal catalogo pubblico dei template.

  • L'istanziazione di nuove istanze dal template sospeso è disabilitata.

  • Le istanze precedentemente istanziate rimangono inalterate.

  • I template possono essere riattivati in qualsiasi momento.

  • I template non possono essere eliminati.

20.3.1.1.4. Istanziazione del e-service Template

I Partecipanti possono istanziare un Servizio Elettronico Template sfogliando il Catalogo Template e selezionando un template. Questo processo genera un nuovo servizio elettronico.

I vincoli di istanziazione includono:

  • Solo i template in stato Attivo sono idonei per l'istanziazione.

  • L'istanziazione è facilitata attraverso una procedura guidata nell'interfaccia web PDND.

  • A causa dell'obiettivo di standardizzazione dei template, la maggior parte dei campi è pre-compilata e immutabile durante l'istanziazione.

  • Le seguenti informazioni non possono essere modificate durante l'istanziazione:

    • Caricamento della documentazione

    • Tempo di scadenza del token

    • Nome, descrizione e attributi

Invece, i seguenti campi devono essere specificati durante l'istanziazione:

  • Audience

  • Thresholds

  • Automatic/Manual Approval Policy

Inoltre, sebbene la specifica OpenAPI sia fissa, i seguenti campi di metadati possono essere forniti in modo che PDND possa aggiornare automaticamente la specifica YAML:

  • Contatti (nome, email, URL, URL Termini e Condizioni)

  • URL del server

Ogni servizio elettronico istanziato mantiene un ciclo di vita indipendente analogo ai servizi elettronici standard.

20.3.1.2. Gestione delle Versioni

Il versioning dei template segue un processo controllato:

  • La pubblicazione di una nuova versione del template la imposta su Active.

  • La versione precedentemente Active viene automaticamente trasferita a Deprecated.

  • È consentita solo una versione Active per template in qualsiasi momento.

  • I template possono anche avere una singola versione Draft che coesiste con la versione Active.

Le istanze derivate dai template mantengono un versioning indipendente poiché i Partecipanti possono aggiornare i campi specifici dell'istanza (ad esempio, URL del server) più volte, mentre l'istanza rimane collegata alla versione del template di origine.

Di conseguenza, le versioni dei template e le versioni delle istanze sono indipendenti e non direttamente correlate.

I Partecipanti che istanziano un template possono quindi aggiornare sia l'istanza specifica o, se disponibile, aggiornare a una versione più recente del template.

20.3.1.3. Template per Fonte Autentica

La funzionalità del servizio elettronico template viene utilizzata per standardizzare la trasmissione dei dati dalle Fonti Autentiche ai Fornitori di Attestati Elettronici. Il servizio elettronico template DOVREBBE essere pubblicato all'interno della PDND dal Fornitore di Attestati Elettronici ed è accessibile attraverso il Catalogo Template PDND.

20.3.1.3.1. Parametri del Template per Fonte Autentica

Il servizio elettronico template DEVE rispettare le seguenti proprietà:

  • Name: IT Wallet - Fonte Autentica - <Nome dell'Attestato Elettronico>

  • Intended Recipients: IT Wallet - Fonte Autentica - <Dominio della Fonte Autentica>

  • Description: Descrizioni utili al Fornitore di Attestati Elettronici in relazione al nuovo attestato elettronico <Nome dell'Attestato Elettronico>

  • Technology: REST

  • Data variation via Signal Hub: True

  • Version changelog: Servizio elettronico Fonte Autentica tramite implementazione template

  • Voucher Time Limit: 20

  • Suggest custom threshold: False

  • Suggest manual agreement approval policy: False

  • Attributes: <Nome ufficiale dell'Ente Pubblico Fornitore di Attestati Elettronici>

20.3.1.3.2. Istanziazione del Template per Fonte Autentica

Ogni Fonte Autentica DOVREBBE istanziare il servizio elettronico template IT Wallet - Fonte Autentica nella PDND. Il processo di istanziazione risulterà in un nuovo servizio elettronico che DEVE soddisfare i seguenti requisiti:

  • Signal Hub: True

  • Politica di approvazione manuale: False

  • Soglia giornaliera chiamate API per ogni fornitore: maggiore di 10000

  • Soglia giornaliera chiamate API: maggiore di 10000

Informazioni aggiuntive richieste durante il processo di creazione sono dipendenti dal fornitore.

20.3.1.3.3. Specifica OpenAPI della Fonte Autentica PDND

Di seguito è riportata la specifica OpenAPI completa per i servizi elettronici della Fonte Autentica PDND:

  1openapi: 3.0.1
  2info:
  3  title: IT Wallet API - AS web services
  4  version: 0.2.0
  5  description: IT Wallet Authentic Source e-Service exposed via PDND.
  6  termsOfService: "https://authentic-source.example.it/tos/"
  7  contact:
  8    name: IT-Wallet <credential_name> <credential_provider>
  9    url: https://github.com/italia/eid-wallet-it-docs
 10  x-api-id: ASITW-01
 11  x-summary: IT-Wallet Authentic Source API.
 12servers:
 13  - url: https://test.authentic-source.example.it/v0.2.0
 14    description: Authentic Source API test server
 15  - url: https://authentic-source.example.it/v0.2.0
 16    description: Authentic Source API production server
 17security:
 18  - BearerAuth: []
 19  - DPoPAuth: []
 20paths:
 21  /status:
 22    get:
 23      tags:
 24        - status
 25      summary: Get Authentic Source API status.
 26      description: Health-check endpoint that returns the operational status of the Authentic Source API.
 27      operationId: authenticSourceStatus
 28      responses:
 29        "200":
 30          description: Service available
 31          content:
 32            application/problem+json:
 33              schema:
 34                $ref: "#/components/schemas/ProblemDetails"
 35          headers:
 36            Cache-Control:
 37              $ref: "#/components/headers/CacheControlHeader"
 38            RateLimit-Limit:
 39              $ref: "#/components/headers/RateLimitLimitHeader"
 40            RateLimit-Remaining:
 41              $ref: "#/components/headers/RateLimitRemainingHeader"
 42            RateLimit-Reset:
 43              $ref: "#/components/headers/RateLimitResetHeader"
 44        "429":
 45          description: Too Many Requests
 46          content:
 47            application/problem+json:
 48              schema:
 49                $ref: "#/components/schemas/ProblemDetails"
 50          headers:
 51            RateLimit-Limit:
 52              $ref: "#/components/headers/RateLimitLimitHeader"
 53            RateLimit-Remaining:
 54              $ref: "#/components/headers/RateLimitRemainingHeader"
 55            RateLimit-Reset:
 56              $ref: "#/components/headers/RateLimitResetHeader"
 57        "503":
 58          description: Service Unavailable
 59          content:
 60            application/problem+json:
 61              schema:
 62                $ref: "#/components/schemas/ProblemDetails"
 63          headers:
 64            Retry-After:
 65              $ref: "#/components/headers/RetryAfterHeader"
 66
 67  /attribute-claims/{datasetId}:
 68    post:
 69      tags:
 70        - credential
 71      summary: Get Attribute Claims
 72      description: >-
 73        This service provides the Credential Issuer with all attribute claims necessary for the issuance of a Digital Credential
 74      operationId: attributeClaims
 75      parameters:
 76        - in: path
 77          name: datasetId
 78          schema:
 79            type: string
 80          required: true
 81          description: Identifier of the dataset as registered in the Authentic Source Registry
 82        - name: DPoP
 83          in: header
 84          description: Use only if the DPoP voucher has been requested from PDND.
 85          schema:
 86            type: string
 87            format: JWT
 88          required: false
 89        - name: Agid-JWT-Signature
 90          in: header
 91          description: >-
 92            JWT containing the signature of the message headers whose integrity
 93            needs to be guaranteed, to comply with the INTEGRITY_REST_02
 94            security pattern (see <a target="blank"
 95            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
 96
 97            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
 98            ON JWT.IO</a>
 99          required: true
100          schema:
101            type: string
102            format: JWT
103            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
104        - name: Digest
105          in: header
106          description: >-
107            Digest of the message payload, to comply with the INTEGRITY_REST_02
108            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
109            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
110            digest output.
111          required: true
112          schema:
113            type: string
114            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
115        - name: Agid-JWT-TrackingEvidence
116          in: header
117          description: >-
118            If the Voucher type is Bearer, this header represents a JWT acting as a proof of possession, to comply with the REST_JWS_2021_POP security
119            pattern using the POP_TPoP implementation. Otherwise, it is a JWT containing the data tracked in the Consumer's domain, to comply with AUDIT_REST_02 (see <a target="blank"
120            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
121            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
122            ON JWT.IO</a>
123          required: false
124          schema:
125            type: string
126            format: JWT
127            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
128      requestBody:
129        required: true
130        content:
131          application/json:
132            schema:
133              $ref: "#/components/schemas/CredentialClaimsRequest"
134      responses:
135        "200":
136          description: OK
137          headers:
138            Agid-JWT-Signature:
139              description: JWT containing the signature of the message headers whose integrity needs to be guaranteed, to comply with the INTEGRITY_REST_02 security pattern (see <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <a target="blank" href="https://jwt.io/#debugger-io?token=ew0KICAiYWxnIjogIkVTMjU2IiwNCiAgImtpZCI6ICJhMWY1YzhkMi00YjM3LTRlOTEtYjBkMi03OWUzZjBjNGE4ZWYiLA0KICAidHlwIjogIkpXVCINCn0.ew0KICAiaXNzIjogIjEyMzRhYmNkLWVmNTYtZ2g3OC1pOWowLWtsbW5vcHFyc3R3eCIsDQogICJzdWIiOiAiMTIzNGFiY2QtZWY1Ni1naDc4LWk5ajAta2xtbm9wcXJzdHd4IiwNCiAgImF1ZCI6ICJodHRwczovL2ZydWl0b3JlLmV4YW1wbGUvZW50ZS1leGFtcGxlL3YxIiwNCiAgImlhdCI6IDE3MzMzOTc4NDAsDQogICJuYmYiOiAxNzMzNDAxNjI4LA0KICAiZXhwIjogMTczMzQwMTQ0MCwNCiAgImp0aSI6ICI4ZTEyZjRiNy05YzNhLTRmODMtOWI4ZC01MWEyYzdmNmU5ZDQiLA0KICAic2lnbmVkX2hlYWRlcnMiOiBbDQogICAgew0KICAgICAgImRpZ2VzdCI6ICJTSEEtMjU2PTc5YTIwYTc0NDMzNjQyMDMwMTgzMDYwMGFkOWJkY2E5OTM1OTNmODc2MjA5YTAwNGI1OTliNTgzMDk1YjBhNjEiDQogICAgfSwNCiAgICB7DQogICAgICAiY29udGVudC10eXBlIjogImFwcGxpY2F0aW9uL2pzb24iDQogICAgfQ0KICBdDQp9.DpuBNo2UgQhL7WLin4mpdZrbIpQq3tPvCX6HfktkxG7L5mk6a8OK1Hg0mQcZfFi3gelS-aL9kFS-6MoSy4csBg">EXAMPLE
140              required: true
141              schema:
142                type: string
143            Digest:
144              description: Digest of the message payload, to comply with the INTEGRITY_REST_02 security pattern. According to RFC 3230 Section 4.2 <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC 3230 §4.2</a>, the format MUST be the following digest-algorithm=encoded digest output.
145              required: true
146              schema:
147                type: string
148                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
149            Cache-Control:
150              $ref: "#/components/headers/CacheControlHeader"
151            RateLimit-Limit:
152              $ref: "#/components/headers/RateLimitLimitHeader"
153            RateLimit-Remaining:
154              $ref: "#/components/headers/RateLimitRemainingHeader"
155            RateLimit-Reset:
156              $ref: "#/components/headers/RateLimitResetHeader"
157          content:
158            application/json:
159              schema:
160                $ref: "#/components/schemas/CredentialClaimsResponse"
161              example:
162                interval: 864000
163                userClaims:
164                  given_name: "Mario"
165                  family_name: "Rossi"
166                  birth_date: "1980-01-10"
167                  birth_place: "Roma"
168                  tax_id_code: "TINIT-RSSMRA80A01H501Z"
169                  personal_administrative_number: "12345A123A"
170                attributeClaims:
171                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
172                    status: "VALID"
173                    last_updated: "2025-01-15T10:30:00Z"
174                    institute_name: "Nome Istituto Universitario"
175                    programme_type_name: "Laurea Magistrale"
176                    degree_course_name: "Computer Science - Informatica"
177                    academic_qualification_date: "2025-06-25"
178                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
179                    status: "VALID"
180                    last_updated: "2025-01-10T08:00:00Z"
181                    institute_name: "Nome Istituto Universitario"
182                    programme_type_name: "Laurea Triennale"
183                    degree_course_name: "Informatica"
184                    academic_qualification_date: "2022-11-27"
185                metadataClaims:
186                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
187                    issuance_date: "2025-06-25"
188                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
189                    issuance_date: "2022-11-27"
190        "400":
191          description: Bad Request
192          content:
193            application/problem+json:
194              schema:
195                $ref: "#/components/schemas/ProblemDetails"
196          headers:
197            RateLimit-Limit:
198              $ref: "#/components/headers/RateLimitLimitHeader"
199            RateLimit-Remaining:
200              $ref: "#/components/headers/RateLimitRemainingHeader"
201            RateLimit-Reset:
202              $ref: "#/components/headers/RateLimitResetHeader"
203        "401":
204          description: Unauthorized
205          content:
206            application/problem+json:
207              schema:
208                $ref: "#/components/schemas/ProblemDetails"
209          headers:
210            RateLimit-Limit:
211              $ref: "#/components/headers/RateLimitLimitHeader"
212            RateLimit-Remaining:
213              $ref: "#/components/headers/RateLimitRemainingHeader"
214            RateLimit-Reset:
215              $ref: "#/components/headers/RateLimitResetHeader"
216            WWW-Authenticate:
217              $ref: "#/components/headers/WWWAuthenticateHeader"
218        "404":
219          description: Claims not found
220          content:
221            application/problem+json:
222              schema:
223                $ref: "#/components/schemas/ProblemDetails"
224          headers:
225            RateLimit-Limit:
226              $ref: "#/components/headers/RateLimitLimitHeader"
227            RateLimit-Remaining:
228              $ref: "#/components/headers/RateLimitRemainingHeader"
229            RateLimit-Reset:
230              $ref: "#/components/headers/RateLimitResetHeader"
231        "429":
232          description: Too Many Requests
233          content:
234            application/problem+json:
235              schema:
236                $ref: "#/components/schemas/ProblemDetails"
237          headers:
238            RateLimit-Limit:
239              $ref: "#/components/headers/RateLimitLimitHeader"
240            RateLimit-Remaining:
241              $ref: "#/components/headers/RateLimitRemainingHeader"
242            RateLimit-Reset:
243              $ref: "#/components/headers/RateLimitResetHeader"
244        "500":
245          description: Internal Server Error.
246          content:
247            application/problem+json:
248              schema:
249                $ref: "#/components/schemas/ProblemDetails"
250          headers:
251            Retry-After:
252              $ref: "#/components/headers/RetryAfterHeader"
253        "503":
254          description: Service Unavailable
255          content:
256            application/problem+json:
257              schema:
258                $ref: "#/components/schemas/ProblemDetails"
259          headers:
260            Retry-After:
261              $ref: "#/components/headers/RetryAfterHeader"
262
263tags:
264  - name: status
265    description: Endpoint di health check dell'API.
266  - name: credential
267    description: Retrieve information about the credential.
268
269components:
270  securitySchemes:
271    BearerAuth:
272      type: http
273      scheme: bearer
274      bearerFormat: JWT
275      description: PDND Bearer Token
276    DPoPAuth:
277      type: apiKey
278      in: header
279      name: DPoP
280      description: DPoP proof JWT (RFC 9449).
281
282  headers:
283    CacheControlHeader:
284      schema:
285        type: string
286        enum:
287          - no-store
288      description: no-store
289    RateLimitLimitHeader:
290      schema:
291        type: integer
292        format: int32
293        minimum: 0
294      description: Maximum number of requests within the time window.
295    RateLimitRemainingHeader:
296      schema:
297        type: integer
298        format: int32
299        minimum: 0
300      description: Remaining requests within the time window.
301    RateLimitResetHeader:
302      schema:
303        type: integer
304        format: int32
305        minimum: 0
306      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
307    RetryAfterHeader:
308      schema:
309        type: integer
310        format: int32
311        minimum: 0
312      description: Seconds to wait before receiving another response.
313    WWWAuthenticateHeader:
314      schema:
315        type: string
316        example: >-
317          Bearer error="invalid_token", error_description="The access token expired"
318      description: The request cannot be fulfilled because the Voucher is expired, revoked or otherwise malformed. See <a target="blank" href="https://datatracker.ietf.org/doc/html/rfc6750.html#section-3">RFC6750</a> and <a target="blank" href="https://datatracker.ietf.org/doc/html/rfc9449.html#section-7.1-11">RFC9449</a> for details.
319
320  schemas:
321    CredentialClaimsResponse:
322      type: object
323      properties:
324        userClaims:
325          description: List of User Claims.
326          type: object
327          properties:
328            given_name:
329              description: Current First Name.
330              type: string
331              example: "Mario"
332            family_name:
333              description: Current Family Name.
334              type: string
335              example: "Rossi"
336            birth_date:
337              description: Date of Birth.
338              type: string
339              example: "1980-01-10"
340            birth_place:
341              description: Place of Birth.
342              type: string
343              example: "Roma"
344            tax_id_code:
345              description: National tax identification number. REQUIRED if personal_administrative_number is absent.
346              type: string
347              example: "TINIT-XXXXXXXXXXXXXXXX"
348            personal_administrative_number:
349              description: National unique identifier of a natural person. REQUIRED if tax_id_code is absent.
350              type: string
351              example: "XX00000XX"
352        attributeClaims:
353          description: List of Datasets of Attribute.
354          type: array
355          items:
356            type: object
357            properties:
358              object_id:
359                description: Unique identifier of the Dataset.
360                type: string
361                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
362              status:
363                description: Status of the Dataset.
364                type: string
365                enum: ["VALID", "INVALID", "SUSPENDED"]
366                example: "VALID"
367              last_updated:
368                description: Last time the status or attributes of the Dataset have been updated. Its format is `YYYY-MM-DDTHH:MM:SSZ`.
369                type: string
370                example: "2025-01-15T10:30:00Z"
371            additionalProperties:
372              type: string
373            required: [object_id, status, last_updated]
374        metadataClaims:
375          description: List of Metadata Claims.
376          type: array
377          items:
378            type: object
379            properties:
380              object_id:
381                description: Unique identifier of the Dataset.
382                type: string
383                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
384              issuance_date:
385                description: Administrative validity start date of the Dataset
386                type: string
387                example: "2025-01-01"
388              expiry_date:
389                description: Administrative expiry date of the Dataset.
390                type: string
391                example: "2025-12-31"
392            required: [object_id]
393        interval:
394          description: Required if claims parameter is not present. This represents the estimated amount of time (in seconds) required before making the request of the attribute claims again.
395          type: integer
396          format: int64
397          example: 864000
398    CredentialClaimsRequest:
399      required:
400        - unique_id
401      type: object
402      properties:
403        unique_id:
404          type: string
405          description: ID ANPR or Tax identification number
406        object_id:
407          type: string
408          description: Unique identifier of the Credential dataset or `jti` of the Agid-JWT-Signature Credential Issuer deferred flow's request. If this parameter is present only the indicated dataset is returned
409    ProblemDetails:
410      type: object
411      description: RFC7807-compliant problem details object for error responses.
412      properties:
413        type:
414          type: string
415          format: uri
416          description: An absolute URI that identifies the problem type.
417        title:
418          type: string
419          description: A short, human-readable summary of the problem type.
420        status:
421          type: integer
422          format: int32
423          description: The HTTP status code generated by the origin server for this occurrence of the problem.
424        detail:
425          type: string
426          description: A human-readable explanation specific to this occurrence of the problem.
427        instance:
428          type: string
429          format: uri
430          description: An absolute URI that identifies the specific occurrence of the problem.
431      required: [title, status, detail]