Saltar al contingut principal
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.
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 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 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ó. 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ó:
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. 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:
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:
Comprova wallet_verification.outcome: 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). 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 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 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.
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:
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:
Errors que cal gestionar: 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. 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. 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 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 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.
Darrera modificació el 7 de novembre del 2026