Referencia técnica

El detalle contractual de los cuatro endpoints que tu aplicación llama directamente: códigos de respuesta, casos de error, límites de tasa. Para el esquema exacto, consultable y siempre actualizado, la documentación Swagger está disponible en todis.eu/es/docs, sin necesidad de token.

Autenticación y límites de tasa

Todas las rutas de verificación requieren la cabecera Authorization: Bearer <token>. Un token ausente, inválido, revocado o caducado devuelve 401. Superado el límite de tu plan (30 peticiones/segundo en Starter, 60 en Standard), una petición devuelve 429.

Quién decide qué información se divulga

Cada atributo de una presentación SD-JWT VC (la edad, un título, un estado) está protegido por su propio digest salado en el JWT firmado. La cartera solo adjunta a su presentación el valor y el salt de los atributos que el usuario ha aceptado revelar: el resto permanece como una huella irreversible. Todis solo tiene acceso técnicamente a lo que realmente se divulga en la presentación que recibe, nunca más.

Con POST /verify/sessions, el campo claims de tu solicitud se convierte en una consulta DCQL integrada en la solicitud de autorización enviada a la cartera: el usuario ve y aprueba exactamente esa lista antes de que su cartera construya la presentación. Con POST /verify/sd-jwt-vc, ese paso ya ha ocurrido antes de que obtengas la presentación: Todis la verifica y te devuelve su contenido tal cual.

POST /verify/sd-jwt-vc

Verifica una presentación SD-JWT VC. Dos modos en el cuerpo de la petición: issuer_public_key_pem (clave del emisor indicada directamente) o country_code (resolución automática a través del registro oficial de la UE) ; issuer_public_key_pem tiene prioridad si ambos están presentes.

  • 200: presentación verificada, claims incluido.
  • 400: no se indicó ni issuer_public_key_pem ni country_code.
  • 401: token de licencia ausente, inválido, revocado o caducado.
  • 422: presentación malformada o firma no verificada (verified: false, detalle en error).
  • 429: cuota de peticiones del plan superada.
  • 502: resolución del registro de confianza del emisor imposible (solo en modo country_code, por ejemplo si el registro europeo no está disponible temporalmente).

POST /verify/mdoc

Verifica una presentación mdoc (ISO/IEC 18013-5, usada especialmente para el permiso de conducir móvil). El certificado de confianza del emisor (issuer_trust_anchor_pem) debe indicarse explícitamente en el cuerpo de la petición: todavía no hay resolución automática por país para este formato (contáctanos si te concierne un emisor mdoc concreto).

  • 200: presentación verificada, doc_type y namespaces incluidos.
  • 401: token de licencia ausente, inválido, revocado o caducado.
  • 422: presentación malformada, certificado de confianza incorrecto o firma no verificada.
  • 429: cuota de peticiones del plan superada.

POST /verify/sessions

Crea una sesión de verificación OpenID4VP. El cuerpo de la petición indica el tipo de credential solicitado (vct) y los atributos solicitados (claims, rutas simples, ej. "age_over_18"), con la misma elección issuer_public_key_pem/country_code que en la verificación directa. La respuesta contiene una solicitud de autorización OpenID4VP para presentar a la cartera del usuario (código QR o enlace directo). La sesión caduca 15 minutos después de su creación, haya recibido respuesta o no. 

curl -X POST https://verify.todis.eu/verify/sessions \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vct": "https://example.eu/credentials/pid",
    "claims": ["age_over_18"],
    "country_code": "FR"
  }'
  • 201: sesión creada, con session_id y authorization_request.
  • 400: claims vacío, o no se indicó ni issuer_public_key_pem ni country_code.
  • 401: token de licencia ausente, inválido, revocado o caducado.
  • 429: cuota de peticiones del plan superada.

GET /verify/sessions/{id}

Consulta el resultado de una sesión creada por POST /verify/sessions, a interrogar después de que el usuario haya respondido con su cartera (o periódicamente mientras se espera). 

curl https://verify.todis.eu/verify/sessions/<session_id> \
  -H "Authorization: Bearer TU_TOKEN"
  • 200: tres estados posibles, {"status": "pending"}, {"status": "verified", "claims": {...}} o {"status": "failed", "error": "..."}.
  • 401: token de licencia ausente, inválido, revocado o caducado.
  • 404: sesión desconocida (identificador inválido, o sesión caducada tras 15 minutos).
  • 429: cuota de peticiones del plan superada.

Formato de la respuesta (verificación directa)

Para /verify/sd-jwt-vc y /verify/mdoc: un booleano verified y, según el resultado, la información divulgada (claims para SD-JWT VC, doc_type/namespaces para mdoc) o un campo de texto error. Nunca el documento de identidad completo, solo los atributos realmente divulgados (ver arriba).

Para ir más allá

Para la visión general (autenticación, dos formas de integrar, un ejemplo con curl), consulta Cómo funciona la API. Para el esquema exacto de peticiones/respuestas, todis.eu/es/docs (Swagger). ¿Tienes una pregunta que no está aquí? contact@todis.eu.