Tabella dei contenuti
Come integrare il proprio e-service con il Probing
Per integrare il proprio e-service con il Probing, va predisposto un endpoint di status, che verrà contattato da PDND ogni 5 minuti per verificarne la disponibilità.
Step 1: Integrare l'endpoint di status
Il sistema di Probing invoca un endpoint dell’e-service costruito a partire dal basePath registrato a catalogo:
| Tecnologia | Metodo HTTP | Path |
|---|---|---|
| REST | GET | {basePath}/status |
| SOAP | POST (envelope SOAP standard) | {basePath}/status |
L’endpoint deve essere esposto tramite protocollo HTTPS e deve essere coerente con la tecnologia dichiarata dall’erogatore (REST o SOAP).
Risposte attese
L’esito della verifica si basa esclusivamente sul codice di stato HTTP restituito dall’endpoint:
- 200: indica che l’e-service è operativo. Non è richiesto alcun contenuto nel corpo della risposta;
- 4xx/5xx: indicano un errore applicativo o una condizione di indisponibilità. L’e-service deve restituire una risposta conforme allo standard RFC 7807, utilizzando il formato Problem JSON per descrivere l’anomalia riscontrata;
- errori di rete o mancata risposta: se l’endpoint non è raggiungibile o non risponde nei tempi previsti, il servizio è considerato non disponibile.
Step 2: verificare le richieste che arrivano da PDND
Dopo aver completato l'integrazione, è necessario verificare e autorizzare le richieste che PDND farà verso l'endpoint di status ogni 5 minuti. Le richieste avranno un header Authorization e saranno basate su access token Bearer.
Il flusso è molto simile alla verifica di un voucher di tipo Bearer (maggiori informazioni nel tutorial dedicato). La differenza è che il token, che non è consumato da un fruitore ma direttamente da PDND, non conterrà i campi eserviceId, descriptorId, producerId, consumerId , purposeId e client_id.
Esempio di voucher Bearer utilizzato da PDND Interoperabilità deserializzato
Header:
1{
2 "typ": "at+jwt",
3 "alg": "RS256",
4 "use": "sig",
5 "kid": "{KID_CHIAVE_PDND}"
6}
7Payload:
1{
2 "iss": "interop.pagopa.it",
3 "nbf": 1747408537,
4 "iat": 1747408537,
5 "exp": 1747409537,
6 "jti": "12297ac1-c192-4573-8350-207a4213e5ac",
7 "aud": "https://eservice.pa.it/api/v1",
8 "sub": "[Confermare Lorenzo]"
9}
10Significato dei campi
Nell'header si troveranno quattro campi:
| Nome campo | Significato |
|---|---|
| kid | l'id della chiave che usato per firmare il voucher, reperibile sul well known di PDND Interoperabilità (vedi sotto Verifica sulla firma) |
| alg | l'algoritmo usato per firmare il JWT ( RS256) |
| use | valorizzato a sig, indica che la chiave è destinata alla firma digitale |
| typ | il tipo di oggetto che si sta inviando (at+jwt) |
Nel payload ci saranno invece tredici campi obbligatori, e uno opzionale:
| Nome campo | Significato |
|---|---|
| iss | l'issuer, rappresenta il dominio corrispondente all'authorization server di PDND Interoperabilità che ha rilasciato il voucher (ad esempio, l'issuer dell'ambiente di produzione è interop.pagopa.it) |
| nbf | not before, il timestamp dal quale è valido il voucher, espresso in UNIX epoch (valore numerico, non stringa). Per i voucher di PDND Interoperabilità, l'nbf corrisponde allo iat, ossia il voucher è spendibile immediatamente |
| iat | issued at, il timestamp nel quale è stato rilasciato il voucher, espresso in UNIX epoch (valore numerico, non stringa) |
| exp | l'expiration, il timestamp riportante data e ora di scadenza del token, espresso in UNIX epoch (valore numerico, non stringa). La durata del voucher (ossia la differenza tra nbf ed exp) dipende dal valore che l'erogatore ha impostato nella configurazione dell'e-service |
| jti | il JWT ID, un id unico random assegnato da PDND Interoperabilità |
| aud | l'audience, ossia l'indicazione di quale servizio dell'erogatore PDND intenda consumare con il voucher. Il valore riportato è quello che l'erogatore ha inserito nella configurazione dell'e-service |
| sub | il subject, in questo caso l'id del client che ha richiesto il voucher a PDND Interoperabilità |
Pagina successiva → Tutorial per il fruitore
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
