> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API di verifica con wallet di identità digitale

> Verifica l'identità tramite wallet di identità digitale dalla tua applicazione Didit, senza creare un workflow di verifica.

Usa un endpoint dedicato ai wallet per verificare una persona dalla tua applicazione.
Non devi creare o pubblicare un workflow, né fornire un `workflow_id`.
Il tuo backend avvia la verifica e ne recupera il risultato; la tua interfaccia guida la persona attraverso l'autenticazione richiesta dal wallet.

> [!NOTE]
>
> Un'integrazione API richiede comunque che la persona si autentichi e approvi la condivisione della propria identità.
> Non è possibile verificare una persona inviando il suo identificativo personale senza questa interazione.

## Come funziona la verifica

1. Il tuo backend consulta il [catalogo dei wallet](https://docs.didit.me/it/standalone-apis/digital-id-wallet-catalog.md), quindi chiama l'endpoint di avvio di un wallet disponibile usando la chiave API della tua applicazione.
2. Didit restituisce un riferimento di verifica e l'azione che la persona deve compiere.
3. La tua applicazione apre la pagina di autenticazione o mostra le istruzioni di approvazione del wallet.
4. La persona si autentica con il proprio wallet.
5. Il tuo backend recupera il risultato verificato e gestisce le notifiche di completamento.

L'autenticazione tramite wallet è asincrona.
Una richiesta di avvio riuscita significa che l'autenticazione è iniziata; non significa che l'identità sia stata verificata.
Controlla sempre il risultato finale prima di considerare la persona verificata.

## Integrazione backend

Usa [Elenco dei wallet di identità digitale](https://docs.didit.me/it/standalone-apis/digital-id-wallet-catalog.md) per ottenere gli endpoint attuali, i campi obbligatori e la disponibilità per la tua applicazione.

Conserva la tua `x-api-key` sul backend.
Non inserirla in un bundle del browser o in un'applicazione mobile.
Usa un `Idempotency-Key` distinto per ogni nuovo tentativo di verifica e riutilizza quella chiave quando ripeti la stessa richiesta di avvio.
Modificare la richiesta riutilizzando la stessa chiave è un conflitto, non un nuovo tentativo di verifica.

Ogni wallet ha un proprio URL di avvio, ad esempio `/v3/id-verification/wallets/ftn/` per Finnish Trust Network.
Il `request_id` identifica la verifica autonoma per le operazioni successive.
Usa `vendor_data` come riferimento interno, fino a 2.000 byte UTF-8, e `metadata` per un oggetto JSON facoltativo.
Entrambi vengono restituiti con il risultato e con il webhook di completamento.

| Operazione | Endpoint |
| - | - |
| Leggi stato e risultato | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Esegui il polling di un'approvazione dal telefono | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Invia la risposta di un wallet Digital Credentials | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Annulla una verifica in attesa | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

Queste operazioni usano la chiave API dell'applicazione che ha avviato la verifica.
La disponibilità del polling e dell'autenticazione dipende dal wallet selezionato.

Un annullamento rifiuta una verifica in attesa senza addebitarla e restituisce invariata una verifica completata.
Per Smart-ID e Mobile-ID, un annullamento che arriva mentre un polling sta controllando l'approvazione attende alcuni secondi che il polling termini.
Quindi rifiuta la verifica oppure la restituisce come `verified` se la persona aveva già approvato.
Una verifica che la persona sta completando in quel momento non può essere annullata: la risposta è `409` con `error: "verification_in_progress"` e un header `Retry-After`.
Riprova dopo quel numero di secondi per leggere il risultato completato.

## Registra la tua destinazione di ritorno

I wallet con reindirizzamento riportano la persona alla tua applicazione dopo l'autenticazione.
Registra l'hostname esatto prima di avviare una verifica:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

Poi invia nella richiesta di avvio un `return_url` HTTPS, ad esempio `https://app.example.com/identity/complete`.
Usa hostname semplici in `allowed_return_hosts`, senza schema, percorso o wildcard.
Registra separatamente ogni sottodominio che usi, fino a 20 hostname.
L'aggiornamento di `allowed_return_hosts` sostituisce l'elenco registrato, quindi includi ogni hostname che vuoi conservare.
`GET /v3/webhook/` restituisce l'elenco attuale; vedi [Configurazione webhook](https://docs.didit.me/it/sessions-api/management-api.md#configurazione-webhook).
Per registrare una destinazione di ritorno non serve un workflow né un dominio White label.
La destinazione è una pagina di ritorno del browser; configura i webhook di completamento separatamente per il tuo backend.

## Esempio: Finnish Trust Network

Dopo aver registrato l'hostname di ritorno, avvia una verifica Finnish Trust Network:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

Salva il `request_id` restituito e invia il browser della persona a `wallet_verification.next_action.url` quando il suo `type` è `redirect`.
Dopo che la persona torna, recupera il risultato dal tuo backend:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Controlla `wallet_verification.outcome`:

| Esito | Significato |
| - | - |
| `pending` | Autenticazione ancora in corso. |
| `verified` | Autenticazione completata e identità restituita verificata. |
| `cancelled` | La persona o la tua applicazione ha annullato il tentativo. |
| `timeout` | La finestra di autenticazione è scaduta. |
| `failed` | Autenticazione o convalida dell'identità non riuscita. |

Usa l'identità solo quando l'esito è `verified` e `simulated` è `false` per un controllo d'identità reale.
Una risposta in attesa può contenere un'azione successiva; le risposte finali non hanno un'azione successiva.

## Autenticazione

**I wallet con reindirizzamento** restituiscono un URL di autenticazione.
Apri quell'URL nel browser della persona, lascia che completi il processo di autenticazione del wallet e riportala alla destinazione registrata.
Leggi il risultato dal tuo backend invece di considerare un parametro dell'URL di ritorno come prova di identità.

**Smart-ID e Mobile-ID** usano una richiesta di approvazione sul telefono della persona.
La tua interfaccia raccoglie l'identificativo personale richiesto; Mobile-ID richiede anche il numero di telefono associato.
Mostra il codice di confronto e chiedi alla persona di approvare solo se corrisponde al codice presente sul suo telefono.
Il PIN va inserito nel prompt del wallet o del telefono, mai nel tuo modulo o in una richiesta API.
Interroga il tuo backend con l'intervallo indicato in `poll_interval_seconds` per ricevere un riscontro sulla richiesta.
Didit controlla anche in background le approvazioni telefoniche in attesa, quindi il completamento può arrivare al tuo webhook dopo che la persona ha chiuso la tua pagina.

**Google Wallet** viene richiesto dalla tua pagina o dalla tua app tramite la Digital Credentials API, senza reindirizzamento; vedi [Wallet con credenziali digitali (Google Wallet)](#wallet-con-credenziali-digitali-google-wallet).

L'interazione disponibile dipende dal wallet selezionato.
Non dare per scontato che ogni wallet supporti un modulo incorporato, un codice QR o l'autenticazione senza browser.

## Wallet con credenziali digitali (Google Wallet)

Google Wallet viene richiesto direttamente dalla tua pagina web o dalla tua app Android, usando la W3C Digital Credentials API.
Non c'è alcun reindirizzamento, nessuna pagina ospitata da Didit e nessun codice QR di Didit.
È disponibile in produzione e in sandbox.
Le applicazioni sandbox non richiedono alcuna registrazione; ogni applicazione di produzione si registra una sola volta dalla console (passaggio di verifica dell'ID, riga Google Wallet, **Registra con Google**) prima di poter usare Google Wallet.
Consulta [L'elenco dei wallet di identità digitale](https://docs.didit.me/it/standalone-apis/digital-id-wallet-catalog.md) per vedere cosa può avviare subito la tua applicazione.

**1. Inizia dall'origine**

Il tuo backend chiama `POST /v3/id-verification/wallets/google-wallet/` con il `country` della persona (`USA`, `GBR`, `BRA`, `SGP` o `TWN`) e l'`origin` da cui verrà effettuata la richiesta al wallet.
La `origin` è l'origine HTTPS della tua pagina, come `https://app.example.com`, il cui host deve essere uno dei tuoi [nomi host di ritorno registrati](#registra-la-tua-destinazione-di-ritorno) o il tuo dominio white label.
Per un'app Android è `android:apk-key-hash:` seguito dal SHA-256 in base64 del certificato di firma della tua app, senza padding.
Il wallet rifiuta una richiesta effettuata da qualsiasi altra origine.
Non esiste alcun `return_url`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. Richiedi il wallet all'interno di un gesto dell'utente**

La risposta contiene `wallet_verification.interaction = "digital_credentials"` e `next_action.type = "request_digital_credential"`.
Passa `next_action.digital_credentials.request` al browser o all'Android Credential Manager, da un tocco o un clic sulla `origin` con cui hai avviato la richiesta.
Su desktop il browser mostra il proprio codice QR quando il wallet si trova su un altro dispositivo.

**3. Invia ciò che il wallet ha restituito**

Invia `{protocol, data}` restituiti al tuo backend e da lì a `POST /v3/id-verification/wallets/verifications/{request_id}/response/` come `{"response": {...}}`.
La richiesta può essere inviata una sola volta; un secondo invio restituisce la verifica già decisa.

**4. Leggi l'esito**

La risposta all'invio è la verifica decisa.
Puoi anche leggerla con `GET /v3/id-verification/wallets/verifications/{request_id}/` oppure riceverla nel webhook di completamento.

Nel browser, richiedi il wallet da un gestore del clic:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

Offri il metodo solo dove il browser lo supporta, per esempio quando `"DigitalCredential" in window` è true.
`navigator.credentials.get` deve essere eseguito in un gesto dell'utente, quindi chiamalo dal gestore del clic e non dopo un passaggio asincrono.

Su Android, usa Jetpack Credential Manager (`androidx.credentials` 1.5.0 o successiva) con la stessa richiesta:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Errori da gestire:

| Errore | Dove | Significato |
| - | - | - |
| `origin_invalid` | Avvio, `400` | `origin` non è un'origine HTTPS né un'origine di app Android. |
| `origin_not_allowed` | Avvio, `400` | L'host dell'origine non è registrato per la tua applicazione. Registralo in `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Invio, `409` | Questa verifica non accetta una risposta del wallet. |

Una credenziale che non supera la verifica è una verifica decisa con esito `failed`, non una risposta di errore.
Dal wallet escono solo i campi richiesti dalla verifica, e il risultato contiene gli attributi di identità restituiti dal wallet.
Un pass ID di Google Wallet o una patente di guida mobile di uno stato USA non restituisce una fotografia.

In un'applicazione sandbox il flusso viene simulato con gli stessi passaggi e restituisce `simulated: true`.
Qualsiasi risposta inviata decide la verifica in base a `sandbox_scenario`, così puoi costruire l'intero percorso nel browser o nell'app senza una credenziale reale.

## Webhook di completamento

Configura una destinazione webhook dell'applicazione per `status.updated` seguendo la [guida all'integrazione dei webhook](https://docs.didit.me/it/integration/webhooks.md).
Usa `webhook_version: "v3"` per la struttura della decisione descritta qui.
Verifica la firma del webhook nel tuo backend prima di elaborarlo.
Il `session_id` del webhook corrisponde al `request_id` restituito dall'API del wallet.
Un'identità completata tramite wallet compare nell'array `decision.id_verifications` del webhook con `verification_method: "wallet"`.
Puoi anche usare l'identificativo per recuperare il risultato dedicato dell'API del wallet.

Gestisci le notifiche di approvazione e rifiuto, incluse le verifiche annullate e scadute.
Rendi idempotente il gestore del webhook, perché le consegne non riuscite vengono sottoposte a un nuovo tentativo.
Il ritorno dal browser non è un webhook di completamento e i suoi parametri di query non sono una prova di identità.

## Identità restituita

Usa i campi di identità normalizzati per nomi e date di nascita quando vengono restituiti.
Gli attributi specifici del wallet descrivono le informazioni di identità condivise dal wallet selezionato.
Gli attributi disponibili variano in base al wallet e al paese.
Un'identità autenticata non implica che siano disponibili un ritratto, un indirizzo o ogni altro attributo richiesto.

## Test nella sandbox

Un'applicazione in modalità sandbox di Didit simula la verifica del wallet senza contattare un fornitore di wallet e senza addebitare crediti.
La risposta identifica queste richieste con `wallet_verification.simulated: true`.
Un'approvazione simulata si basa su dati di esempio, non su un'identità reale verificata.

Per un wallet con reindirizzamento, segui l'URL restituito per testare il callback e tornare alla tua applicazione.
Per Smart-ID o Mobile-ID, usa l'endpoint di polling per completare l'approvazione simulata; nessuna notifica viene inviata a un telefono.
Per testare la gestione degli errori, imposta `sandbox_scenario` su `wallet_cancelled`, `wallet_timeout` o `wallet_provider_error` quando avvii una richiesta.
Le applicazioni in ambiente di produzione rifiutano `sandbox_scenario`.

La simulazione nella sandbox di Didit è separata dai test eseguiti nell'ambiente di test del fornitore.
Una simulazione riuscita non stabilisce l'accesso live presso il fornitore né la disponibilità in produzione.

### Sandbox del provider ConnectID

La sandbox del provider ConnectID utilizza banche di test ed è separata dalla simulazione nella sandbox di Didit.
Quando l'accesso alla sandbox del provider è configurato per la tua integrazione, passa l'`authorisation_server_id` della banca selezionata all'[endpoint di avvio di ConnectID](https://docs.didit.me/it/api-reference/digital-id-wallets/connectid.md).
Usa l'ID restituito dal selettore banche di ConnectID; non inviare un URL della banca né un emittente arbitrario.
Se ometti il campo, viene selezionata la banca di test predefinita.
Il campo è specifico per ConnectID e non modifica gli attributi di identità richiesti.

Il pacchetto iniziale richiede nome, cognome e data di nascita.
Segui il `next_action` restituito per autenticarti, quindi recupera o interroga il risultato della verifica.
Solo un risultato completato con stato approvato conferma che la verifica è riuscita; il ritorno alla tua applicazione non lo conferma.
ConnectID rimane **Prossimamente** in produzione mentre vengono completati l'onboarding e la certificazione.

## Disponibilità e prezzi

La copertura degli endpoint e l'attivazione del wallet in produzione sono aspetti separati.
Un wallet può avere una pagina di riferimento API pur restando non disponibile per l'autenticazione live.
Verifica la copertura del wallet per paese e lo stato di produzione prima di implementare un percorso live.

Consulta i [prezzi dei wallet di identità digitale](https://docs.didit.me/it/getting-started/pricing.md#prezzi-dei-wallet-di-identità-digitale) per le tariffe pubblicate e la disponibilità.
La verifica tramite wallet viene fatturata separatamente dall'acquisizione dei documenti.

## Scegliere un'integrazione

Usa queste API quando vuoi gestire tu l'interfaccia e la logica dell'applicazione che le circondano.
Usa la [Sessions API](https://docs.didit.me/it/sessions-api/create-session.md) quando vuoi il percorso di verifica ospitato da Didit, le regole del workflow e i passaggi di riserva configurati.
In entrambi i casi è comunque richiesto il processo di autenticazione e consenso del wallet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.