Sellos de tiempo (TSA)¶

Permite administrar configuraciones de Time Stamp Authority (RFC 3161) usadas opcionalmente al firmar documentos (useTsa=true en /api/doc/sign-by-label o /api/doc/sign-by-coord). Todos los endpoints requieren token.

Las credenciales (user, pass) se guardan siempre cifradas (AES-GCM) en userEncrypted / passEncrypted.

Solo puede existir una configuración activa marcada isDefault = true a la vez: si se crea o actualiza otra con isDefault=true, las demás se desmarcan automáticamente (keepOnlyOneDefault / normalizeDefaults).

Endpoints¶

Base URL: /api/tsa

Método	Ruta	Body/Params	Descripción
POST	`/`	Body JSON: `alias`, `url`, `user`, `pass`, `isDefault?`	Crea una configuración TSA. Falla con `400` si el `alias` ya existe (activo) o la URL no es `http`/`https` válida con host.
GET	`/`	—	Lista las configuraciones TSA activas (`status = ACTIVE`), ordenadas por `updated` descendente.
GET	`/{alias}`	—	Obtiene una configuración TSA activa por alias. `404` si no existe.
PUT	`/{alias}`	Body JSON parcial: `url?`, `user?`, `pass?`, `isDefault?`	Actualiza solo los campos enviados.
DELETE	`/{alias}`	—	Elimina lógicamente (`status = DELETED`, `isDefault = false`).
POST	`/{alias}/validate`	—	Ejecuta una solicitud RFC 3161 real contra la TSA para verificar URL y credenciales; actualiza `lastValidatedAt`, `validationCount`, `lastValidationOk`.

Ejemplos¶

Crear configuración TSA¶

curl -X POST http://localhost:8080/api/tsa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "tsa-prd",
    "url": "https://tsa.proveedor.com/rfc3161",
    "user": "usuario_tsa",
    "pass": "clave_tsa",
    "isDefault": true
  }'

Respuesta 201 CREATED (TimeStampConfigResponse, sin credenciales):

{
  "id": 3,
  "alias": "tsa-prd",
  "url": "https://tsa.proveedor.com/rfc3161",
  "isDefault": true,
  "status": "ACTIVE",
  "lastValidatedAt": null,
  "validationCount": 0,
  "lastValidationOk": null,
  "created": "2026-07-14T10:00:00.000+00:00",
  "updated": "2026-07-14T10:00:00.000+00:00"
}

Listar configuraciones activas¶

curl http://localhost:8080/api/tsa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Actualizar¶

curl -X PUT http://localhost:8080/api/tsa/tsa-prd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "pass": "nueva_clave_tsa" }'

Eliminar (lógico)¶

curl -X DELETE http://localhost:8080/api/tsa/tsa-prd \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Validar¶

curl -X POST http://localhost:8080/api/tsa/tsa-prd/validate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Respuesta exitosa (200 OK):

{
  "status": "SUCCESS",
  "message": "TSA validated successfully.",
  "errorCode": "TSA_VALID",
  "alias": "tsa-prd",
  "validatedAt": "2026-02-11T15:20:35.100+00:00",
  "validationCount": 5,
  "lastValidationOk": true
}

Ejemplo de error (401 UNAUTHORIZED, credenciales inválidas):

{
  "status": "ERROR",
  "message": "Invalid TSA credentials.",
  "errorCode": "TSA_AUTH_FAILED",
  "alias": "tsa-prd",
  "validatedAt": "2026-02-11T15:21:01.512+00:00",
  "validationCount": 6,
  "lastValidationOk": false
}

Códigos de error de validación¶

`errorCode`	HTTP Status	Causa
`TSA_ALIAS_NOT_FOUND`	404	Alias no existe o fue eliminado
`TSA_URL_INVALID`	400	La URL no tiene esquema `http`/`https` o host válido
`TSA_AUTH_FAILED`	401	Credenciales rechazadas por la TSA (401/403)
`TSA_TIMEOUT`	408	Timeout contactando la TSA
`TSA_UNREACHABLE`	502	Host inalcanzable (DNS, conexión rechazada, etc.)
`TSA_EMPTY_RESPONSE`	502	La TSA respondió sin token de sello de tiempo
`TSA_VALIDATION_ERROR`	502	Cualquier otro error durante la solicitud RFC 3161
`TSA_CREATE_VALIDATION` / `TSA_UPDATE_VALIDATION`	400 (o 404 si "not found")	Error de validación al crear/actualizar
`TSA_CREATE_ERROR` / `TSA_UPDATE_ERROR`	500	Error inesperado al crear/actualizar

Ver un flujo completo (crear TSA, validarla y usarla al firmar) en Casos de uso: configurar y usar una TSA.