> ## 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 de verificació amb carteres d'identitat digital

> Verifica la identitat mitjançant una cartera d'ID digital des de la teva aplicació, sense crear un flux de verificació amb Didit.

Utilitza un endpoint de cartera dedicat per verificar una persona des de la teva pròpia aplicació.
No cal que creïs ni publiquis un flux de treball, ni que proporcionis un `workflow_id`.
El teu backend inicia la verificació i recupera'n el resultat; la teva interfície guia la persona pel procés d'autenticació que requereix la cartera.

> [!NOTE]
>
> Una integració amb l'API encara requereix que la persona s'autentiqui i aprovi compartir la seva identitat.
> No pots verificar algú enviant el seu identificador personal sense aquesta interacció.

## Com funciona la verificació

1. El teu backend consulta el [catàleg de carteres](https://docs.didit.me/ca/standalone-apis/digital-id-wallet-catalog.md) i després crida l'endpoint d'inici d'una cartera disponible amb la teva clau d'API d'aplicació.
2. Didit retorna una referència de verificació i l'acció que la persona ha de fer.
3. La teva aplicació obre la pàgina d'autenticació o mostra les instruccions d'aprovació de la cartera.
4. La persona s'autentica amb la seva cartera.
5. El teu backend recupera el resultat verificat i gestiona les notificacions de finalització.

L'autenticació amb cartera és asíncrona.
Una sol·licitud d'inici satisfactòria vol dir que l'autenticació ha començat; no vol dir que la identitat s'hagi verificat.
Comprova sempre el resultat final abans de considerar que la persona està verificada.

## Integració al backend

Fes servir [Llista de carteres d'identitat digital](https://docs.didit.me/ca/standalone-apis/digital-id-wallet-catalog.md) per obtenir els endpoints actuals, els camps obligatoris i la disponibilitat per a la teva aplicació.

Mantén el teu `x-api-key` al backend.
No el posis en un paquet de codi del navegador ni en una aplicació mòbil.
Fes servir un `Idempotency-Key` diferent per a cada nou intent de verificació i reutilitza aquesta clau quan reintentis la mateixa sol·licitud d'inici.
Canviar la sol·licitud mentre reutilitzes la seva clau és un conflicte, no un nou intent de verificació.

Cada cartera té la seva pròpia URL d'inici, com ara `/v3/id-verification/wallets/ftn/` per a Finnish Trust Network.
El `request_id` identifica la verificació independent per a les operacions posteriors.
Fes servir `vendor_data` per a la teva pròpia referència, fins a 2,000 bytes UTF-8, i `metadata` per a un objecte JSON opcional.
Tots dos es retornen amb el resultat i amb el webhook de finalització.

| Operació | Endpoint |
| - | - |
| Llegir l'estat i el resultat | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Consultar una aprovació telefònica | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Enviar una resposta de cartera de credencials digitals | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Cancel·lar una verificació pendent | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

Aquestes operacions fan servir la clau d'API de l'aplicació que ha iniciat la verificació.
La consulta i la disponibilitat de l'autenticació depenen de la cartera seleccionada.

Una cancel·lació rebutja una verificació pendent sense cobrar-la, i retorna una verificació completada sense canvis.
Per a Smart-ID i Mobile-ID, una cancel·lació que arriba mentre una consulta està comprovant l'aprovació espera uns segons que finalitzi aquesta consulta.
Després rebutja la verificació, o la retorna com a `verified` si la persona ja l'havia aprovada.
No es pot cancel·lar una verificació que la persona està completant en aquest moment: la resposta és `409` amb `error: "verification_in_progress"` i una capçalera `Retry-After`.
Torna-ho a intentar després d'aquest nombre de segons per llegir el resultat completat.

## Registra la teva destinació de retorn

Les carteres amb redirecció envien la persona de tornada a la teva aplicació després de l'autenticació.
Registra el nom d'host exacte abans d'iniciar una verificació:

```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"]}'
```

Després, envia a la sol·licitud d'inici un `return_url` HTTPS, com ara `https://app.example.com/identity/complete`.
Fes servir noms d'host simples a `allowed_return_hosts`, sense esquema, camí ni comodí.
Registra cada subdomini que facis servir per separat, fins a 20 noms d'host.
Actualitzar `allowed_return_hosts` substitueix la llista registrada, així que inclou tots els noms d'host que vulguis conservar.
`GET /v3/webhook/` retorna la llista actual; consulta [Configuració del webhook](https://docs.didit.me/ca/sessions-api/management-api.md#configuració-del-webhook).
No necessites un flux de treball ni un domini de marca blanca per registrar una destinació de retorn.
La destinació és una pàgina de retorn del navegador; configura els webhooks de finalització per separat per al teu backend.

## Exemple: Finnish Trust Network

Després de registrar el teu nom d'host de retorn, inicia una verificació de 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"
  }'
```

Desa el `request_id` retornat i envia el navegador de la persona a `wallet_verification.next_action.url` quan el seu `type` sigui `redirect`.
Després que la persona torni, recupera el resultat des del teu 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'
```

Comprova `wallet_verification.outcome`:

| Resultat | Significat |
| - | - |
| `pending` | L'autenticació encara està en curs. |
| `verified` | L'autenticació s'ha completat i la identitat retornada està verificada. |
| `cancelled` | La persona o la teva aplicació han cancel·lat l'intent. |
| `timeout` | La finestra d'autenticació ha caducat. |
| `failed` | L'autenticació o la validació de la identitat ha fallat. |

Només fes servir la identitat quan el resultat sigui `verified` i `simulated` sigui `false` en una comprovació d'identitat real.
Una resposta pendent pot incloure una acció següent; les respostes finals no tenen cap acció següent.

## Experiències d'autenticació

**Les carteres de redirecció** retornen un URL d'autenticació.
Obre aquest URL al navegador de la persona, deixa que completi el procés d'autenticació de la cartera i retorna-la a la destinació de retorn registrada.
Llegeix el resultat des del teu backend en lloc de confiar en un paràmetre de l'URL de retorn com a prova d'identitat.

**Smart-ID i Mobile-ID** fan servir una sol·licitud d'aprovació al telèfon de la persona.
La teva interfície recull l'identificador personal obligatori; Mobile-ID també necessita el número de telèfon associat.
Mostra el codi de comparació i indica a la persona que aprovi només quan coincideixi amb el codi del seu telèfon.
El seu PIN s'ha d'introduir a la sol·licitud de la cartera o del telèfon, mai al teu formulari ni a una sol·licitud d'API.
Consulta des del teu backend a l'interval indicat per `poll_interval_seconds` per obtenir una resposta immediata sobre la sol·licitud.
Didit també comprova en segon pla les aprovacions pendents al telèfon, de manera que la finalització pot arribar al teu webhook després que la persona tanqui la teva pàgina.

**Google Wallet** es demana des de la teva pròpia pàgina o aplicació mitjançant la Digital Credentials API, sense redirecció; consulta [Carteres de Digital Credentials (Google Wallet)](#carteres-de-digital-credentials-google-wallet).

La interacció disponible depèn de la cartera seleccionada.
No donis per fet que totes les carteres admeten un formulari integrat, un codi QR o l'autenticació sense navegador.

## Carteres de Digital Credentials (Google Wallet)

Google Wallet es demana directament des de la teva pàgina web o des de la teva aplicació d'Android, mitjançant la W3C Digital Credentials API.
No hi ha redirecció, ni pàgina allotjada per Didit, ni codi QR de Didit.
Està disponible en producció i en sandbox.
Les aplicacions de sandbox no necessiten registre; cada aplicació de producció es registra una vegada des de la consola (pas de verificació d'identitat, fila de Google Wallet, **Registra't amb Google**) abans de poder utilitzar Google Wallet.
Consulta [Llista de carteres d'identitat digital](https://docs.didit.me/ca/standalone-apis/digital-id-wallet-catalog.md) per saber què pot iniciar ara la teva aplicació.

**1. Comença amb el teu origen**

El teu backend crida `POST /v3/id-verification/wallets/google-wallet/` amb el `country` de la persona (`USA`, `GBR`, `BRA`, `SGP` o `TWN`) i el `origin` des del qual es demanarà la cartera.
El `origin` és l'origen HTTPS de la teva pàgina, com `https://app.example.com`, el host del qual ha de ser un dels teus [noms d'host de retorn registrats](#registra-la-teva-destinació-de-retorn) o el teu domini de marca blanca.
Per a una aplicació d'Android és `android:apk-key-hash:` seguit del SHA-256 en base64 del certificat de signatura de la teva aplicació, sense padding.
La cartera rebutja qualsevol sol·licitud feta des d'un altre origen.
No hi ha `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. Demana la cartera dins d'un gest de l'usuari**

La resposta té `wallet_verification.interaction = "digital_credentials"` i `next_action.type = "request_digital_credential"`.
Passa `next_action.digital_credentials.request` al navegador o al Credential Manager d'Android, des d'un toc o clic a l'`origin` amb què vas començar.
A l'escriptori, el navegador mostra el seu propi codi QR quan la cartera es troba en un altre dispositiu.

**3. Envia el que ha retornat la cartera**

Envia el `{protocol, data}` retornat al teu backend i, des d'allà, a `POST /v3/id-verification/wallets/verifications/{request_id}/response/` com a `{"response": {...}}`.
La sol·licitud només es pot enviar una vegada; un segon enviament retorna la verificació ja decidida.

**4. Llegeix el resultat**

La resposta de l'enviament és la verificació decidida.
També la pots llegir amb `GET /v3/id-verification/wallets/verifications/{request_id}/` o rebre-la al webhook de finalització.

Al navegador, demana la cartera des d'un gestor de clics:

```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);
  }
});
```

Ofereix el mètode només quan el navegador l'admeti, per exemple quan `"DigitalCredential" in window` és true.
`navigator.credentials.get` s'ha d'executar dins d'un gest de l'usuari, així que crida'l des del gestor de clics i no després d'un pas asíncron.

A Android, fes servir Jetpack Credential Manager (`androidx.credentials` 1.5.0 o posterior) amb la mateixa sol·licitud:

```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.
```

Errors que cal gestionar:

| Error | Lloc | Significat |
| - | - | - |
| `origin_invalid` | Inici, `400` | `origin` no és un origen HTTPS ni un origen d'aplicació d'Android. |
| `origin_not_allowed` | Inici, `400` | El host de l'origen no està registrat per a la teva aplicació. Registra'l a `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Enviament, `409` | Aquesta verificació no accepta una resposta de cartera. |

Una credencial que no supera la verificació és una verificació decidida amb un resultat `failed`, no una resposta d'error.
Només surten de la cartera els camps que la verificació demana, i el resultat conté els atributs d'identitat que la cartera ha retornat.
Un carnet d'identitat de Google Wallet o un carnet de conduir mòbil d'un estat dels EUA no retorna un retrat.

En una aplicació de sandbox, el flux es simula amb els mateixos passos i retorna `simulated: true`.
Qualsevol resposta enviada decideix la verificació segons el `sandbox_scenario`, de manera que pots construir tot el recorregut al navegador o a l'aplicació sense una credencial real.

## Webhooks de finalització

Configura una destinació del webhook de l'aplicació per a `status.updated` seguint la [guia d'integració de webhooks](https://docs.didit.me/ca/integration/webhooks.md).
Fes servir `webhook_version: "v3"` per a l'estructura de decisió que es descriu aquí.
Verifica la signatura del webhook al teu backend abans de processar-lo.
El `session_id` del webhook coincideix amb el `request_id` retornat per l'API de carteres.
Una identitat de cartera completada apareix a l'array `decision.id_verifications` del webhook amb `verification_method: "wallet"`.
També pots fer servir l'identificador per recuperar el resultat dedicat de l'API de carteres.

Gestiona les notificacions d'aprovació i de rebuig, incloses les verificacions cancel·lades i caducades.
Fes que el teu gestor de webhooks sigui idempotent, perquè els lliuraments fallits es tornen a intentar.
Un retorn des del navegador no és un webhook de finalització, i els seus paràmetres de consulta no són prova d'identitat.

## Identitat retornada

Utilitza els camps d'identitat normalitzats per als noms i les dates de naixement quan aquests camps es retornin.
Els atributs específics de la cartera descriuen la informació d'identitat que la cartera seleccionada comparteix.
Els atributs disponibles varien segons la cartera i el país.
Una identitat autenticada no implica que hi hagi disponible un retrat, una adreça ni cap altre atribut sol·licitat.

## Prova en sandbox

Una aplicació en mode sandbox de Didit simula la verificació amb cartera sense contactar amb cap proveïdor de carteres ni cobrar crèdits.
La resposta identifica aquestes sol·licituds amb `wallet_verification.simulated: true`.
Una aprovació simulada consisteix en dades de mostra, no una identitat real verificada.

Per a una cartera de redirecció, segueix l'URL retornat per executar el callback i tornar a la teva aplicació.
Per a Smart-ID o Mobile-ID, utilitza l'endpoint de consulta per completar l'aprovació simulada; no s'envia cap notificació al telèfon.
Per provar la gestió d'errors, defineix `sandbox_scenario` com a `wallet_cancelled`, `wallet_timeout` o `wallet_provider_error` en iniciar una sol·licitud.
Les aplicacions en producció rebutgen `sandbox_scenario`.

La simulació del sandbox de Didit és independent de les proves contra l'entorn de prova propi d'un proveïdor.
Una simulació reeixida no estableix l'accés a un proveïdor en producció ni la disponibilitat en producció.

### Sandbox del proveïdor ConnectID

El sandbox del proveïdor ConnectID utilitza bancs de prova i és independent de la simulació del sandbox de Didit.
Quan l'accés al sandbox del proveïdor estigui configurat per a la teva integració, passa el `authorisation_server_id` del banc seleccionat a l'[endpoint d'inici de ConnectID](https://docs.didit.me/ca/api-reference/digital-id-wallets/connectid.md).
Utilitza l'ID retornat pel selector de bancs de ConnectID; no enviïs un URL de banc ni un emissor arbitrari.
Si omets el camp, se selecciona el banc de prova per defecte.
El camp és específic de ConnectID i no canvia els atributs d'identitat sol·licitats.

El paquet inicial sol·licita el nom de pila, el cognom i la data de naixement.
Segueix el `next_action` retornat per autenticar-te i, després, obtén o consulta el resultat de la verificació.
Només un resultat completat amb un estat aprovat confirma que la verificació ha tingut èxit; tornar a la teva aplicació no ho confirma.
ConnectID encara figura com a **Properament** en producció mentre es completen l'alta i la certificació.

## Disponibilitat i preus

La cobertura dels endpoints i l'activació en producció de les carteres són coses diferents.
Una cartera pot tenir una pàgina de referència de l'API mentre no estigui disponible per a l'autenticació en producció.
Comprova la cobertura per país i l'estat de producció de la cartera abans d'implementar un recorregut en producció.

Consulta els [preus de les carteres d'identitat digital](https://docs.didit.me/ca/getting-started/pricing.md#preus-de-les-carteres-d’identitat-digital) per conèixer les tarifes publicades i la disponibilitat.
La verificació amb cartera es factura per separat de la captura de documents.

## Triar una integració

Utilitza aquestes APIs quan vulguis gestionar tu mateix la interfície que envolta el procés i la lògica de l'aplicació.
Utilitza l'[API de Sessions](https://docs.didit.me/ca/sessions-api/create-session.md) quan vulguis el recorregut de verificació allotjat de Didit, les regles del flux de treball i els passos alternatius configurats.
En tots dos casos cal igualment el procés d'autenticació i consentiment de la cartera.


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