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ó
- 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ó.
- Didit retorna una referència de verificació i l’acció que la persona ha de fer.
- La teva aplicació obre la pàgina d’autenticació o mostra les instruccions d’aprovació de la cartera.
- La persona s’autentica amb la seva cartera.
- El teu backend recupera el resultat verificat i gestiona les notificacions de finalització.
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 teux-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ó: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: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:
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 perpoll_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ó."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:
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 astatus.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 ambwallet_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 elauthorisation_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ó.