Guía de integración de una API de eID: patrones, código y seguridad

Última revisión: 5 de octubre de 2026 · No constituye asesoramiento jurídico

Esta guía, centrada en el código, está dirigida a ingenieros que incorporan eID nacionales al proceso de alta de clientes.

Cómo funciona una API de eID: cinco patrones de interacción

Su sistema es la parte usuaria (RP). Nunca ve la credencial en sí, solo una respuesta firmada sobre la persona.

Algunos esquemas funcionan detrás de una pasarela pública: TARA, de Estonia, es una pasarela de código de autorización situada delante del documento de identidad, Smart-ID, Mobile-ID y las eID de la UE.^[7] Consulte esquemas de eID por país para ver qué patrón utiliza cada esquema.

Qué construye usted y qué gestiona un proveedor

El acceso va antes que el código. En Dinamarca, todo proveedor de servicios debe pasar por un intermediario de MitID certificado.^[12] En Suecia, BankID se contrata con un banco o un distribuidor y se solicita un certificado de parte usuaria.^[15] En Alemania, puede operar su propio servidor eID, usar un servicio eID alojado con su propio certificado o usar un servicio de identificación sin tener ningún certificado propio.^[13] Para la cartera EUDI, una parte usuaria debe registrarse en el Estado miembro en el que esté establecida.^[1]

Existen intermediarios certificados para la mayoría de los esquemas nórdicos y bálticos. Opte por la integración directa para un único esquema con gran volumen; use una única API cuando los usuarios procedan de varios países.

El flujo de redirección, paso a paso

Este es el flujo de código de autorización de OIDC. Su backend redirige el navegador con un state y un nonce aleatorios. Después intercambia el código devuelto por un token de ID y lo comprueba.

Un inicio de sesión por redirección. Los intermediarios y las pasarelas añaden saltos en el paso 2, no pasos nuevos para usted.

La comprobación posterior al paso 5 es la más importante. Según la documentación de ID-porten de Digdir, el cliente "DEBE validar que el nivel de seguridad (acr) es suficientemente alto".^[5] Interprete acr como el nivel de garantía (LoA) que afirma el esquema y rechace todo lo que quede por debajo de su política.

El flujo de notificación en la app con código de comparación

Con Smart-ID y Mobile-ID el usuario no sale de su página. El usuario introduce un código de identificación personal (Mobile-ID también pide el número de teléfono). Su página muestra un código corto y el mismo código aparece en la app. El usuario aprueba con el PIN en el teléfono solo si los códigos coinciden.^[20] Smart-ID también puede mostrar tres códigos y pedir al usuario que elija el correcto.^[10]

BankID Sweden sigue el mismo esquema, con un QR en lugar de un código tecleado: el usuario abre la app en el mismo dispositivo con un token de inicio automático, o escanea un QR animado que se muestra en el otro dispositivo, y su backend consulta /collect hasta que la orden se completa. La orden completada incluye el número personal, el nombre, el nombre de pila y el apellido, además de campos de dispositivo, de firma y, de forma opcional, de riesgo.^[8] Smart-ID+ traslada Smart-ID a este modelo (QR dinámico en ordenador, de app a app en el móvil), de modo que los usuarios ya no teclean un código personal en un sitio web.^[11]

Un inicio de sesión con Smart-ID o Mobile-ID, en el orden en que lo ve el usuario: código personal, código de comparación en su página, el mismo código en la app y, después, el PIN.^[20] En la variante QR de BankID, el paso 1 desaparece y el paso 2 muestra un código QR.

Tarjeta y NFC, y la cartera EUDI mediante OpenID4VP

Con el documento de identidad electrónico alemán, el usuario acerca la tarjeta a un teléfono con NFC en la AusweisApp. Antes de que se introduzca el PIN, la ley exige que la app muestre el nombre y la dirección del proveedor y las categorías de datos solicitadas, y solo se envían esas categorías.^[14]

Según la OpenID Foundation, OpenID4VP 1.0 es una especificación final.^[16] El Marco de Arquitectura y Referencia (ARF) recoge como presentación remota OpenID4VP mediante redirecciones y esquemas URI personalizados como openid4vp://, OpenID4VP a través de la W3C Digital Credentials API, o ISO/IEC 18013-7 a través de esa API.^[2][17] Antes de compartir nada, la cartera autentica su certificado de acceso, comprueba que no solicita más atributos de los que registró y permite al usuario aprobar cada uno.^[2] El retrato solo pasa a ser obligatorio en los datos de identificación personal (PID) a partir del 11 de agosto de 2028, salvo que el usuario lo rechace expresamente.^[18]

1. 23 de julio de 2026ARF v3.0.0Versión actual del marco de la cartera.
2. 24 de diciembre de 2026Plazo de las carterasCada Estado miembro ofrece al menos una cartera.
3. 24 de diciembre de 2027AceptaciónLas partes usuarias privadas obligadas por ley o por contrato a utilizar la autenticación reforzada de usuario la aceptan a petición del usuario. Las microempresas y pequeñas empresas están exentas.
4. 11 de agosto de 2028RetratoEl retrato del PID pasa a ser obligatorio salvo que el usuario lo rechace.

Fechas de la cartera EUDI que condicionan la hoja de ruta de una API de eID.^[1][2][18]

La guía de la cartera EUDI trata el registro de partes usuarias y el grado de preparación por país.

Errores, alternativas y reintentos

Un inicio de sesión termina completado, cancelado, caducado o fallido. Trate los tres últimos de la misma forma y decida por país qué ocurre después.

Nunca reintente automáticamente un inicio de sesión cancelado. Haga que el callback sea idempotente, para que una recarga o un evento duplicado no puedan abrir dos cuentas. Mantenga una vía para las personas sin eID, normalmente un documento de identidad con lectura del chip NFC, prueba de vida y comparación facial. Verificación de eID por NFC y seguridad del chip explica esa vía.

Lista de comprobación de seguridad para una integración de API de eID

• Genere un state y un nonce nuevos en cada inicio de sesión y rechace cualquier callback que no coincida con ellos.
• Verifique la firma de cada token o resultado antes de leer un solo atributo.
• Compruebe el nivel de garantía en el resultado, no solo en la solicitud.^[5]
• Exija un nivel sustancial o alto cuando le sea aplicable la vía eID del AMLR.^[3]
• Nunca recoja el PIN de la eID en su página; corresponde a la app del esquema.^[20]
• En los inicios de sesión entre dispositivos, priorice el código QR o el lanzamiento de app a app frente a los códigos tecleados.^[11]
• Solicite solo los atributos que haya registrado y que necesite.^[1]
• Verifique las firmas y las marcas de tiempo de los webhooks antes de dar por bueno un resultado.

El anclaje jurídico es el Reglamento contra el blanqueo de capitales (AMLR), aplicable a partir del 10 de julio de 2027: el artículo 22(6)(b) admite «medios de identificación electrónica que cumplan los requisitos del Reglamento (UE) n.º 910/2014 en lo que respecta a los niveles de garantía “sustancial” o “alto”».^[3] No todos los esquemas están notificados: MitID figura en la lista de la UE de esquemas notificados, Smart-ID no.^[4]

Cómo ayuda Didit con la integración de API de eID

Didit reúne cinco eID operativas tras una única API de sesiones (MitID, BankID Sweden, Finnish Trust Network, Smart-ID y Mobile-ID, en siete países), con una vía documental en el mismo flujo de trabajo. Hay más esquemas en la hoja de ruta de Didit, y la aceptación de la cartera EUDI llegará próximamente. Didit nunca solicita el PIN. Más información en la página de carteras de identidad digital y en la documentación de carteras.^[19]

Active por país las eID operativas

En la consola: Workflows, el paso ID Verification, Countries, «Wallets accepted». A través de la API, la función ID Verification (OCR) recibe un objeto methods indexado por código de país ISO 3166-1 alfa-3, enviado con POST /v3/workflows/. El fragmento documentado para Dinamarca:^[21]

{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }

Y para Estonia, aceptando las dos eID basadas en el teléfono:^[20]

{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }

providers es una lista de aceptación, no una clasificación. on_failure admite fallback_to_document o decline. Una cartera que no esté disponible en su entorno provoca el rechazo de todo el guardado, así que consulte antes el catálogo.^[21]

Crear una sesión y leer el resultado

POST /v3/session/ con su workflow_id (y, opcionalmente, vendor_data y un callback) devuelve session_id, url y session_token. Abra la URL o use el SDK.^[24] El resultado llega por webhook o mediante GET /v3/session/{id}/decision/, con verification_method: "wallet", assurance: "cryptographic" y un objeto wallet_verification.^[19]

Un nivel inferior al solicitado hace que el inicio de sesión falle. Solo se facturan los inicios de sesión completados.^[19] Precios: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks y sandbox

Verifique X-Signature-V2 con el secreto de su destino, rechace un X-Timestamp con más de 300 segundos de antigüedad y base la idempotencia en event_id. Una entrega fallida se reintenta hasta dos veces.^[22] Una aplicación de sandbox puede habilitar todas las carteras, aprueba sin un inicio de sesión real y ofrece wallet_cancelled, wallet_timeout y wallet_provider_error para probar su flujo alternativo.^[23]

Preguntas frecuentes

Fuentes

1. Reglamento (UE) 2024/1183 (eIDAS 2), EUR-Lex, Diario Oficial de 30 de abril de 2024, artículos 5a, 5b y 5f.
2. Architecture and Reference Framework v3.0.0, proyecto EUDI Wallet de la Comisión Europea, publicado el 23 de julio de 2026, secciones 4.4.3, 5.7.1 y 6.6.3.
3. Reglamento (UE) 2024/1624 (AMLR), EUR-Lex, artículo 22(6).
4. Overview of pre-notified and notified eID schemes under eIDAS, Comisión Europea, consultado el 5 de octubre de 2026.
5. ID-porten ID token, Agencia Noruega de Digitalización (Digdir).
6. Anbindung mit OpenID Connect, documentación para desarrolladores de ID Austria.
7. TARA technical specification, Autoridad del Sistema de Información de Estonia (RIA).
8. Auth and sign: collect, documentación para desarrolladores de BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 de julio de 2019 (fuente secundaria).
10. Why do I sometimes see one confirmation code and sometimes three, Smart-ID.
11. How does the new Smart-ID protect me from fraud, Smart-ID.
12. Intermediarios de MitID, Agencia Danesa de Administración Digital.
13. Become a service provider, AusweisApp, Gobierno federal alemán.
14. Sección 18 de la Ley de Pasaportes y Documentos de Identidad (PAuswG), Gesetze im Internet.
15. Conecte su empresa a BankID, BankID.
16. OpenID for Verifiable Presentations 1.0 final specification approved, OpenID Foundation.
17. Digital Credentials, W3C.
18. Reglamento de Ejecución (UE) 2026/1731 de la Comisión, EUR-Lex, retrato en el PID a partir del 11 de agosto de 2028.
19. Carteras de identidad digital, documentación de Didit.
20. Integración de Smart-ID y Mobile-ID, documentación de Didit.
21. Configuración de funcionalidades del flujo de trabajo, documentación de Didit.
22. Webhooks, documentación de Didit.
23. Sandbox y datos de prueba, documentación de Didit.
24. Inicio rápido, documentación de Didit.

Consulte cada eID nacional, su nivel y su estado en la página de verificación con eID.