Verificar un mDoc funciona igual que con SD-JWT VC: creás una sesión diciendo qué datos querés, mostrás un QR y recibís un webhook. La diferencia está en cómo se nombra cada dato: en un mDoc, cada dato vive dentro de un namespace (un grupo de datos con nombre propio), así que se nombra con dos partes, namespace y dato.
Hay dos casos: el esquema que usa el namespace ISO (org.iso.18013.5.1) o el que
genera Sovra, y el esquema con un namespace propio. Donde difieren, vas a ver
pestañas. Qué es cada uno está en
Tipos de credenciales.
El flujo
Crear la sesión con lo que querés pedir
Le mandás a Sovra una consulta DCQL con
format: "mso_mdoc":curl -s -X POST "$BASE_URL/api/v1/verifier/verifications" \ -H "Authorization: Bearer $SOVRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "dcql_query": { "credentials": [ { "id": "licencia", "format": "mso_mdoc", "meta": { "doctype_value": "org.iso.18013.5.1.mDL" }, "claims": [ { "path": ["org.iso.18013.5.1", "family_name"] }, { "path": ["org.iso.18013.5.1", "given_name"] }, { "path": ["org.iso.18013.5.1", "age_over_18"] } ] } ] } }'Ojo: con el docType ISO, el namespace es
org.iso.18013.5.1, no el docType (org.iso.18013.5.1.mDL). Con el docType que genera Sovra (io.sovra.…) y sin namespace propio, el namespace sí es la misma cadena que el docType.curl -X POST "$BASE_URL/api/v1/verifier/verifications" \ -H "Authorization: Bearer $SOVRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "dcql_query": { "credentials": [{ "id": "licencia", "format": "mso_mdoc", "meta": { "doctype_value": "io.sovra.0x5de0df12cce712ddaaa23feb359920ae4f3230d4.driving_licence_v2.1" }, "claims": [ {"path": ["mx.gob.nl.icv.1", "given_name"]}, {"path": ["mx.gob.nl.icv.1", "family_name"]}, {"path": ["mx.gob.nl.icv.1", "age_over_18"]} ] }] } }'Ojo:
doctype_valuelleva el docType y elpathlleva el namespace (mx.gob.nl.icv.1), que acá son cadenas distintas. Leelas del esquema (Listar esquemas), no las deduzcas.En palabras:
ides una etiqueta tuya. Vuelve tal cual en el resultado.meta.doctype_value(opcional) es el tipo de documento exacto que aceptás. Si no coincide con el presentado, falla condoctype_mismatch.- Cada
pathtiene exactamente dos partes:["<namespace>", "<dato>"].
La respuesta trae el
session_id(vuelve en el webhook comoverification_id), la URI para el QR yexpires_at. Referencia completa: Crear una verificación.Mostrar el QR
Mostrá como QR la URI
authorization_request_uri_ref: es corta (unos 250 caracteres) y no crece con la consulta.jq -r '.authorization_request_uri_ref' resp.json | qrencode -o qr.png -s 8La wallet busca la credencial por docType y le muestra al ciudadano cada dato pedido. Puede destildar los que no quiera compartir, salvo los marcados como
always shared, que se comparten siempre. La sesión dura 10 minutos.Recibir el resultado
Llega
presentation.verifiedopresentation.failed. Las claves declaimsllevan el namespace adelante:{ "event": "presentation.verified", "data": { "verification_id": "e2d16450-42e8-46a9-ae92-d72af51a7435", "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274", "success": true, "credentials": [ { "id": "licencia", "format": "mso_mdoc", "claims": { "org.iso.18013.5.1.family_name": "Lovelace", "org.iso.18013.5.1.given_name": "Ada", "org.iso.18013.5.1.age_over_18": true } } ] } }{ "event": "presentation.verified", "data": { "verification_id": "e2d16450-42e8-46a9-ae92-d72af51a7435", "holder_did": "did:sovra:0x9083…f274", "success": true, "credentials": [{ "id": "licencia", "format": "mso_mdoc", "claims": { "mx.gob.nl.icv.1.given_name": "Sofía", "mx.gob.nl.icv.1.family_name": "Demo", "mx.gob.nl.icv.1.age_over_18": true } }] } }Si algo falló,
presentation.failedtrae unerrorque dice en qué paso se cortó, por ejemplomissing_required_claim:org.iso.18013.5.1.first_name. Qué significa cada valor está en Errores de verificación.
Qué pedir
Pedí el mínimo necesario: cada dato es algo que el ciudadano ve en la pantalla de
aprobación y puede rechazar, y si falta uno solo, falla toda la presentación. Si solo
necesitás saber que es mayor de edad, pedí age_over_18 y no birth_date. Para la
primera prueba, un solo dato alcanza para comprobar que todo el circuito funciona.
Reglas finas de DCQL para mDoc
- Dos partes, siempre.
["<namespace>", "<dato>"], ni una ni tres. No uses["family_name"](es de SD-JWT) ni un parnamespace/claim_name(de un borrador viejo de la especificación). Unpathque no sea de dos cadenas devuelve400 invalid_mdoc_claim_pathal crear la sesión. - El namespace no es el docType cuando el docType es ISO, ni cuando el esquema
declara un namespace propio. Confundirlos da
missing_required_claim:<namespace>.<elemento>: el dato existe, pero se lo busca donde no está. - Sin
meta.doctype_valuese acepta cualquier docType. - Sin
claims, la wallet comparte solo los datos que no se pueden retener y el resultado llega con"claims": {}. Sirve para «acreditame que tenés una credencial de este docType», no para obtener datos. - No se mezclan formatos:
mso_mdocconvc+sd-jwten la misma consulta da400 mixed_dcql_formats. Si necesitás los dos, usá dos sesiones. - Los datos
always sharedviajan aunque no los pidas. Por ejemplo, sifamily_nameysecond_family_namesonalways shared, el apellido materno llega igual, como clave separada.
Más ejemplos de consultas
Identificación para atención presencial:
{ "credentials": [ { "id": "identidad", "format": "mso_mdoc",
"claims": [
{ "path": ["org.iso.18013.5.1", "family_name"] },
{ "path": ["org.iso.18013.5.1", "given_name"] },
{ "path": ["org.iso.18013.5.1", "document_number"] },
{ "path": ["org.iso.18013.5.1", "portrait"] }
] } ] }Categorías habilitadas:
{ "credentials": [ { "id": "categorias", "format": "mso_mdoc",
"claims": [ { "path": ["org.iso.18013.5.1", "driving_privileges"] } ] } ] }Cualquier mDoc del docType indicado, sin pedir datos:
{ "credentials": [ { "id": "cualquiera", "format": "mso_mdoc",
"meta": { "doctype_value": "io.sovra.0xab…ef.credencial.1" } } ] }Un esquema con docType generado, donde el namespace es el docType completo:
{ "credentials": [ { "id": "membresia", "format": "mso_mdoc",
"claims": [ { "path": ["io.sovra.0xab…ef.membresia.1", "nivel"] } ] } ] }Urgencias médicas:
"claims": [
{"path": ["mx.gob.nl.icv.1", "blood_type"]},
{"path": ["mx.gob.nl.icv.1", "allergies"]},
{"path": ["mx.gob.nl.icv.1", "organ_donor"]},
{"path": ["mx.gob.nl.icv.1", "emergency_phone"]}
]Comprobante de domicilio, sin fotografía, folio ni fecha de nacimiento:
"claims": [
{"path": ["mx.gob.nl.icv.1", "street"]},
{"path": ["mx.gob.nl.icv.1", "exterior_number"]},
{"path": ["mx.gob.nl.icv.1", "interior_number"]},
{"path": ["mx.gob.nl.icv.1", "neighborhood"]},
{"path": ["mx.gob.nl.icv.1", "resident_city"]},
{"path": ["mx.gob.nl.icv.1", "resident_postal_code"]}
]Zona de cobertura: calle y código postal, nada más.
"claims": [
{"path": ["mx.gob.nl.icv.1", "street"]},
{"path": ["mx.gob.nl.icv.1", "resident_postal_code"]}
]Trámite que requiere CURP:
"claims": [
{"path": ["mx.gob.nl.icv.1", "curp"]},
{"path": ["mx.gob.nl.icv.1", "given_name"]},
{"path": ["mx.gob.nl.icv.1", "family_name"]},
{"path": ["mx.gob.nl.icv.1", "second_family_name"]}
]Cómo vuelve cada tipo de dato (y las imágenes)
| Tipo | Se envía como | Vuelve como |
|---|---|---|
string, uri |
"Sofía" |
Igual |
integer, number |
170 |
170 |
boolean |
true |
true |
date |
"2030-10-22" |
"2030-10-22" |
datetime |
"2026-10-22T14:30:00Z" |
"2026-10-22T14:30:00Z" |
bytes |
base64 estándar con padding | base64url sin padding (ojo) |
driving_privileges |
Array de objetos | Array de objetos; las fechas, "YYYY-MM-DD" |
Las fechas llegan como cadenas ISO, no como objetos.
Las imágenes (bytes) se envían en base64 estándar pero vuelven en base64url sin
padding: es la causa más frecuente de una imagen ilegible del lado del verificador.
Para mostrarlas, convertilas:
const b64url = claims["mx.gob.nl.icv.1.signature_usual_mark"];
// base64url → base64 estándar, reponiendo el padding
const b64 = b64url
.replace(/-/g, "+")
.replace(/_/g, "/")
.padEnd(Math.ceil(b64url.length / 4) * 4, "=");
img.src = `data:image/png;base64,${b64}`;Las dos URIs del QR y los campos de la sesión
La respuesta de crear la sesión:
{
"session_id": "e2d16450-42e8-46a9-ae92-d72af51a7435",
"authorization_request_uri": "openid4vp://?client_id=…&request=eyJ…",
"authorization_request_uri_ref": "openid4vp://?client_id=…&request_uri=https%3A%2F%2F…",
"status": "pending",
"expires_at": "2026-09-28T13:12:34Z"
}authorization_request_uri_reflleva un enlace a la solicitud firmada: unos 250 caracteres, constante. Es la recomendada para el QR.authorization_request_urilleva la solicitud firmada entera: 2000 a 3000 caracteres con un DCQL completo. El máximo absoluto de un QR en modo byte son 2953 caracteres, así que con varios datos y undoctype_valuelargo el QR queda muy denso. Queda como recurso para una wallet que no implemente pass-by-reference, y en ese caso reducir la consulta es un requisito.
Cuidado con los generadores de QR en línea: varios cortan a 1000 caracteres casi sin
avisar. La wallet recibe una URI mutilada y responde
Missing required OpenID4VP parameters, un error que parece de la wallet y es del
generador. Generalo en local, como en el paso 2.
En el resultado, holder_did sale de un namespace interno de la credencial
(io.sovra.meta.1), porque un mDoc no lleva DID. Viene null cuando la falla ocurre
antes de identificar al holder, como en malformed_vp_token, unknown_issuer o
session_expired.
Para consultar y listar sesiones por API, ver Consultar sesiones: es igual para los dos formatos.
Tres fallos que parecen el mismo
Los tres se ven como «no funciona la verificación», pero ocurren en etapas distintas. El mensaje dice en cuál:
| Mensaje | Etapa | Causa |
|---|---|---|
422 unencodable_claims: portrait, signature_usual_mark |
Emisión | Los bytes llevan el prefijo data:image/jpeg;base64,. Van sin prefijo. Ver Emitir mDoc. |
Missing required OpenID4VP parameters |
La wallet lee el QR | La URI llegó truncada. Casi siempre, un generador de QR con tope de caracteres. |
DID … publishes no P-256 assertion key #key-assert |
La wallet resuelve el DID | La wallet consulta una cadena donde ese workspace no está registrado. |
El segundo ocurre antes que el tercero: mientras el QR llegue cortado, nunca vas a saber si la cadena está bien.
Comprobar en qué cadena vive el DID
Los dos primeros fallos se arreglan del lado del emisor. El tercero depende de a qué cadena apunta la wallet que usa el ciudadano. Antes de pedirle nada a nadie, comprobá en qué cadena está registrado el DID de tu workspace: es una consulta de solo lectura, sin API key.
Cómo hacer la consulta a la cadena
curl -s -X POST https://rpc.testnet.sovra.io \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"eth_call","id":1,"params":[{
"to":"0xB9A2c855376ED79966e5f4956D3BfD21ef80d96E",
"data":"0x55ea6c470000000000000000000000005de0df12cce712ddaaa23feb359920ae4f3230d4"
},"latest"]}'El data es resolve(address) seguido de la dirección del workspace rellenada a 32
bytes. En la respuesta:
- Todo ceros: el DID no está en esa cadena. Una wallet que resuelva ahí va a dar el error de la llave.
- Aparece
9b37b628c726e77e17c0c89d093ef9a80df1cf7cdc4d658dd9a29953ff3105f8: la llave está publicada. Ese hash eskeccak256("key-assert")y es constante, así que sirve de marcador visual.
| Entorno | RPC | DID Registry |
|---|---|---|
| Test | https://rpc.testnet.sovra.io |
0xB9A2c855376ED79966e5f4956D3BfD21ef80d96E |
| Producción | https://rpc.sovra.io |
0x3829184dB00Ae8C7a6c72104A2Ede879F6F25e78 |
Emitir funciona igual aunque esto falle, y es lo que más confunde: la emisión no resuelve ningún DID. La verificación es el único flujo en que la wallet consulta la cadena.
Qué valida Sovra, paso a paso
La cascada corre en orden y se corta en el primer fallo:
| # | Comprobación | Fallo asociado |
|---|---|---|
| 1 | El DeviceResponse se analiza correctamente |
malformed_vp_token |
| 2 | Se resuelve el emisor, por la dirección del docType o por el x5chain |
unknown_issuer |
| 3 | La firma del issuerAuth valida contra la llave resuelta |
credential_signature_invalid |
| 4 | El docType del MSO firmado coincide con el del documento |
credential_signature_invalid |
| 5 | Los digests de los elementos divulgados coinciden con valueDigests |
invalid_disclosure |
| 6 | El namespace io.sovra.meta.1 está completo y correctamente tipado |
missing_mandatory_element:io.sovra.meta.1 |
| 7 | La dirección del emisor del namespace meta coincide con la resuelta | unknown_issuer |
| 8 | Están presentes todos los elementos obligatorios congelados en la emisión | missing_mandatory_element:<ns>.<elemento> |
| 9 | validFrom <= ahora < validUntil, y la firma no tiene fecha futura |
credential_expired |
| 10 | La deviceKey del MSO está entre las llaves que el holder autoriza actualmente |
holder_key_mismatch |
| 11 | La firma de device authentication valida contra el session transcript | holder_key_mismatch, device_mac_unsupported, unsupported_device_auth_alg |
| 12 | El estado on-chain no figura como revocado ni suspendido | credential_revoked, credential_suspended, status_check_failed |
| 13 | La consulta DCQL se satisface: docType y cada elemento solicitado | doctype_mismatch, missing_required_claim:<ns>.<el>, format_mismatch:<formato> |
Dos comprobaciones no existen en SD-JWT:
- Paso 4: el docType firmado tiene que coincidir con el del documento. Impide, por ejemplo, presentar como licencia de conducir una credencial emitida como atestación de edad.
- Paso 7: la dirección del emisor guardada en la credencial tiene que coincidir con la resuelta. Impide que un workspace con certificado emita credenciales a nombre de otro.
La ruta del certificado (x5chain) es la de los mDL con docType ISO; habilitarla
requiere un trámite, descrito en Habilitar mDL ISO.
Errores al crear la sesión
| HTTP | error |
Causa |
|---|---|---|
| 400 | invalid_dcql_query |
Falta credentials, o está vacío. |
| 400 | unsupported_dcql_format |
Un format distinto de mso_mdoc, vc+sd-jwt o dc+sd-jwt. |
| 400 | invalid_mdoc_claim_path |
Un path de mso_mdoc que no es exactamente de dos cadenas. |
| 400 | mixed_dcql_formats |
La consulta combina mDoc con SD-JWT. Usá dos sesiones. |
| 401 | invalid_api_key |
API key ausente o inválida. |
| 403 | workspace_inactive |
Workspace u organización inactivos. |
| 409 | workspace_not_provisioned |
El aprovisionamiento todavía no terminó. |
La tabla completa y los errores de presentación están en Errores de verificación.
Ejemplo completo en Node.js
const BASE_URL = process.env.BASE_URL;
const API_KEY = process.env.SOVRA_API_KEY;
const MDL_DOCTYPE = "org.iso.18013.5.1.mDL";
const MDL_NS = "org.iso.18013.5.1"; // atención: el namespace NO es el docType
/** Pide únicamente la atestación de edad: ni nombre ni fecha de nacimiento. */
async function pedirControlDeEdad() {
const res = await fetch(`${BASE_URL}/api/v1/verifier/verifications`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
dcql_query: {
credentials: [
{
id: "edad",
format: "mso_mdoc",
meta: { doctype_value: MDL_DOCTYPE },
claims: [{ path: [MDL_NS, "age_over_18"] }],
},
],
},
}),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error);
// La variante `_ref` mantiene el QR compacto sin importar el tamaño del DCQL.
return { sessionId: body.session_id, qr: body.authorization_request_uri_ref };
}
/** Las claves del resultado vienen cualificadas por namespace. */
function leerClaim(credencial, namespace, elemento) {
return credencial.claims[`${namespace}.${elemento}`];
}
app.post("/webhooks/sovra", verificarFirmaHmac, (req, res) => {
const { event, data } = req.body;
if (event === "presentation.verified") {
const lic = data.credentials.find((c) => c.id === "edad");
const mayor = leerClaim(lic, MDL_NS, "age_over_18");
resolverSesion(data.verification_id, { mayor });
}
if (event === "presentation.failed") {
// `error` identifica con precisión la comprobación que se cortó.
rechazarSesion(data.verification_id, data.error);
}
res.sendStatus(200);
});Con un namespace propio, cambiá MDL_DOCTYPE por el docType del esquema y MDL_NS
por su namespace (por ejemplo mx.gob.nl.icv.1), leyendo ambos del esquema.