Guia d'integració d'una API d'eID: patrons, codi i seguretat

Darrera revisió: 5 d'octubre de 2026 · No constitueix assessorament jurídic

Aquesta guia centrada en el codi és per a enginyers que afegeixen eID nacionals a l'alta de clients.

Com funciona una API d'eID: cinc patrons d'interacció

El vostre sistema és la part usuària (RP). Mai no veu la credencial en si, només una resposta signada sobre la persona.

Alguns sistemes funcionen darrere d'una passarel·la pública: TARA, d'Estònia, és una passarel·la de codi d'autorització situada davant del document d'identitat, Smart-ID, Mobile-ID i les eID de la UE.^[7] Vegeu Sistemes d'eID per país per saber quin patró fa servir cada sistema.

Què construïu vosaltres i què gestiona un proveïdor

L'accés va abans que el codi. A Dinamarca, tot proveïdor de serveis ha de passar per un intermediari certificat de MitID.^[12] A Suècia, compreu BankID a un banc o a un revenedor i sol·liciteu un certificat de part usuària.^[15] A Alemanya, podeu gestionar el vostre propi servidor eID, fer servir un servei eID allotjat amb el vostre propi certificat o fer servir un servei d'identificació sense tenir cap certificat propi.^[13] Per a la cartera europea d'identitat digital (EUDI Wallet), una part usuària s'ha de registrar a l'Estat membre on està establerta.^[1]

Hi ha intermediaris certificats per a la majoria dels sistemes nòrdics i bàltics. Connecteu-vos directament si treballeu amb un sol sistema i un volum alt; feu servir una sola API quan els usuaris vénen de diversos països.

El flux de redirecció, pas a pas

Aquest és el flux de codi d'autorització d'OIDC. El vostre backend envia el navegador a fora amb un state i un nonce aleatoris, després intercanvia el codi retornat per un ID token i el comprova.

Un inici de sessió per redirecció. Els intermediaris i les passarel·les afegeixen salts al pas 2, no passos nous per a vosaltres.

La comprovació després del pas 5 és la més important. Segons la documentació d'ID-porten de Digdir, el client «HA DE validar que el nivell de seguretat (acr) és prou alt».^[5] Llegiu acr com el nivell de garantia (LoA) que afirma el sistema, i rebutgeu qualsevol valor per sota de la vostra política.

El flux de notificació a l'app amb un codi de comparació

Smart-ID i Mobile-ID no surten mai de la vostra pàgina. L'usuari escriu un codi d'identificació personal (Mobile-ID també demana el número de telèfon), la vostra pàgina mostra un codi curt i el mateix codi apareix a l'app. L'usuari aprova amb el PIN al telèfon només quan els codis coincideixen.^[20] Smart-ID també pot mostrar tres codis i demanar a l'usuari que triï el correcte.^[10]

BankID Sweden segueix el mateix esquema, però amb un QR en lloc d'un codi escrit. L'usuari obre l'app al mateix dispositiu amb un token d'inici automàtic, o escaneja un QR animat que es mostra a l'altre dispositiu. El vostre backend consulta /collect fins que l'ordre es completa. L'ordre completada inclou el número personal, el nom, el nom de pila i el cognom, a més de camps de dispositiu, de signatura i, opcionalment, de risc.^[8] Smart-ID+ porta Smart-ID a aquest model (QR dinàmic a l'ordinador, d'app a app al mòbil), de manera que els usuaris ja no escriuen un codi personal en un lloc web.^[11]

Un inici de sessió amb Smart-ID o Mobile-ID, en l'ordre en què el veu l'usuari: codi personal, codi de comparació a la vostra pàgina, el mateix codi a l'app i, després, el PIN.^[20] En la variant QR de BankID, el pas 1 desapareix i el pas 2 mostra un codi QR.

Targeta i NFC, i la cartera europea d'identitat digital (EUDI Wallet) amb OpenID4VP

Amb el carnet d'identitat electrònic alemany, l'usuari apropa la targeta a un telèfon amb NFC a l'AusweisApp. Abans que l'usuari introdueixi el PIN, la llei obliga l'app a mostrar el nom i l'adreça del proveïdor i les categories de dades sol·licitades. Només s'envien aquestes categories.^[14]

Segons l'OpenID Foundation, OpenID4VP 1.0 és una especificació final.^[16] L'Architecture and Reference Framework (ARF) recull aquestes vies de presentació remota: OpenID4VP mitjançant redireccions i esquemes d'URI personalitzats com openid4vp://, OpenID4VP mitjançant la W3C Digital Credentials API, o ISO/IEC 18013-7 mitjançant aquesta API.^[2][17] Abans de compartir res, la cartera autentica el vostre certificat d'accés, comprova que no demaneu més atributs dels que vau registrar i permet a l'usuari aprovar-los un per un.^[2] El retrat només esdevé obligatori a les dades d'identificació de la persona (PID) a partir de l'11 d'agost de 2028, excepte quan l'usuari hi renunciï expressament.^[18]

1. 23 de juliol de 2026ARF v3.0.0Versió actual del marc de la cartera.
2. 24 de desembre de 2026Termini de les carteresCada estat membre ofereix almenys una cartera.
3. 24 de desembre de 2027AcceptacióLes parts usuàries privades obligades per llei o per contracte a utilitzar una autenticació forta de l'usuari l'accepten a petició de l'usuari. Les microempreses i les petites empreses n'estan exemptes.
4. 11 d'agost de 2028RetratEl retrat de la PID esdevé obligatori llevat que l'usuari hi renunciï.

Dates de l'EUDI Wallet que condicionen el full de ruta d'una API d'eID.^[1][2][18]

La guia de l'EUDI Wallet explica el registre de les parts usuàries i el grau de preparació per país.

Errors, alternatives i reintents

Un inici de sessió acaba completat, cancel·lat, caducat o fallit. Tracta els tres últims casos de la mateixa manera i decideix per país què passa després.

No tornis a intentar mai automàticament un inici de sessió cancel·lat. Fes que el callback sigui idempotent, perquè una recàrrega o un esdeveniment duplicat no pugui obrir dos comptes. Mantén una via per a les persones sense eID, normalment un document d'identitat amb lectura del xip NFC, prova de vida i comparació facial. La verificació d'eID per NFC i la seguretat del xip explica aquesta via.

Llista de control de seguretat per a una integració d'API d'eID

• Genera un state i un nonce nous per a cada inici de sessió i rebutja qualsevol callback que no hi coincideixi.
• Verifiqueu la signatura de cada token o resultat abans de llegir cap atribut.
• Comproveu el nivell de garantia en el resultat, no només en la sol·licitud.^[5]
• Exigeix el nivell substancial o alt quan se t'apliqui la via d'eID de l'AMLR.^[3]
• No recullis mai el PIN de l'eID a la teva pàgina; correspon a l'app del sistema.^[20]
• Prioritzeu el codi QR o l'obertura d'app a app per davant dels codis escrits en els inicis de sessió entre dispositius.^[11]
• Sol·liciteu només els atributs que heu registrat i que necessiteu.^[1]
• Verifica les signatures i les marques de temps dels webhooks abans de confiar en un resultat.

L'ancoratge legal és el Reglament contra el blanqueig de capitals (AMLR), aplicable a partir del 10 de juliol de 2027: l'article 22(6)(b) admet "mitjans d'identificació electrònica que compleixin els requisits del Reglament (UE) núm. 910/2014 pel que fa als nivells de garantia 'substancial' o 'alt'".^[3] No tots els sistemes estan notificats: MitID és a la llista de la UE de sistemes notificats, Smart-ID no.^[4]

Com us ajuda Didit amb la integració d'API d'eID

Didit ofereix cinc eID en funcionament darrere d'una única API de sessions (MitID, BankID Sweden, Finnish Trust Network, Smart-ID i Mobile-ID, en set països), amb una via documental en el mateix flux de treball. Hi ha més sistemes al full de ruta de Didit, i l'acceptació de la cartera europea d'identitat digital (EUDI Wallet) arribarà aviat. Didit no demana mai el PIN. Més informació a la pàgina de carteres d'identitat digital i a la documentació de les carteres.^[19]

Activeu les eID en funcionament per país

A la consola: Workflows, el pas ID Verification, Countries, "Wallets accepted". Per API, la funció ID Verification (OCR) rep un objecte methods indexat pel codi de país ISO 3166-1 alpha-3, enviat amb POST /v3/workflows/. El fragment documentat per a Dinamarca:^[21]

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

I per a Estònia, acceptant totes dues eID basades en el telèfon:^[20]

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

providers és una llista d'acceptació, no una classificació. on_failure és fallback_to_document o decline. Una cartera que no està disponible al teu entorn fa que es rebutgi tot el desament, així que consulta primer el catàleg.^[21]

Crea una sessió i llegeix el resultat

POST /v3/session/ amb el teu workflow_id (i opcionalment vendor_data i un callback) retorna session_id, url i session_token. Obre l'URL o fes servir l'SDK.^[24] El resultat arriba per webhook o per GET /v3/session/{id}/decision/, amb verification_method: "wallet", assurance: "cryptographic" i un objecte wallet_verification.^[19]

Un nivell inferior al sol·licitat fa que l'inici de sessió falli. Només es facturen els inicis de sessió completats.^[19] Preus: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks i entorn de proves

Verifiqueu X-Signature-V2 amb el secret de la vostra destinació, rebutgeu qualsevol X-Timestamp de més de 300 segons d'antiguitat i baseu la idempotència en event_id. Un lliurament fallit es reintenta fins a dues vegades.^[22] Una aplicació a l'entorn de proves pot activar totes les carteres, aprova sense un inici de sessió real i ofereix wallet_cancelled, wallet_timeout i wallet_provider_error per provar la vostra alternativa.^[23]

Preguntes freqüents

Fonts

1. Reglament (UE) 2024/1183 (eIDAS 2), EUR-Lex, Diari Oficial del 30 d'abril de 2024, articles 5a, 5b i 5f.
2. Architecture and Reference Framework v3.0.0, projecte EUDI Wallet de la Comissió Europea, publicat el 23 de juliol de 2026, seccions 4.4.3, 5.7.1 i 6.6.3.
3. Reglament (UE) 2024/1624 (AMLR), EUR-Lex, article 22(6).
4. Overview of pre-notified and notified eID schemes under eIDAS, Comissió Europea, consultat el 5 d'octubre de 2026.
5. ID token d'ID-porten, Agència Noruega de Digitalització (Digdir).
6. Anbindung mit OpenID Connect, documentació per a desenvolupadors d'ID Austria.
7. Especificació tècnica de TARA, Autoritat del Sistema d'Informació d'Estònia (RIA).
8. Auth and sign: collect, documentació per a desenvolupadors de BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 de juliol de 2019 (font secundària).
10. Per què de vegades veig un codi de confirmació i de vegades tres, Smart-ID.
11. Com em protegeix del frau el nou Smart-ID, Smart-ID.
12. Intermediaris de MitID, Agència Danesa per al Govern Digital.
13. Esdevenir proveïdor de serveis, AusweisApp, Govern federal alemany.
14. Secció 18 de la Llei de passaports i documents d'identitat (PAuswG), Gesetze im Internet.
15. Connecteu la vostra empresa a BankID, BankID.
16. Aprovada l'especificació final d'OpenID for Verifiable Presentations 1.0, OpenID Foundation.
17. Digital Credentials, W3C.
18. Reglament d'Execució (UE) 2026/1731 de la Comissió, EUR-Lex, retrat al PID a partir de l'11 d'agost de 2028.
19. Carteres d'identitat digital, documentació de Didit.
20. Integració de Smart-ID i Mobile-ID, documentació de Didit.
21. Configuració de funcions dels fluxos de treball, documentació de Didit.
22. Webhooks, documentació de Didit.
23. Sandbox i dades de prova, documentació de Didit.
24. Inici ràpid, documentació de Didit.

Consulteu cada eID nacional, el seu nivell i el seu estat a la pàgina de verificació amb eID.