Viafirma
Guía Técnica
Detalle de secciones

1. Introducción

El presente documento pretende ser una guía que permita a los usuarios:

  • Instalar Signservices

  • Integrar sus aplicaciones

Nota: Esta documentación técnica está sujeta a modificaciones diarias, alguna información o configuración avanzada podría no estar reflejada.

1.1. Consumo de servicios en cloud

Para consumir los servicios en cloud en nuestros entorno de sandbox puede hacer uso de la URL https://sandbox.viafirma.com/signservices para lo que tienes que solicitar unas credenciales de acceso a tu comercial.

En la guía de integración se detallan los pasos a seguir para el consumo de los servicios.

2. Guia de instalación

El presente documento pretende ser una guía de instalación para el proyecto Viafirma SignServices.

La información va dirigida a perfiles técnicos y con solvencia en la instalación y despliegues de aplicaciones.

SignServices puede ser instalada en un cluster de kubernetes o en un servidor de aplicaciones Tomcat 10.X que haga uso de Java21.

2.1. Instalación en kubernetes

En los siguientes apartados se describen los pasos a seguir para desplegar SignServices en Kubernetes.

2.1.1. Solicita a tu comercial:

  • Licencia de uso de la aplicación.

  • Credenciales de acceso al registry de docker o imagen de docker de la aplicación.

  • Credenciales de acceso a nuestro repositorio de helm o el chart de helm de la versión que deseas instalar.

2.1.2. Preparar tu entorno de instalación

  • Configurar un secret con los datos de acceso al registry de docker que vas a utilizar.

  • Crea un bucket de S3 para almacenar los documentos firmados o prepara un PVC para persistir la información.

  • Prepara el dominio y certificado SSL para el acceso a la aplicación

2.1.3. Instalación desde el repositorio de helm

Para instalar SignServices empleando helm deben ejecutar el siguiente comando.

helm upgrade signservices viafirma/signservices -n signservices --install --values values.yaml --version 1.3.17-r65-89b66cb

2.1.4. Configuración del deployment

En el fichero values.yaml del chart de helm puedes configurar los siguientes valores respecto a la configuración del deployment:

## DEPLOY INGRESS
deployIngress: true
ingressHost: "sandbox.viafirma.com"
ingressPath: "/signservices"
ingressTlsSecret: "ssl-viafirma"

## DOCUMENTATION DEPLOYMENT (OPTIONAL)
deployDoc: false

## PULL SECRET
imagePullSecrets: "releases-viafirma"

## SIGNSERVICES DEPLOYMENT
signservicesPodMemory: "4095Mi"
signservicesPodCpu: "2000m"
signservicesReplicas: 2
signservicesTemporalStorageSize: "512Mi"
signservicesUseVolume: true
signservicesVolumeClaim: "signservices-pvc"

## REDIS DEPLOYMENT (OPTIONAL)
deployRedis: true
redisMaxMemory: "1024M"
redisPodMemory: "2048Mi"
redisPodCpu: "500m"
redisImage: "redis:7.2.4"

## SECRET WITH LICENSE FILE (OPTIONAL)
licenseSecret: "viafirma-license"

2.2. Instalación en Apache Tomcat 10 y Java 21

Añadir configuración de java y de la aplicación en el fichero setenv.sh en la carpeta /bin del Tomcat

fichero setenv.sh

#!/bin/sh

export VIAFIRMA_HOME="/viafirma/signservices-home"
export JAVA_OPTS="${JAVA_OPTS} \
  -Xms2g \
  -Xmx4g \
  -XX:MetaspaceSize=512m \
  -XX:MaxMetaspaceSize=1g \
  -XX:+UseG1GC \
  -XX:InitiatingHeapOccupancyPercent=45 \
  -Djava.security.egd=file:/dev/./urandom \
  -Djava.awt.headless=true \
  -Djava.io.tmpdir=/tmp \
  -Dfile.encoding=UTF-8 \
  -Dspring.config.location=${VIAFIRMA_HOME}/application.properties \
  -Dlogging.config=${VIAFIRMA_HOME}/logback.xml"

Posteriormente se tienen que configurar el fichero application.properties con las propiedades de configuración de la aplicación y el fichero logback.xml con la configuración de logs de la aplicación

Ejemplo de application.properties

server.servlet.context-path=/signservices
server.port=7088
serverName=Viafirma

publicServiceURL=http://127.0.0.1:8080/signservices

caSupportEnabled=true
caSupportSubscriptions=/prod

storage.type=disk
viafirmaHomePath=/home/viafirma/viafirma-storage

defaultTsaURL=https://tsa.viafirma.com/viafirma-tsa/tsa
defaultTsaUser=XXX
defaultTsaPassword=XXX

fortress.enabled=true
fortress.serviceUrl=https://fortress.viafirma.com/fortress
fortress.clientId=XXX
fortress.clientSecret=XXX

CREDENTIALS=put_your_user/put_your_password

Ejemplo de logback.xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

	<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
		<encoder>
			<Pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern>
		</encoder>
	</appender>

	<logger name="com.viafirma.core.api.stats" level="DEBUG" />

	<root level="INFO">
		<appender-ref ref="STDOUT" />
	</root>

</configuration>

Una vez configurados los anteriores ficheros puede arrancar el servidor de aplicaciones Tomcat y comenzar a usar los servicios de la aplicación.

2.3. Configuración del servicio

Pueden configurar el servicio haciendo uso de las variables de entorno del deployment, estas mismas propiedades pueden ser usadas en un fichero signservices.properties que puedes montar en el contenedor.

Sí tienes problemas con los '.' en los nombres de las variables de entorno puedes usar '_' en su lugar.

2.3.1. Parámetros de configuración de acceso al servicio

Clave Valor por defecto Description

publicServiceURL

URL de acceso a los servicios públicos de la aplicación, por ejemplo https://sandbox.viafirma.com/signservices

CREDENTIALS

Lista de credenciales de acceso a los servicios, separados por ',' cada credencial se compone de un par de valores separados por '/', el primero es el usuario y el segundo la contraseña. Que se usará para la autenticación básica de los servicios consumidos desde otro servidor (nunca directamente desde un entorno web). Por ejemplo: key001/secrect001,key002/secrect002

2.3.2. Configuración de la TSA

Para configurar una TSA por defecto en la plataforma, será necesario que se indiquen en el fichero de propiedades los siguientes campos:

Clave Valor por defecto Description

defaultTsaURL

URL de acceso a la TSA. Por ejemplo https://tsa.viafirma.com/viafirma-tsa/tsa

defaultTsaUser

Usuario de acceso a la TSA

defaultTsaPassword

Contraseña de acceso a la TSA

defaultTsaCertificateAlias

Alias del certificado de acceso a la TSA

defaultTsaCertificatePassword

Contraseña del certificado de acceso a la TSA

defaultTsaUseTls

false

Setea si la conexión con la TSA se hace usando TLS. Posibles valores true o false.

defaultTsaPolicyOid

Policy OID por defecto de la TSA (Opcional)

defaultTsaExtensionOid

OID a informar con un valor específico, por ejemplo 1.3.4.6.1.3.4.6 (Opcional)

defaultTsaExtensionValue

Valor del OID especificado en el parámetro anterior defaultTsaExtensionOid (Opcional)

Siempre y cuando se haya configurado la TSA por defecto y no se haya configurado la TSA en la aplicación, se empleará en firmas de los siguientes tipos:

  • CADES_T

  • CADES_LT

  • CADES_LTA

  • PADES_T

  • PADES_LT

  • PADES_LTA

  • XADES_T

  • XADES_LT

  • XADES_LTA

2.3.3. Configuración del sistema de persistencia de información

SingService permite configurar la persistencia en S3 o en Sistema de ficheros.

Los parámetros de configuración a emplear son;

Clave Valor por defecto Description

viafirmaHomePath

/viafirma/signservices

Ruta de acceso al directorio de trabajo de la aplicación

storage.type

disk

Tipo de almacenamiento de la información, puede ser 'disk' o 's3'

La configuración del bucket de S3 solo serán necesarios si 'storage.type' es igual a 's3'.

Clave

Valor por defecto

Description

s3BucketName

Nombre del bucket de S3 donde se almacenarán los documentos firmados

s3BucketRegion

Región del bucket de S3

s3EndPoint

URL de acceso al servicio de S3 por ejemplo: https://s3.eu-west-1.amazonaws.com

s3ApiKey

Clave de acceso al servicio de S3

s3SecretKey

Contraseña de acceso al servicio de S3

La configuración de redis para la persistencia temporal de información.

Clave

Valor por defecto

Description

redisTtl

Valor en minutos que se mantendrá la información en redis

spring.data.redis.host

Host de acceso al servicio de redis en un solo nodo

spring.data.redis.port

Puerto de acceso al servicio de redis en un solo nodo

spring.data.redis.username

Usuario de acceso al servicio de redis en un solo nodo

spring.data.redis.password

Contraseña de acceso al servicio de redis en un solo nodo

spring.data.redis.sentinel.master

Nombre del nodo maestro en el servicio de redis

spring.data.redis.sentinel.nodes

Lista de pares host:port separados por coma 127.0.0.1:26379,127.0.0.1:26380

spring.data.redis.sentinel.username

El nombre de usuario que se aplicará al autenticarse con Redis Sentinel (requiere Redis 6)

spring.data.redis.sentinel.password

La contraseña a aplicar al autenticarse con Redis Sentinel

spring.data.redis.cluster.nodes

Lista delimitada por comas de pares de host:port

spring.data.redis.cluster.max-redirects

Número de redirecciones de clúster permitidas

2.3.4. Configuración del servicio de auditoría

SingService permite configurar el servicio de auditoria, informando los siguientes propiedades:

Clave Valor por defecto Description

trail.enabled

false

Habilita el servicio de auditoría: true / false

trail.serviceUrl

URL de acceso al servicio de auditoría: https://sandbox.viafirma.com/trail/rest

trail.clientId

Identificador de la aplicación en el servicio de auditoría

trail.clientSecret

Clave de acceso al servicio de auditoría

2.3.5. Configuración del servicio de certificados cloud

SingService permite configurar el servicio de certificados cloud. Los parámetros de configuración a emplear son:

Clave Valor por defecto Description

fortress.enabled

false

Habilita el servicio de certificados cloud de viafirma: true / false

fortress.serviceUrl

URL de acceso al servicio de certificados cloud de viafirma: https://sandbox.viafirma.com/fortress

fortress.clientId

Identificador de la aplicación en el servicio de certificados cloud de viafirma

fortress.clientSecret

Clave de acceso al servicio de certificados cloud de viafirma

2.3.6. Servicio de recolección de estadísticas de uso

SingService permite configurar el servicio de recolección de estadísticas de uso. Los parámetros de configuración a emplear son:

Clave Valor por defecto Description

collect.enabled

false

Habilita el servicio de recolección de estadísticas de uso: true / false

collect.serverUrl

URL de acceso al servicio de recolección de estadísticas: https://collect-live.viafirma.com

collect.defaultApplication

Identificador de la aplicación en el servicio de recolección de estadísticas: SIGNSERVICES_XXXXXX

collect.apiUser

Clave de acceso al servicio de recolección de estadísticas

collect.apiPassword

Contraseña de acceso al servicio de recolección de estadísticas

collect.unsentFolderPath

Carpeta donde se almacenarán los ficheros de estadísticas que no se han podido enviar

2.3.7. Configuración de la base de datos para las firmas

A continuación, se describen los parámetros a agregar para configurar la base de datos que almacenará información de las firmas realizadas.

Clave Valor por defecto Description

database.enabled

false

Propiedad personalizada que habilita o deshabilita la persistencia en base de datos. Si es false, la aplicación funcionará sin las funcionalidades que requieran base de datos.

development.data.loader.enabled

false

Habilita la carga de datos iniciales o de prueba al arrancar la aplicación. Debe estar deshabilitado (false) en entornos productivos.

spring.datasource.driverClassName

Clase del driver JDBC para la conexión. Spring Boot normalmente lo autodetecta a partir de la URL, por lo que no suele ser necesario especificarlo.

spring.datasource.url

(Requerido). URL de conexión JDBC a la base de datos. Formato: jdbc:postgresql://<host>:<puerto>/<nombre_bd>.

spring.datasource.username

(Requerido). Nombre de usuario para la conexión a la base de datos.

spring.datasource.password

(Requerido). Contraseña del usuario para la conexión a la base de datos.

2.3.8. Configuración del archivado de firmas

Estos parámetros controlan el comportamiento del archivado histórico de las firmas en la base de datos.

Clave Valor por defecto Descripción

archive.enabled

false

Habilita o deshabilita la función de archivado de firmas. Valores: true / false.

2.3.9. Configuración de la caducidad y custodia de firmas

Estos parámetros controlan la gestión del ciclo de vida de las firmas almacenadas en la base de datos.

Clave Valor por defecto Descripción

signature.expirationDays

365

Define el número de días, tras los cuales la firma se considerará caducada.

signature.custodyDays

60

Define el periodo de custodia en días para una firma archivada, contado desde el momento en que se almacena en el archivo.

2.3.10. Configuración de Tareas de refirmado

A continuación, se describen los parámetros para configurar las tareas programadas (jobs) que procesan las firmas caducadas o que requieren una promoción de formato.

Clave Valor por defecto Description

job.esxpiredEnabled

false

Habilita o deshabilita la tarea de refirmado para firmas caducadas. Valores: true / false.

job.expiredSchedule

Expresión Cron que define la frecuencia de ejecución de la tarea para las firmas caducadas. Ejemplo: 0 0 * * * * (cada hora).

job.expiredLimit

100

Número máximo de firmas caducadas que se procesarán en cada ejecución de la tarea.

job.expiredDays

1

Define un umbral (en días) para seleccionar firmas próximas a caducar. Por ejemplo, un valor de 1 procesará las firmas que expiren en el día.

job.formatEnabled

false

Habilita o deshabilita la tarea de refirmado para firmas con formato inadecuado. Valores: true / false.

job.formatSchedule

Expresión Cron que define la frecuencia de ejecución para las firmas con formato inadecuado. Ejemplo: 0 0 * * * * (cada hora).

job.formatExcludedFormats

Lista de los formatos que si se consideran correctos Ejemplo: CADES_LTA,PADES_LTA,XADES_LTA.

job.formatLimit

100

Número máximo de firmas no excluídas por formato (ver parámetro job.formatExcludedFormats), que se procesarán en cada ejecución de la tarea.

job.apiKey

Clave de acceso al servicio de las tareas de refirmado.

job.apiPass

Contraseña de acceso al servicio de las tareas de refirmado.

job.apiUrl

URL de acceso a los servicios públicos de la aplicación, por ejemplo https://sandbox.viafirma.com/signservices

2.3.11. Configuración del almacén de certificados local

A continuación, se indican los parámetros a agregar a la configuración para configurar un almacén de certificados local.

Clave Valor por defecto Description

keystoreFileName

cacerts.jks

Nombre del fichero almacén de claves local

keystorePassword

changeit

Clave del almacén de claves local

certificateAlias

alias del certificado de firma de documentos por defecto

certificatePassword

contraseña del certificado de firma de documentos por defecto

cypherCertificateAlias

alias del certificado de cifrado de datos biométricos

2.3.12. Configuración de la validación de certificados

Signservices permite configurar los mecanismos empleados para la validación de certificados:

Clave Valor por defecto Description

revocationRequestType

ONLINE_WITH_CACHE

Permie realizar la validación de los certificados intervinientes en la firma de documentos, siguiendo una de las siguientes estrategias:

- DEFAULT: Se utilizará el sistema de validación definido en el sistema de soporte de certificados.
- ONLINE: Para validar el estado de revocación de cada certificado se accede a la fuente de validación disponible preferente por OCSP.
- ONLINE_WITH_CACHE: Para validar el estado de revocación de cada certificado se accede a la fuente de validación disponible preferente por OCSP, pero utilizando caché de CRL, se utilizará la crl ya descargada siempre que esta sea válida.
- CRL: Se valida el estado de revocación consultando las listas de revocación de certificados CRL, siempre se descarga la CRL, no se utiliza cache. Si no puede consultar el estado de revocación mediante CRL se producirá un error.
- CRL_CACHE: Se valida el estado de revocación consultando las listas de revocación de certificados CRL, utilizando caché de CRL, se utilizará la crl ya descargada siempre que esta sea válida.
- OCSP: Se valida el estado de revocación del certificado haciendo uso del protocolo OCSP. Si no se puede consultar el estado de revocación se producirá un error.

caSupportEnabled

true

Habilita el uso del servicio de confianza de certificados de viafirma

caSupportSubscriptions

Lista de suscripciones al servicio de confianza de certificados de viafirma por ejemplo: /prod/eu/es,/test/eu/pt

2.3.13. Metadatos utilizados en las operaciones de firma

Signservices permite configurar un conjunto de Metadatos por defecto a incluir al realizar firmas, estos son:

Clave Valor por defecto Description

country

España

País

postalCode

41940

Código Postal

stateOrProvince

Sevilla

Estado/provincia

city

Tomares

Ciudad

3. Guía de integración

Los siguientes apartados describen como realizar la integración entre sistemas clientes y SignServices.

Requisitos

Cualquier sistema cliente que quiera integrarse con Signservices debe estar dado de alta y disponer de un api_user y un api_password proporcionado por el departamento comenrcial, que se utilizarán durante la integración.

En caso de interactuar con la plataforma, sin indicar unas credenciales válidas la plataforma devolverá un error controlado, indicando que no está autorizado.

{
"timestamp": 1728560102625,
"status": 401,
"error": "Unauthorized",
"path": "/signservices/api/{{request_path}}"
}

3.1. Autenticación de usuarios

A continuación, se describen los servicios que permiten autenticar a un usuario o consultar el estado de una autenticación

3.1.1. Solicitud de autenticación de usuarios.

Método que permite autenticar al usuario en SignServices.

Uso del servicio

Para autenticar al usuario deben emplear el siguiente servicio.

POST /api/client/auth/request

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Parámetros del servicio

Este servicio recibe por parámetros al menos el callbackURL donde el servicio devolverá el token JWT.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

Parámetros de solicitud simple
{
    "callbackURL": "https://webhook.site/9043980d-e457-4a9f-9228-79486fdc6a28"
}

Donde :

Campo

Descripción

callbackURL

URL donde se proporcionará la respuesta del servicio
Parámetros de solicitud con filtro de certificados
{
    "callbackURL": "https://webhook.site/9043980d-e457-4a9f-9228-79486fdc6a28",
    "callbackAuthorization": "Bearer 28dee3fe-a47a-4d11-88a1-87acfb1f2746",
    "certificateFilter": {
        "autoSend": true,
        "certFilter": {
            "operator": "contains",
            "filterValues": [
                "CALERO"
            ]
        },
        "caFilter": {
            "operator": "contains",
            "filterValues": [
                "FNMT"
            ]
        },
        "nationalIdFilter": {
            "operator": "contains",
            "filterValues": [
                "47000000Y"
            ]
        }
    }
}

Campo

Descripción

callbackURL

URL donde se proporcionará la respuesta del servicio

callbackAuthorization

Código de autorización devuelto. Este valor se añade en las cabeceras (headers) de la llamada de callback bajo la clave Authorization.

certificateFilter

Filtro de certificado a aplicar
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "code": "eyJ0eXAiO...",
    "expires": 1728016712631,
    "clientAccess": {
        "desktopProtocol": "viafirmawpfclient://?url=https://ci.viafirma.com/signservices&operationId=eyJ0eXAiO...",
        "fortressLink": "https://ci.viafirma.com/fortress/oauth2/v1/auth?scope=signatures&client_id=com.viafirma.signservices.ci&redirect_uri=https://ci.viafirma.com/signservices/api/fortress/callback/eyJ0eXAiO..."
    }
}

Donde :

Campo Descripción

code

Código de la operación.

expires

Fecha de expiración del token

clientAccess.desktopProtocol

URL para abrir por protocolo la autenticación con Viafirma Desktop

clientAccess.fortressLink

URL para poder autenticar con Viafirma Fortress

3.1.2. Consulta del estado de autenticación de usuarios.

Método que permite consulta del estado de autenticación de un usuario en SignServices.

Uso del servicio

Para obtener el estado de la autenticación del usuario se debe invocar al siguiente servicio.

GET /api/client/auth/status/{{code}}

El parámetro {{code}}, se corresponde con el campo code devuelto al llamar al servicio anterior para autenticar al usuario

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "type": "AUTHENTICATION",
    "certificate": {
        "numberUserId": "47000000Y",
        "name": "JESUS",
        "surname1": "LOPEZ",
        "surname2": "CALERO",
        "ca": "CN=AC FNMT Usuarios, OU=Ceres, O=FNMT-RCM, C=ES",
        "type": "X.509",
        "cn": "CN=LOPEZ CALERO MANUEL JESUS - 47000000Y, SURNAME=LOPEZ CALERO, GIVENNAME=JESUS, SERIALNUMBER=IDCES-47000000Y, C=ES",
        "isValidated": true,
        "isExpired": false,
        "isRevoked": false
    },
    "expires": 1728016712631,
    "requestCode": "eyJ0eXA...",
    "operationId": "1728016712631_32da3cb499a4433e",
    "callbackURL": "https://webhook.site/9043980d-e457-4a9f-9228-79486fdc6a28",
    "certificateFilter": {
        "autoSend": true,
        "discardExpiredCertificates": true,
        "certFilter": {
            "operator": "contains",
            "filterValues": [
                "CALERO"
            ]
        },
        "caFilter": {
            "operator": "contains",
            "filterValues": [
                "FNMT"
            ]
        },
        "nationalIdFilter": {
            "operator": "contains",
            "filterValues": [
                "47000000Y"
            ]
        }
    },
    "operations": [
        {
            "status": "FINISHED"
        }
    ],
    "randomStringToSignForAuth": "de5ee085-3e96-4f6d-a701-0ca80bc451b9",
    "signatureAlgorithm": "SHA256withRSA"
}

3.2. Firma en cliente

En los siguientes apartados se describen los diferentes métodos del API que permite realizar una firma desde un sistema cliente en SignService.

3.2.1. Solicitud de firma de documentos

Método del api que permite realizar una solciitud de firma de documentos.

Uso del servicio

Para solicitar una firma deben emplear el siguiente servicio

POST /api/client/signature/request

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Este servicio recibe por parámetros la configuración de la solicitud de firma empleada para el documento a firmar, donde se indica, entre otras cosas, el tipo de firma que se quiere realizar, la referencia al documento a firmar, en identificador del certificado centralizado a emplear.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

En los siguientes subapartados se muestra la información a incluir en el body para realizar diferentes tipos de operaciones:

Solicitud de firma con envío posterior de documentos

Mínima información a informar en los parámetros, no se proporciona información ni de los documentos a firmar, ni de la modalidad de firma.

{
    "count": 1,
    "callbackURL": "{{callbackURL}}",
    "archiveEnabled": true
}

Donde :

Campo

Descripción

count

Número de documentos a firmar

callbackURL

URL donde se proporcionará la respuesta del servicio

archiveEnabled

Indica si la información de la firma debe ser archivada en la base de datos. Valores: true / false. (Opcional, por defecto es false).
Solicitud añadiendo documentos y configuración (pocos documentos en una sola petición)

Parámetros a incluir en una solicitud de firma de documentos.

{
    "count": 1,
    "callbackURL": "{{callbackURL}}",
    "archiveEnabled": true,
    "signatures": [
        {
            "file": "{{reference}}",
            "fileName": "{{$randomUUID}}.pdf",
            "sourceId": "test_{{$randomUUID}}",
            "configuration": {
                "signatureType": "PADES_B",
                "packaging": "ENVELOPED",
                "signatureReason": "integration test"
            }
        }
    ]
}

Donde :

Campo

Descripción

count

Número de documentos a firmar

callbackURL

URL donde se proporcionará la respuesta del servicio

archiveEnabled

Indica si la información de la firma debe ser archivada en la base de datos. Valores: true / false. (Opcional, por defecto es false).

signatures.file

URL del documento a firmar o referencia del documento subido previamente a la plataforma

signatures.fileName

Nombre del documento

signatures.sourceId

Referencia asociada al documento

signatures.configuration.signatureType

Política de firma a emplear. (Para más información puede consultar la sección Políticas de firma)

signatures.configuration.packaging

Envoltura de la firma. Valores disponibles:

- ENVELOPED
- ENVELOPING
- DETACHED

signatures.configuration.signatureReason

Razón a incluir en la firma
Solicitud de firma con filtro de certificados

Finalmente se muestra como filtrar los certificados que puede emplear el usuario para realizar la firma.

{
    "count": 5,
    "callbackURL": "{{callbackURL}}",
    "archiveEnabled": true,
    "certificateFilter": {
        "autoSend": true,
        "certFilter": {
            "operator": "contains",
            "filterValues": [
                "CALERO"
            ]
        },
        "caFilter": {
            "operator": "contains",
            "filterValues": [
                "FNMT"
            ]
        },
        "nationalIdFilter": {
            "operator": "contains",
            "filterValues": [
                "47000000Y"
            ]
        }
    }
}

Campo

Descripción

count

Número de documentos a firmar.

callbackURL

URL donde se proporcionará la respuesta del servicio.

archiveEnabled

Indica si la información de la firma debe ser archivada en la base de datos. Valores: true / false. (Opcional, por defecto es false).

certificateFilter

Filtro de certificado a aplicar.
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "code": "eyJ0eXAiO....",
    "count": 1,
    "expires": 1728440171250,
    "clientAccess": {
        "desktopProtocol": "viafirmawpfclient://?url=https://ci.viafirma.com/signservices&operationId=eyJ0eXAiO....&isParallel=true",
        "link": "https://ci.viafirma.com/sign-page/operation/eyJ0eXAiOi...",
        "fortressLink": "https://ci.viafirma.com/fortress/oauth2/v1/auth?scope=signatures&client_id=com.viafirma.signservices.ci&redirect_uri=https://ci.viafirma.com/signservices/api/fortress/callback/eyJ0eXAiO...."
    }
}

Campo

Descripción

code

Código de la operación.

count

Número de documentos a firmar

expires

Fecha de expiración del token

clientAccess.desktopProtocol

URL para abrir por protocolo la autenticación con Viafirma Desktop

clientAccess.link

URL con el enlace a la página de firma

clientAccess.fortressLink

Url para poder autenticar con Viafirma Fortress

3.2.2. Envío de documentos para firmar a una solicitud ya creada

Para añadir cada documento a la solicitud de firma, es necesario emplear el siguiente método.

Solicitud de firma con envío posterior de documentos

Servicio a emplear para agregar configuración y/o documentos a una solicitud de firma.

POST /api/client/signature/add/config

Este servicio recibe por parámetros la configuración de la firma empleada para el documento a firmar, donde se indica, entre otras cosas, el tipo de firma que se quiere realizar, la referencia al documento a firmar.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
  "file" : "{{reference}}",
  "fileName" : "{{$randomUUID}}.pdf",
  "requestCode" : "{{code}}",
  "sourceId" : "demo_{{$randomUUID}}",
  "configuration" : {
    "signatureType" : "PADES_B",
    "packaging" : "ENVELOPED",
    "signatureReason" : "integration test"
  }
}
Campo Descripción

file

Referencia del documento subido a la plataforma.

fileName

Nombre del documento

code

Código de operación devuelto al realizar la solicitud de firma

sourceId

Identificador de la operación

configurations/signatureType

Política de firma a emplear. (Para más información puede consultar la sección Políticas de firma)

configurations/packaging

Envoltura de la firma. Valores disponibles: - ENVELOPED
- ENVELOPING
- DETACHED

configuration.signatureReason

Razón a incluir en la firma
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "signatureCode": "DCKR-DOAG-OF1O-....",
    "expires": 1728554647986
}
Campo Descripción

signatureCode

Código de firma.

expires

Fecha de expiración

3.2.3. Consulta del estado de una operación de firma de documentos

Servicio empleado para consultar el estado de una operación de firma.

GET /api/client/signature/status/{{jwt}}

Donde el parámetro {{jwt}}, se corresponde con el token JWT devuelto al llamar al servicio para consultar el estado de una operación de firma

Respuesta del consumo del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "totalCount": 1,
    "type": "SIGNATURE",
    "certificate": {
        "numberUserId": "47000000Y",
        "name": "MANUEL JESUS",
        "surname1": "LOPEZ",
        "surname2": "CALERO",
        "ca": "C=ES,O=FNMT-RCM,OU=Ceres,CN=AC FNMT Usuarios",
        "type": "X.509",
        "cn": "C=ES,SERIALNUMBER=IDCES-47000000Y,GIVENNAME=MANUEL JESUS,SURNAME=LOPEZ CALERO,CN=LOPEZ CALERO MANUEL JESUS - 47000000Y",
        "isValidated": true,
        "isExpired": false,
        "isRevoked": false
    },
    "expires": 1728440171250,
    "requestCode": "eyJ0eXAiOi...",
    "operationId": "1728440171250_a43856a5a11045aa",
    "callbackURL": "https://webhook.site/eb7b4ff4-a036-49d1-b6b5-3cc006ef429d",
    "operations": [
        {
            "documentId": "SCKR-DOAG-OF1O...",
            "status": "FINISHED",
            "signedLink": "https://ci.viafirma.com/signservices/d/SCKR-DOAG-OF1O...",
            "fileName": "833860cc-ad5e-4b9a-b7d1-381af8cfa722.pdf",
            "sourceId": "postman_test_d3be9428-12da-4715-b7a3-b45aa983370b"
        }
    ]
}

3.2.4. Forzar la finalización de una solicitud de documentos

Servicio empleado para forzar la finalización de una solicitud de firma en la que no se han enviado todos los documents a firmar.

POST /api/client/signature/force/finish/{{jwt}}

Donde el parámetro {{jwt}}, se corresponde con el token JWT devuelto al llamar al servicio para consultar el estado de una operación de firma

Respuesta del consumo del servicio
{
    "current": 1,
    "total": 5
}

3.2.5. Rechazar una solicitud de firma

Servicio empleado para rechazar una solicitud de firma, de la que eliminaremos todos los documentos asociados.

POST /api/client/signature/reject/{{jwt}}

Puede recibir de forma opcional un parámetro 'reason' como form param con el motivo del rechazo.

Donde el parámetro {{jwt}}, se corresponde con el token JWT devuelto al llamar al servicio para consultar el estado de una operación de firma

Respuesta del consumo del servicio
{
    "totalCount": 2,
    "type": "SIGNATURE",
    "expires": 1733358256779,
    "requestCode": "eyJ0eXAi...",
    "operationId": "1733358...",
    "operations": [
        {
            "documentId": "NCKR-DOAG-...",
            "status": "REJECTED",
            "statusReason": "document not found",
            "fileName": "d72418a9-8fae.pdf",
            "sourceId": "3a8a32c-6eb2-4119-a246-db5d5025e5ba"
        },
        {
            "documentId": "WCKR-DOAG-OF1O-TK86-2173-3333-0618-64",
            "status": "REJECTED",
            "statusReason": "document not found",
            "fileName": "1fabbe12-4141-4526-9a0a-35d50a99fe37.pdf",
            "sourceId": "postman_test_a3a4ebf5-8a99-4568-8c59-c0a0b3e37326"
        }
    ]
}

3.3. Firma en servidor

En los siguientes apartados se describe el método del API que permite realizar una firma en servidor desde un sistema cliente con SignService.

3.3.1. Firma en servidor con certificado centralizado

Método del API que permite realizar una firma desatendida en SignService empleando un certificado centralizado

Uso del servicio

Para realizar una firma desatendida con certificado centralizado deben emplear el siguiente servicio

POST /api/sign

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Parámetros del servicio

Este servicio recibe por parámetros la configuración de la firma empleada para el documento a firmar, donde se indica, entre otras cosas, el tipo de firma que se quiere realizar, el documento a firmar, el identificador del certificado centralizado a emplear.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
    "file": "{{base64file}}",
    "certificateId": "{{certificateId}}",
    "archiveEnabled": true,
    "configuration": {
        "signatureType": "PADES_B",
        "packaging": "ENVELOPED",
        "operationId": "{{myExpReference}}-{{$randomInt}}"
        "tsa" : {
              "type" : "USER",
              "url" : "https://tsa.viafirma.com/viafirma-tsa/tsa",
              "user" : "VIAFIRMA",
              "password" : "**************************"
        }
    }
}

Donde :

Campo Descripción

file

Base64 del documento a firmar.

certificateId

Identificador del certificado centralizado

archiveEnabled

Indica si la información de la firma debe ser archivada en la base de datos. Valores: true / false. (Opcional, por defecto es false).

configurations/signatureType

Política de firma a emplear. (Para más información puede consultar la sección Políticas de firma)

configurations/packaging

Envoltura de la firma. Valores disponibles:

- ENVELOPED
- ENVELOPING
- DETACHED

configurations/operationId

Identificador de la operación

configurations/tsa

Opcional. Datos de configuración de TSA propia (URL, credenciales, etc)
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "operationCode": "1728445211865_bbf6f5db0a954e1c",
    "signedFile": "JVBERi0xLjM...",
    "signatureCode": "TCKR-DOAG-OF1O..."
}

Donde:

Campo Descripción

operationCode

Código interno de operación.

signedFile

Documento firmado en formato base64

signatureCode

Identificador de firma

3.4. Firma en servidor de resúmenes (hash o digest)

La firma en servidor de resúmenes de archivos, conocidos como hashes o digest, se utiliza cuando el documento a firmar es demasiado grande para viajar por la red. En este caso se calcula su hash o digest y es este el que se envía a firmar.

La configuración es idéntica a la de una firma en servidor tradicional, solamente que se añaden parámetros para especificar que lo que se va a firmar es un hash y el algoritmo utilizado para la creación de dicho hash

Dado que se trata de firmas de archivos grandes, el tipo o envoltura de la firma debe ser obligatoriamente DETACHED, con el fin de luego poder validar que el documento original se corresponde con el hash firmado.

Este tipo de firma solamente se encuentra disponible para las firmas XAdES.

3.4.1. Parámetros del servicio

Este servicio recibe por parámetros la configuración de la firma empleada para el documento a firmar, donde se indica, entre otras cosas, el tipo de firma que se quiere realizar, el hash a firmar, el identificador del certificado centralizado a emplear.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
    "file": "{{base64file}}",
    "certificateId": "{{certificateId}}",
    "configuration": {
        "signatureType": "XADES_LT",
        "signatureAlgorithm" : "RSA_SHA256",
        "packaging": "DETACHED",
        "xadesConfig" : {
              "hashSignature" : true,
              "hashDigestAlgorithm" : "SHA256"
        },
        "operationId": "{{myExpReference}}-{{$randomInt}}"
    }
}

Donde :

Campo Descripción

file

Base64 del documento a firmar.

certificateId

Identificador del certificado centralizado

configurations/signatureType

Política de firma a emplear. (Para más información puede consultar la sección Políticas de firma)

configurations/packaging

Envoltura de la firma. Valores disponibles:

- DETACHED

configurations/xadesConfig/hashSignature

Configuración específica para firmas XAdES. Si el valor de hashSignature es true estamos informando que queremos firmas un hash

configurations/xadesConfig/hashDigestAlgorithm

Configuración específica para firmas XAdES. Si el valor de hashSignature es true, debemos informar el algoritmo con el que se ha generado el hash o digest

configurations/operationId

Identificador de la operación

3.4.2. Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "operationCode": "1728445211865_bbf6f5db0a954e1c",
    "signedFile": "JVBERi0xLjM...",
    "signatureCode": "TCKR-DOAG-OF1O..."
}

Donde:

Campo Descripción

operationCode

Código interno de operación.

signedFile

Documento firmado en formato base64

signatureCode

Identificador de firma

3.5. Promoción de firma

En los siguientes apartados se describe el método del API que permite realizar la promoción de una firma desde un sistema cliente con SignService.

3.5.1. Promoción de firmas

Método del API que permite realizar la promoción de una firma previa a formatos de firmas longevos con SignService

Uso del servicio

Para realizar una firma desatendida con certificado centralizado deben emplear el siguiente servicio

POST /api/sign/promote

En la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Parámetros del servicio

Este servicio recibe por parámetros, el documento con las firmas previas que se desea promocionar al formato de firma longevo, así como el formato de firma destino al que se desea promocionar el documento firmado.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
    "file": "{{base64signedFile}}",
    "original" : "PZC4gmR9fBUBZgm7U9...twrXnMel7Qh1tbiPeqsD2sIbY=",
    "targetSignatureType": "{{targetSignatureType}}",
    "hashSignature" : true
}

Donde :

Campo Descripción

file

Base64 del documento firmado a promocionar.

original

Aplica solamente para firmas DETACHED, para poder realizar la validación. Base64 con el contenido del documento original enviado a firmar. Para firmas DETACHED de hash, ver el parámetro hashSignature.

targetSignatureType

Formato de firma longevo al que se desea promocionar. Valores disponibles:

- PADES_LT
- PADES_LTA
- XADES_LT
- XADES_LTA
- XADES_LTA

hashSignature

Aplica solamente para firmas DETACHED, para poder realizar la validación. Especifica si se está enviando a promocionar la firma previa de un hash o digest. En este caso en el parámetro original se pasará solamente el Base64 del hash enviado a firmar, y no todo el documento original. Por defecto vale false.
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "promotedFileBase64": "JVBERi0xLjQKJfbk...",
}

Donde promotedFileBase64 es el base64 del documento con la promoción de la firma al formato escogido en la petición.

También es posible promocionar una firma previa conociendo su identificador de firma.

En este caso, no sería necesario pasar el parámetro file sino que el contenido del documento firmado a promocionar se obtendría a partir del identificador de firma.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
    "signatureCode" : "{{signatureCode}}",
    "original" : "PZC4gmR9fBUBZgm7U9...twrXnMel7Qh1tbiPeqsD2sIbY=",
    "targetSignatureType" : "{{targetSignatureType}}",
    "custodyStorage" : true,
    "hashSignature" : true
}

Donde :

Campo Descripción

signatureCode

Identificador de firma del documento firmado a promocionar. Tiene el siguiente formato: RCKR-DOAG-OF1O-TK9D-E174-6457-9938-12

original

Aplica solamente para firmas DETACHED, para poder realizar la validación. Base64 con el contenido del documento original enviado a firmar. Para firmas DETACHED de hash, ver el parámetro hashSignature.

custodyStorage

Especifica si se desea que se custodie físicamente el nuevo documento promocionado. Hay que tener en cuenta que en este caso se sobrescribirá el documento con la firma previa (enviada a promocionar) por el documento promocionado asociado al identificador de firma proporcionado. Por defecto vale false.

targetSignatureType

Formato de firma longevo al que se desea promocionar. Valores disponibles:

- PADES_LT
- PADES_LTA
- XADES_LT
- XADES_LTA
- XADES_LTA

hashSignature

Aplica solamente para firmas DETACHED, para poder realizar la validación. Especifica si se está enviando a promocionar la firma previa de un hash o digest. En este caso en el parámetro original se pasará solamente el Base64 del hash enviado a firmar, y no todo el documento original. Por defecto vale false.
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "promotedFileBase64": "JVBERi0xLjQKJfbk...",
    "signatureCode": "RCKR-DOAG-OF1O-TK9D-E174-6457-9938-12"
}

Donde promotedFileBase64 es el base64 del documento con la promoción de la firma al formato escogido en la petición y signatureCode es el identificador de firma del documento promocionado, el cual debe coincidir con el de la solicitud.

3.5.2. Promoción de Refirma por Identificador

Método del API que permite realizar la promoción de una firma a un formato longevo utilizando únicamente su identificador (signatureCode). El sistema se encarga de recuperar la firma existente, determinar el formato longevo apropiado y realizar la promoción de manera automática.

Uso del servicio

Para promocionar una firma existente a partir de su identificador, se debe emplear el siguiente servicio:

POST /api/sign/promote/resign

En la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Parámetros del servicio

Este servicio recibe como cuerpo de la petición (en formato text/plain) el identificador de la firma que se desea promocionar.

Ejemplo de petición
RCKR-DOAG-OF1O-TK9D-E174-6457-9938-12
Respuesta del servicio
{
  "operationCode": "1728445211865_bbf6f5db0a954e1c",
  "promotedFileBase64": "JVBERi0xLjQKJfbk...",
  "signatureCode": "RCKR-DOAG-OF1O-TK9D-E174-6457-9938-12"
}

Donde :

Campo Descripción

operationCode

Código interno de operación.

signatureCode

Identificador de firma del documento firmado a promocionar. Tiene el siguiente formato: RCKR-DOAG-OF1O-TK9D-E174-6457-9938-12

promotedFileBase64

Base64 del documento con la firma promocionada al formato longevo correspondiente.

3.6. Validación de firma

En los siguientes apartados se describen los diferentes métodos del API que permiten validar un documento firmado y certificados

3.6.1. Validación de documento firmado

Método que permite validar un documento firmado.

Uso del servicio

Para validar un documento firmado se debe emplear el siguiente servicio.

POST /api/validation

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Parámetros del servicio

Este servicio recibe por parámetros la referencia al documento firmado subido empleando el sevicio upload, o una URL accesible donde se encuentre publicado en documento firmado.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
   "showExtendedInfo" : true,
   "signedFile" : "{{reference}}"
}

Donde :

Campo Descripción

filename

Nombre del fichero firmado (Opcional).

showExtendedInfo

[true/false] variable indicada para mostrar o no la versión extendida.

signedFile

Referencia al documento firmado subido empleando el sevicio upload, o una URL accesible donde se encuentre publicado en documento firmado.

signatureCode

Opcional. Identificador de firma asociado al documento firmado. Si se especifica este parámetro y no se especifica el parámetro signedFile, se intenta validar el documento firmado y custodiado refferenciado por el identificador especificado. Si se especica el parámetro signedFile, se usa el mismo en vez del identificador de firma.
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
"operationCode": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.....",
"signatureValid": true,
"validationTime": 1728647715278,
"signaturesCount": 1,
"validSignaturesCount": 1
}

Donde :

Campo Descripción

operationCode

Código de la operación.

signatureValid

[true/false] Indica si la firma es válida o no

validationTime

Timestamp del momento en el que se realizó la validación

signaturesCount

Número de firmas en el documento

validSignaturesCount

Número de firmas válidas en el documento

Notas → Si se ha indicado el valor true en la propiedad showExtendedInfo, se devolverá la estructura con el detalle de la verificación de las firmas presentes en el documento.

3.6.2. Validación de documento firmado a través de su identificador de firma

De la misma forma es posible validar una firma previa únicamente conociendo su identificador

GET /api/validation/{{ID de firma}}

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Respuesta del servicio

La respuesta de este servicio es la misma que la del servicio de validación de firmas que se explica más arriba.

3.6.3. Validación de firmas de resúmenes (hash o digest)

Método que permite validar firmas de resúmenes (hash o digest) de archivos

Uso del servicio

Para validar validar firmas de resúmenes (hash o digest) de archivos se debe usar el siguiente servicio:

POST /api/validation/hash

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Parámetros del servicio

Este servicio recibe por parámetros la referencia al documento firmado subido empleando el sevicio upload, o una URL accesible donde se encuentre publicado en documento firmado. Si se desea validar una firma hash a través de su identificador de firma, sin tener que enviar el documento firmado, se debe utilizar el parámetro signatureCode en lugar de signedFile

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
   "showExtendedInfo" : true,
   "signedFile" : "{{reference}}",
   "originalContent" : "{{originalFileHash}}"
}

Donde :

Campo Descripción

filename

Nombre del fichero firmado (Opcional).

showExtendedInfo

[true/false] variable indicada para mostrar o no la versión extendida.

signedFile

Referencia al documento firmado subido empleando el sevicio upload, o una URL accesible donde se encuentre publicado en documento firmado.

signatureCode

Opcional. Identificador de firma asociado al documento firmado. Si se especifica este parámetro y no se especifica el parámetro signedFile, se intenta validar el documento firmado y custodiado refferenciado por el identificador especificado. Si se especica el parámetro signedFile, se usa el mismo en vez del identificador de firma.

originalContent

Es el Base64 del hash del archivo original enviado a firmar
Respuesta del servicio

La respuesta de este servicio es la misma que la del servicio de validación de firmas que se explica más arriba.

3.6.4. Validación de firmas de resúmenes (hash o digest) a través de su identificador de firma

De la misma forma es posible validar una firma hash previa únicamente conociendo su identificador

GET /api/validation/hash/{{ID de firma}}

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Respuesta del servicio

La respuesta de este servicio es la misma que la del servicio de validación de firmas que se explica más arriba.

3.6.5. Validación de firmas DETACHED

Método que permite validar firmas detached

Uso del servicio

Para validar validar firmas detached se debe usar el siguiente servicio:

POST /api/validation/detached

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Parámetros del servicio

Este servicio recibe por parámetros la referencia al documento firmado subido empleando el sevicio upload, o una URL accesible donde se encuentre publicado en documento firmado.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
   "showExtendedInfo" : true,
   "signedFile" : "{{reference}}",
   "filename" : "{{filename}}",
   "originalContent" : "{{originalFile}}"
}

Donde :

Campo Descripción

filename

Nombre del fichero firmado (Opcional).

showExtendedInfo

[true/false] variable indicada para mostrar o no la versión extendida.

signedFile

Referencia al documento firmado subido empleando el sevicio upload, o una URL accesible donde se encuentre publicado en documento firmado.

originalContent

Es el Base64 del archivo original enviado a firmar

referenceUri (Opcional)

Valor del atributo URI referenciada en el nodo ds:Signature de la firma XAdES a validar. Utilizada en la validación de firmas detached realizadas con Viafirma Platform.
Respuesta del servicio

La respuesta de este servicio es la misma que la del servicio de validación de firmas que se explica más arriba.

3.6.6. Validación de firmas DETACHED a través de su identificador de firma

De la misma forma es posible validar una firma DETACHED previa únicamente conociendo su identificador

GET /api/validation/detached/{{ID de firma}}

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial

Respuesta del servicio

La respuesta de este servicio es la misma que la del servicio de validación de firmas que se explica más arriba.

3.6.7. Validación de certificado

Método que permite validar un certificado

Uso del servicio

Para validar un certificado deben emplear el siguiente servicio.

POST /api/validation/certificate

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Parámetros del servicio

Este servicio recibe por parámetros el Base64 de la clave pública del certificado y el tipo de validación a emplear.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
    "certificateBase64" : "MIIG5zCCBM+gAwIBAgIIBtv/RzdZgzUwDQY...",
    "validationType": "CRL_CACHE"
}

Donde :

Campo Descripción

certificateBase64

Base64 de la clave pública del certificado a validar.

validationType

Tipo de validación a emplear:

- ONLINE
- ONLINE_WITH_CACHE
- CRL
- CRL_CACHE
- OCSP
- NONE
Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
"operationCode": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
"status": "EXPIRED"
}

Donde :

Campo Descripción

operationCode

Código de la operación.

status

Estado del certificado

3.7. Subida temporal de documentos

El proceso a realizar para enviar a SignService los documentos a firmar, está compuesto de dos pasos

  • Solicitar enlace de subida de archivo

  • Subir documento

En los siguientes apartados descibiremos las llamadas a realizar

3.7.1. Solicitar enlace de subida de archivo

Método que permite solicitar un código asociado a la solicitud de subida del documento.

Uso del servicio
GET /api/upload/request/link

Además en la cabecera HTTP de la petición, es necesesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas por el equipo comercial.

Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "code": "eyJ0eXAiOiJ...",
    "expires": 1728442812162
}

Donde :

Campo Descripción

code

Token JWT que permite securizar la subida del documento

expires

Fecha de expiración del token

3.7.2. Subida de documento

Puede subir el fichero en formato binario consumiendo el siguiente servicio.

POST /api/upload/file/{{jwt}}

Donde el parámetro {{jwt}}, se corresponde con el token JWT devuelto al llamar al servicio para solicitar enlace de subida de archivo

Parámetros del servicio

Este servicio recibe por parámetros el fichero temporal.

El fichero se debe proporcionar en formato multipart/form-data.

Respuesta de ejemplo

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

{
    "reference": "4f3ef206-0708-49ac-aa4b-e592f0c7da20_sample.pdf",
    "expires": 1728417612169
}

Donde :

Campo Descripción

reference

Referencia del documento subido a la plataforma.

expires

Fecha de expiración del token

3.8. Proceso de Firma Biométrica Avanzada

Métodos que permiten orquestar la captura de evidencias (firma biométrica, imágenes, etc.) desde una aplicación cliente hacia el servidor SignService.

3.8.1. Solicitud de captura de evidencia

Para iniciar un proceso de captura de evidencias se debe emplear el siguiente servicio. Este método prepara la operación y devuelve un token de sesión.

POST /api/client/evidence/request

Además en la cabecera HTTP de la petición, es necesario realizar una autenticación de tipo Básica, indicando las credenciales proporcionadas.

Parámetros del servicio

Este servicio recibe por parámetros la configuración de la operación, indicando cuántas evidencias se esperan, el tipo de evidencia y, opcionalmente, los documentos a firmar.

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
    "count": 1,
    "type": "SIGNATURE",
    "callbackURL": "https://mi-sistema.com/api/callback",
    "callbackRedirectURL": "https://mi-sistema.com/fin?token={{token}}",
    "callbackAuthorization": "Bearer eyJhbGciOi...",
    "trailEnabled": true,
    "documents": [
        {
            "document": "{{base64File}}",
            "operationId": "doc-ref-001"
        }
    ],
    "fortressConfiguration": {
        "serviceUrl": "https://sandbox.viafirma.com/fortress",
        "clientId": "mi_client_id",
        "clientSecret": "mi_client_secret",
        "certificateId": "CERT-001",
        "archiveEnabled": true
    },
    "configSignature": {
        "signatureType": "PADES_B",
        "signatureAlgorithm": "SHA256withRSA"
    }
}

A continuación se describen los campos del objeto principal PrepareEvidenceRequestDTO:

Campo Tipo Descripción

count

Integer

Número total de evidencias que se van a capturar en esta sesión. (Obligatorio).

type

String (Enum)

Tipo de evidencia a capturar. Valores posibles definidos en EvidenceType (ej. SIGNATURE, IMAGE, FINGERPRINT).

documents

List

Lista de objetos EvidenceDocumentDTO que contienen los archivos PDF sobre los que se realizará la adición de evidencias, en este paso son opcionales, se podran añadir en otro método.

callbackURL

String

URL donde se proporcionará la respuesta del servicio.

callbackRedirectURL

String

URL a la que se redirigirá al navegador del usuario final una vez termine el proceso.

callbackAuthorization

String

Valor que se enviará en la cabecera Authorization de la llamada al callbackURL. Útil si tu servidor requiere un Bearer token o Basic Auth para recibir la notificación.

trailEnabled

Boolean

Indica si se debe generar un documento de auditoría al finalizar el proceso. true para activarlo.

certificateAlias

String

Alias del certificado que se usará.

certificatePass

String

Contraseña del certificado especificado en certificateAlias.

certificateId

String

Identificador del certificado.

fortressConfiguration

Object

Objeto de configuración para la conexión con Viafirma Fortress (Firma Centralizada). Ver detalles en la tabla siguiente.

configSignature

Object

Configuración técnica de la firma electrónica resultante. Permite definir el formato (PADES_B, XADES, etc.), algoritmo y sellado de tiempo (TSA).

signatureRequest

Object

Objeto avanzado para configurar firma posterior a la adición de evidencias.
Documentos de Evidencia (EvidenceDocumentDTO)

Este objeto define cada uno de los documentos sobre los que se va a capturar la evidencia. Se envía dentro de la lista documents del objeto principal.

Campo Tipo Descripción

document

String (Base64)

Contenido binario del documento PDF codificado en Base64.

operationId

String

Identificador único o referencia externa para este documento.

password

String

Contraseña de apertura del documento PDF, en caso de que el archivo original esté protegido o encriptado.

positions

List<PositionDTO>

Lista de coordenadas donde se estampará la evidencia visual (firma, imagen, etc.) en el PDF. Define página, ejes X/Y y dimensiones.
Configuración de Fortress (FortressConfigurationDTO)

Si se desea utilizar firma centralizada o en la nube, se debe informar este objeto dentro de la petición principal.

Campo Tipo Descripción

serviceUrl

String

URL base del servicio de Fortress (ej. https://sandbox.viafirma.com/fortress).

serviceRedirectUri

String

URL de redirección configurada en el cliente OAuth de Fortress.

clientId

String

Identificador del cliente (Client ID) proporcionado por Fortress para la autenticación OAuth.

clientSecret

String

Clave secreta (Client Secret) proporcionada por Fortress.
Solicitud de Firma Avanzada (SignatureRequestDTO)

Este objeto permite una configuración granular y avanzada del proceso de firma posterior. Se utiliza cuando se requiere firmar el documento une vez realizada la adición de las evidencias.

Campo Tipo Descripción

file

String (Base64)

Contenido del archivo a firmar en Base64. (Nota: Generalmente redundante si ya se pasa el documento en la lista principal, pero útil en flujos de firma simple).

fileLink

String

URL pública o accesible desde el servidor para descargar el documento a firmar (alternativa a enviar el Base64 en file).

configuration

Object (ConfigSignatureDTO)

Configuración técnica específica de la firma (Formato PAdES/XAdES/CAdES, Algoritmo SHA1/SHA256, etc.).

configurationTemplate

String

Identificador de una plantilla de configuración predefinida en el servidor para aplicar ajustes de firma reutilizables.

reason

String

Texto que indica el motivo o propósito de la firma. Este texto suele incrustarse en las propiedades de la firma del PDF.

certificateAlias

String

Alias del certificado en el almacén de claves local del servidor que se debe usar para realizar la firma.

certificatePass

String

Contraseña para acceder al certificado privado indicado en certificateAlias.

certificateId

String

Identificador del certificado si se emplea un sistema de gestión centralizada (alternativo al alias local).

trailEnabled

Boolean

Indica si se debe generar un rastro de auditoría (Audit Trail) específico para esta operación de firma.

archiveEnabled

Boolean

Indica si el documento firmado resultante debe ser archivado automáticamente en el sistema de gestión documental o custodia configurado.

fortressConfiguration

Object (FortressConfigurationDTO)

Configuración específica para delegar la firma en Viafirma Fortress (nube/centralizado), anulando la configuración local.
Respuesta del servicio

Si la solicitud es correcta, el servicio devuelve un objeto RequestResultDTO con el token de la operación.

{
    "code": "TOK-123456789",
    "count": 1,
    "expires": 1690610891372,
    "clientAccess": {
        "desktopProtocol": "viafirmawpfclient://?url=...&operationId=TOK-123456789",
        "link": "https://..."
    }
}
Campo Descripción

code

Token único de la operación generado. Este código se usará en el resto de llamadas (/access, /add/data).

expires

Fecha de caducidad del token en milisegundos (Epoch timestamp).

clientAccess

Objeto que contiene la cadena de protocolo (desktopProtocol) para lanzar la aplicación nativa automáticamente.

3.8.2. Añadir documento a la operación

Método del API que permite añadir y configurar un documento a una petición de evidencia existente. Este servicio es útil cuando no se envían todos los documentos en la llamada inicial de creación (/request), permitiendo agregarlos posteriormente paso a paso.

Para usar este servicio, la operación creada previamente debe tener "huecos" disponibles. Es decir, el número de documentos ya subidos debe ser menor al count total especificado en la petición inicial.
Uso del servicio
POST /api/client/evidence/add/config

Además, en la cabecera HTTP de la petición, es necesario realizar una autenticación de tipo Básica.

Parámetros del servicio

Este servicio recibe por parámetros un objeto JSON EvidencePrepareConfigDTO que contiene el documento y su configuración específica.

{
    "requestCode": "TOK-123456789",
    "file": "{{base64File_OR_URL}}",
    "fileName": "contrato_ventas.pdf",
    "type": "SIGNATURE",
    "positions": [
        {
            "page": 1,
            "x": 100,
            "y": 200,
            "width": 150,
            "height": 75
        }
    ],
    "sourceId": "REF-EXTERNA-001",
    "password": "pdf_password",
    "trailEnabled": true
}

A continuación se describen los campos del objeto de entrada:

Table 1. Parámetros de entrada (EvidencePrepareConfigDTO)
Campo Tipo Descripción

requestCode

String

Token de la operación a la que se quiere añadir este documento. Este token se obtuvo previamente en la respuesta de /request. (Obligatorio).

file

String

Contenido del documento. El servicio es capaz de detectar automáticamente tres formatos: 1. Base64: El binario del PDF codificado. 2. URL: Una dirección web pública desde donde descargar el PDF. 3. Cache ID: Un identificador de un documento previamente subido a la caché temporal del servidor.

fileName

String

Nombre del archivo (ej. documento.pdf). Importante para el registro y la devolución del archivo firmado.

type

String (Enum)

Tipo de evidencia a capturar en este documento específico (ej. SIGNATURE, IMAGE).

positions

List<PositionDTO>

Lista de coordenadas (página, x, y, ancho, alto) donde se estampará la evidencia en este documento.

sourceId

String

Identificador externo o referencia del documento en el sistema cliente. Útil para trazabilidad.

password

String

Contraseña del documento PDF, si el archivo original se encuentra protegido contra lectura o edición.

trailEnabled

Boolean

Indica si se debe generar un rastro de auditoría individual para este documento específico.
Respuesta del servicio

Si el documento se procesa correctamente, el servicio devuelve un objeto EvidenceConfigResponseDTO.

{
    "evidenceCode": "DOC-REF-987654321",
    "expires": 1690610891372
}

Donde:

Campo Descripción

evidenceCode

Identificador único del documento preparado dentro de la operación. Este código se usa internamente para referenciar este archivo específico.

expires

Fecha de caducidad de la operación en milisegundos (Epoch timestamp).

3.8.3. Consultar estado de la petición

Método del API que permite consultar el estado actual de una operación de evidencia. Devuelve información detallada sobre la configuración de la petición, su fecha de expiración y el estado individual de cada documento asociado.

Uso del servicio
GET /api/client/evidence/status/{token}
Parámetros del servicio

Este servicio recibe un único parámetro en la ruta de la URL (Path Variable).

Parámetro Tipo Descripción

token

String

Token único de la operación que se desea consultar.
Respuesta del servicio

El servicio devuelve un objeto RequestStatusResponseDTO con toda la información de la transacción.

{
    "requestCode": "TOK-123456789",
    "operationId": "OP-98765",
    "totalCount": 1,
    "type": "EVIDENCE",
    "evidenceType": "SIGNATURE",
    "expires": 1690610891372,
    "callbackURL": "https://mi-sistema.com/callback",
    "callbackRedirectURL": "https://mi-sistema.com/fin?token=TOK-123456789",
    "operations": [
        {
            "id": "DOC-001",
            "status": "FINISHED"
        }
    ]
}

A continuación se describen los campos principales de la respuesta:

Campo Tipo Descripción

requestCode

String

Token de la operación consultada.

totalCount

Integer

Número total de evidencias o firmas que componen esta petición.

type

String (Enum)

Categoría de la petición (ej. EVIDENCE, SIGNATURE).

evidenceType

String (Enum)

Tipo específico de evidencia configurada (ej. SIGNATURE para biométrica, IMAGE, etc.).

expires

Date (Timestamp)

Fecha y hora en la que la operación caducará y dejará de estar disponible.

callbackURL

String

URL de notificación configurada para esta operación.

callbackRedirectURL

String

URL de redirección final para el usuario.

operations

List<OperationStatusDTO>

Lista que contiene el estado individual de cada documento o evidencia dentro de la operación (ej. PENDING, FINISHED, ERROR).

certificate

Object (CertificateResponseDTO)

Información pública del certificado digital utilizado o seleccionado, si aplica.

randomStringToSignForAuth

String

Cadena aleatoria utilizada en procesos de autenticación/firma específicos.

3.8.4. Consultar posiciones de las evidencias

Método del API que permite recuperar las coordenadas y ubicación dentro del documento donde se deben estampar las evidencias. Este servicio es utilizado principalmente por la aplicación cliente (Desktop/Mobile) para dibujar los recuadros de firma en la interfaz de usuario.

Uso del servicio
GET /api/client/evidence/positions/{token}
Parámetros del servicio

Este servicio recibe un único parámetro en la ruta de la URL (Path Variable).

Parámetro Tipo Descripción

token

String

Token único de la operación actual.
Respuesta del servicio

El servicio devuelve una lista de objetos PositionsResponse. Cada elemento de la lista corresponde a un documento dentro de la operación y contiene sus respectivas posiciones de firma.

[
    {
        "documentId": "DOC-REF-001",
        "positions": [
            {
                "page": 1,
                "x": 100,
                "y": 250,
                "width": 150,
                "height": 75
            }
        ]
    },
    {
        "documentId": "DOC-REF-002",
        "positions": [
            {
                "page": 2,
                "x": 50,
                "y": 500,
                "width": 100,
                "height": 50
            }
        ]
    }
]

A continuación se describen los campos de la respuesta:

Campo Tipo Descripción

documentId

String

Identificador único del documento al que pertenecen las posiciones. Este ID es necesario para correlacionar la evidencia capturada con el archivo correcto.

positions

List<PositionDTO>

Lista de coordenadas definidas para este documento.

positions/page

Integer

Número de página del PDF donde se ubica la evidencia (comienza en 1).

positions/x

Integer

Coordenada horizontal (eje X) de la esquina superior izquierda del recuadro.

positions/y

Integer

Coordenada vertical (eje Y) de la esquina superior izquierda del recuadro.

positions/width

Integer

Ancho del área de evidencia.

positions/height

Integer

Alto del área de evidencia.

3.8.5. Finalización y envío de datos de evidencia

Este es el método principal para finalizar el ciclo de captura. La aplicación cliente debe invocar este servicio una vez que ha capturado la información del usuario (biometría, imagen, ubicación, etc.).

El servicio recibe los datos, los procesa, los incrusta en el documento PDF y, si está configurado, aplica la firma digital final (PAdES/XAdES) y el sellado de tiempo.

Uso del servicio
POST /api/client/evidence/add/data/{token}
Parámetros del servicio

Este servicio recibe el token en la ruta y un cuerpo JSON (EvidenceRequestDataDTO) con toda la información capturada.

{
    "requestCode": "TOK-123456789",
    "configEvidenceDTO": {
        "type": "SIGNATURE",
        "clientTimestamp": 1690610891372,
        "device": {
            "manufacturer": "Wacom",
            "model": "STU-530",
            "screenHeight": 800,
            "screenWidth": 600,
            "maxPressure": 1024
        },
        "geolocation": {
            "latitude": 37.3891,
            "longitude": -5.9845,
            "accuracy": 10.5
        },
        "biometricData": {
            "signatureIsoFormat": "{{base64IsoData}}",
            "strokes": [  ]
        },
        "configSignature": {
            "signatureType": "PADES_B",
            "tsa": { "url": "http://tsa.viafirma.com" }
        }
    }
}

A continuación se detalla la estructura de los objetos de entrada.

Table 2. Objeto Principal (EvidenceRequestDataDTO)
Campo Tipo Descripción

requestCode

String

Token de la operación (debe coincidir con el de la URL).

configEvidenceDTO

Object

Objeto complejo que contiene toda la configuración y los datos capturados. Ver detalles a continuación.
Table 3. Configuración de Evidencia (ConfigEvidenceDTO)
Campo Tipo Descripción

type

String (Enum)

Tipo de evidencia capturada (SIGNATURE, IMAGE, FINGERPRINT, etc.).

clientTimestamp

Long

Marca de tiempo (Epoch) del momento exacto en que se capturó la evidencia en el cliente.

device

EvidenceDeviceDTO

Información de hardware del dispositivo digitalizador. (Ver tabla Datos del Dispositivo).

geolocation

GeolocationDTO

Información GPS de donde se realizó la firma. (Ver tabla Geolocalización).

biometricData

ConfigBiometricDataDTO

Datos biométricos en bruto (trazos, presión, etc.). (Ver tabla Datos Biométris).

configSignature

ConfigSignatureDTO

Configuración de la firma electrónica que sellará el documento. (Ver tabla Configuración de Firma).

positions

List<PositionDTO>

Lista de coordenadas. Nota: Si las posiciones ya se definieron al subir el documento, este campo debe ir nulo. No pueden coexistir en ambos lados.

image

String (Base64)

Imagen estática de la rúbrica o evidencia (opcional si ya se envían datos biométricos para renderizar).
Detalles de Objetos Anidados
1. Datos del Dispositivo (EvidenceDeviceDTO)

Información técnica sobre el hardware utilizado para capturar la evidencia (Tablet, Móvil, Pad de firma).

Campo Tipo Descripción

manufacturer

String

Fabricante del dispositivo (ej. Apple, Samsung, Wacom).

model

String

Modelo del dispositivo.

osVersion

String

Versión del Sistema Operativo.

screenHeight / screenWidth

Integer

Resolución de la pantalla en píxeles.

areaHeight / areaWidth

Integer

Dimensiones del área activa de firma.

ppi

String

Píxeles por pulgada (densidad de pantalla).

minPressure / maxPressure

Double

Niveles de sensibilidad de presión soportados por el digitalizador.

rotationAllowed

Boolean

Indica si el dispositivo permite rotación de pantalla.

ip

String

Dirección IP del cliente.
2. Geolocalización (GeolocationDTO)

Datos de ubicación geográfica para la auditoría de la firma.

Campo Tipo Descripción

latitude

Double

Latitud geográfica.

longitude

Double

Longitud geográfica.

accuracy

Double

Precisión de la ubicación en metros.

locationInfo

String

Información descriptiva adicional del lugar (opcional).
3. Datos Biométricos (ConfigBiometricDataDTO)

Contiene la información sensible de la firma (velocidad, aceleración, presión).

Campo Tipo Descripción

strokes

List

Lista de objetos que representan cada trazo de la firma (coordenadas X, Y, presión y tiempo por punto).

signatureIsoFormat

String (Base64)

Biometría codificada en formato estándar ISO/IEC 19794-7 (si aplica).

publicKey

X509Certificate

Clave pública utilizada para cifrar los datos biométricos en el cliente. Si no se envía, el servidor intentará usar la configurada por defecto.

fingerPrintData

Object

Datos específicos si la evidencia es una huella dactilar.
4. Configuración de Firma (ConfigSignatureDTO)

Define cómo se aplicará la firma electrónica al documento PDF una vez incrustada la evidencia.

Campo Tipo Descripción

signatureType

Enum

Formato de la firma electrónica. Valores comunes: PADES_B (PDF Básico), PADES_LTV (Larga duración), XADES, CADES.

packaging

Enum

Tipo de empaquetado (ENVELOPED, DETACHED, ENVELOPING). Para PDF suele ser ENVELOPED.

signatureAlgorithm

Enum

Algoritmo de firma (ej. SHA256withRSA).

tsa

ConfigTsaDTO

Configuración de la Autoridad de Sellado de Tiempo (URL, usuario, pass) para dar validez legal temporal a la firma.

policy

ConfigPolicyDTO

OID y URL de la política de firma explícita a incluir en el certificado.

signatureReason

String

Texto del "Motivo" de la firma que aparecerá en las propiedades del PDF.

city / stateOrProvince / country

String

Metadatos de ubicación que se incrustarán en la firma del PDF.

custodyStorage

Boolean

Si es true, solicita al servidor que guarde una copia del documento firmado en el sistema de custodia.

timestampAlgorithm

Enum

Algoritmo a usar para el sello de tiempo (ej. SHA256).
Respuesta del servicio

El servicio devuelve un objeto DataEvidenceResponseDTO que contiene una lista con los documentos resultantes firmados.

{
    "evidenceResponseList": [
        {
            "result": "{{base64_PDF_Firmado}}",
            "format": "PDF",
            "metadata": {  }
        }
    ]
}

3.8.6. Inserción Directa de Evidencia

Método del API que permite realizar todo el proceso en una única llamada: subir el documento, enviar la evidencia capturada (biometría, imagen, etc.) y recuperar el documento firmado inmediatamente.

A diferencia del flujo de solicitud (/request), este método es síncrono y no mantiene sesión en el servidor. Es ideal para escenarios donde el cliente ya dispone del documento y de los datos de la evidencia antes de contactar con el servidor.

Uso del servicio
POST /api/client/evidence/add
Parámetros del servicio

Recibe un objeto EvidenceRequestDTO que combina la configuración y los datos.

{
    "file": "{{base64_PDF_Original}}",
    "configuration": {
        "type": "SIGNATURE",
        "biometricData": {
            "biometricInfo": "{{base64_Biometria_Capturada}}"
        },
        "positions": [
             { "page": 1, "x": 100, "y": 100, "width": 100, "height": 50 }
        ],
        "configSignature": {
            "signatureType": "PADES_B"
        }
    },
    "certificateAlias": "mi_certificado",
    "certificatePass": "1234"
}
Campo Tipo Descripción

file

String

El documento original sobre el que se aplicará la evidencia (Base64 o URL).

configuration

ConfigEvidenceDTO

Objeto que contiene los datos de la evidencia (Biometría, Dispositivo, Geolocalización, etc.) y las posiciones visuales. (Es el mismo objeto detallado en la sección anterior).

certificateAlias / certificatePass

String

(Opcional) Credenciales del certificado local para firmar el documento resultante.

fortressConfiguration

Object

(Opcional) Configuración para delegar la firma final en Viafirma Fortress.
Respuesta del servicio

Devuelve directamente el resultado de la operación.

{
    "result": "{{base64_PDF_Firmado}}",
    "format": "PDF",
    "metadata": {  }
}
Campo Tipo Descripción

result

String (Base64)

El documento final con la evidencia incrustada y firmado digitalmente.

4. Políticas de firma

Pueden configurar una política de firma empleando los distintos tipo de firma, empleando la siguiente configuración de firma

4.1. Parámetros de configuración

Parámetro Valores permitidos Requerido Description

signatureType

- CADES_B
- CADES_T
- CADES_LT
- CADES_LTA
- PADES_B
- PADES_T
- PADES_LT
- PADES_LTA
- XADES_B
- XADES_T
- XADES_LT
- XADES_LTA`

SI

Formato de firma

signatureAlgorithm

- RSA_SHA1
- RSA_SHA224
- RSA_SHA256
- RSA_SHA384
- RSA_SHA512

NO

Si no se informa, se aplicará el algoritmo RSA_SHA256

packaging

- ENVELOPED
- ENVELOPING
- DETACHED

SI

Tipo de empaquetado a emplear en la firma

reason

Cadena de texto

NO

Motivo de la firma

location

Cadena de texto

NO

Localización donde se realiza la firma

En los siguientes apartados, indicaremos la configuración necesaria para cada uno de los tipos de firma.

Nota → Será necesario tener configurado una TSA a nivel de aplicación, o una TSA por defecto a nivel de plataforma para poder realizar firmas que requieran agregar un sello de tiempo, es decir, se empleará la TSA en firmas de los siguientes tipos:

  • CADES_T

  • CADES_LT

  • CADES_LTA

  • PADES_T

  • PADES_LT

  • PADES_LTA

  • XADES_T

  • XADES_LT

  • XADES_LTA

Para especificar que se quiere incluir una política de firma es necesario informar el campo policy en la configuración de la firma.

Por ejemplo, si queremos usar la política de firma de la AGE v1.9, la configuración sería como la siguiente:

{
    "file": "{{base64file}}",
    "certificateId": "{{certificateId}}",
    "configuration": {
        "signatureType": "PADES_B",
        "packaging": "ENVELOPED",
        "policy" : {
              "id" : "2.16.724.1.3.1.1.2.1.9",
              "url" : "https://sede.060.gob.es/politica_de_firma_anexo_1.pdf",
              "description" : "Política de firma electrónica para la Administración General del Estado",
              "digestAlgorithm" : "SHA1",
              "digestValue" : "Rzdyb3VjZjYwMCtmMDNyL28wYkFPUTZXQXMwPQ=="
            },
        "operationId": "{{myExpReference}}-{{$randomInt}}"
    }
}

4.2. PAdES

Pueden configurar una política de firma PAdES para firmar documentos PDF.

4.2.1. Parámetros de configuración

Parámetro Valores permitidos Requerido Description

signatureType

- PADES_B
- PADES_T
- PADES_LT
- PADES_LTA

SI

Formato de firma
Ejemplo de configuración
{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED"
}

4.2.2. Configuración PAdES

Esta configuración solo se aplica para las firmas cuyo signatureType es de tipo PAdES (PAdES B, PAdES T, PAdES LT, PAdES LTA).

"padesConfiguration": {
"stamper": { }
}
Parámetro Description

stamper

[OPCIONAL] Sirve para definir un sello visual asociado a la firma PAdES.

4.2.3. Configuración del Stamper

Parámetro Description

type

Tipo de sello. Valores disponibles:

- PDF417
- QR_BARCODE128
- QR
- BARCODE128
- IMAGE
- TEXT
- QR_NO_TEXT
- QR_SCALED
- CUSTOM_TEXT
- QR_REDUCED
- CSV
- CSV_QR
- IMAGE_TEXT
- DEFAULT

timeZoneId

[OPCIONAL] String que se corresponderá con la lista estándar de zonas horarias.

rotation

[OPCIONAL] Rotación del sello. Si se informa, el sello rotará los grados indicados (Por defecto se aplica ROTATE_0 y no se rota el sello). Valores posibles:

- ROTATE_0
- ROTATE_90
- ROTATE_180
- ROTATE_270

page

Página donde se pintará el sello. Se puede usar el valor -1 para indicar la última página o el valor 0 para pintar el sello en todas las páginas del documento

width

[Opcional]. Ancho del sello de firma

height

[Opcional]. Alto del sello de firma

xAxis

[Opcional]. Posición (en el eje X) del sello de firma

yAxis

[Opcional]. Posición (en el eje Y) del sello de firma

csvPath

URL de verificación de la firma

textLine1

[Opcional]. Primera linea textual a pintar en el contenido del sello de firma

textLine2

[Opcional]. Segunda linea textual a pintar en el contenido del sello de firma

textLine3

[Opcional]. Tercera linea textual a pintar en el contenido del sello de firma

imageUrl

URL de la imagen de fondo del sello de firma

En los siguientes apartados, se proporcionan ejemplos con los tipos de sello disponibles.

Tipo BARCODE128

Tipo de sello BARCODE128, el cual tiene el siguiente formato.

stamper BARCODE 128

Para generar un sello con el formato BARCODE128, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "BARCODE128",
      "width" : 396,
      "height" : 50,
      "xAxis" : 5,
      "yAxis" : 650,
      "page" : 1
    }
  }
}
Tipo CSV

Tipo de sello CSV, el cual tiene el siguiente formato.

stamper QR_BAR

Para generar un sello con el formato CSV, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType": "PADES_B",
  "packaging": "ENVELOPED",
  "padesConfig": {
    "stamper": {
      "type": "CSV",
      "width": 500,
      "height": 12,
      "xAxis": 5,
      "yAxis": 650,
      "page": 0,
      "signingDate": 1709729687957,
      "transparent": true,
      "addCsvLink": false
    }
  }
}
Tipo CSV_QR

Tipo de sello CSV_QR, el cual tiene el siguiente formato.

stamper QR_BAR

Para generar un sello con el formato CSV_QR, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType": "PADES_B",
  "packaging": "ENVELOPED",
  "padesConfig": {
    "stamper": {
      "type": "CSV_QR",
      "width": 500,
      "height": 12,
      "xAxis": 5,
      "yAxis": 650,
      "page": 0,
      "signingDate": 1709729687957,
      "transparent": true,
      "addCsvLink": false
    }
  }
}
Tipo DEFAULT

Tipo de sello DEFAULT, el cual tiene el siguiente formato.

stamper DEFAULT

Para generar un sello con el formato DEFAULT, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "DEFAULT",
      "width" : 595,
      "height" : 36,
      "xAxis" : 0,
      "yAxis" : 805,
      "page" : 1
    }
  }
}
Tipo IMAGE

Tipo de sello IMAGE, el cual tiene el siguiente formato.

stamper IMAGE

Para generar un sello con el formato IMAGE, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "IMAGE",
      "width" : 669,
      "height" : 300,
      "xAxis" : 10,
      "yAxis" : -10,
      "page" : 0,
      "image" : "iVBORw0KGgoAAAANSUhEUgAAA....",
      "signingDate" : 1709729646021,
      "transparent" : true,
      "addCsvLink" : false
    }
  }
}
Tipo IMAGE_TEXT

Tipo de sello IMAGE_TEXT, el cual tiene el siguiente formato.

stamper IMAGE_TEXT

Para generar un sello con el formato IMAGE_TEXT, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "IMAGE_TEXT",
      "textLine1": "Signed by Viafirma Developers",
      "width" : 200,
      "height" : 200,
      "xAxis" : 10,
      "yAxis" : -10,
      "page" : 0,
      "image" : "iVBORw0KGgoAAAANSUhEUgAAAp...",
      "signingDate" : 1709729646021,
      "transparent" : true,
      "addCsvLink" : false
    }
  }
}
Tipo QR

Tipo de sello QR, el cual tiene el siguiente formato.

stamper QR

Para generar un sello con el formato QR, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "QR",
      "width" : 324,
      "height" : 36,
      "xAxis" : 5,
      "yAxis" : 650,
      "page" : 1
    }
  }
}
Tipo QR_BAR

Tipo de sello QR_BAR, el cual tiene el siguiente formato.

stamper QR_BAR

Para generar un sello con el formato QR_BAR, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "QR_BARCODE128",
      "width" : 432,
      "height" : 72,
      "xAxis" : 5,
      "yAxis" : 650,
      "page" : 1
    }
  }
}
Tipo TEXT

Tipo de sello TEXT, el cual tiene el siguiente formato.

stamper TEXT

Para generar un sello con el formato TEXT, deben agregar un stamper con el figuiente formato a la solcitud de firma.

{
  "signatureType" : "PADES_B",
  "packaging" : "ENVELOPED",
  "padesConfig" : {
    "stamper" : {
      "type" : "TEXT",
      "width" : 288,
      "height" : 28,
      "xAxis" : 5,
      "yAxis" : 650,
      "page" : 0,
      "signingDate" : 1709729677440
    }
  }
}

4.3. XAdES

Pueden configurar una política de firma XAdES para firmar documentos XML.

En el atributo signatureType puedes configurar el formato de firma.

XADES_B

Firma básica

XADES_T

Firma con sello de tiempo

XADES_LT

Firma con sello de tiempo a largo plazo

XADES_LTA

Firma con sello de tiempo a largo plazo avanzado

{
  "signatureType" : "XADES_B",
  "packaging" : "ENVELOPED"
}

4.3.1. Configuración XAdES

Esta configuración solo se aplica para las firmas cuyo signatureType es de tipo XAdES (XAdES B, XAdES T, XAdES LT, XAdES LTA).

"xadesConfiguration": {

}

Parámetros a agregar en el objeto xadesConfiguration:

Parámetro Description

signedInfoCanonicalizationMethod

Método de canonización del nodo signedInfo

signedPropertiesCanonicalizationMethod

Método de canonización del nodo signedProperties

xPathLocationString

Selector del nodo bajo el que se insertará la firma, en formato XPath:

Nodos sin namespace

Por ejemplo <factura> podríamos emplear: "xPathLocationString": "//factura"

Referencia:

https://www.w3schools.com/xml/xpath_syntax.asp

Nodos con namespace

por ejemplo:

<T:TicketBai xmlns:T="urn:ticketbai:emision"> , podríamos emplear: "xPathLocationString": "/*[\"TicketBai\"=local-name()]/Sujetos/Emisor" para seleccionar el nodo Emisor

Referencia:

https://www.ibm.com/support/pages/how-use-xpath-namespaces-rit

claimedSignerRoles

Roles del firmante

transformAlgorithms

Algoritmos de transformación para los nodos. Posibles valores:

- http://www.w3.org/TR/2001/REC-xml-c14n-20010315
- http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments
- http://www.w3.org/2001/10/xml-exc-c14n#
- http://www.w3.org/2001/10/xml-exc-c14n#WithComments
- http://www.w3.org/2006/12/xml-c14n11
- http://www.w3.org/2006/12/xml-c14n11#WithComments
- http://santuario.apache.org/c14n/physical

dssReferenceUri

Identificador del nodo a firmar

manifestSignature

Si vale true especifica que se trata de una firma XAdES Manifest.

hashSignature

Si vale true especifica que se trata de la firma del hash de un archivo.

hashDigestAlgorithm

En caso de que se trate de la firma de un hash, se debe especificar el algoritmo de cálculo del hash. Posibles valores:

- SHA1
- SHA224
- SHA256
- SHA384
- SHA512

Por ejemplo:

{
    "signedInfoCanonicalizationMethod": "http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
    "signedPropertiesCanonicalizationMethod": "http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
    "xPathLocationString": "//book[@id='bk101-1']",
    "claimedSignerRoles": [
        "role1",
        "role2"
    ],
    "transformAlgorithms": [
        "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
    ],
    "dssReferenceUri": "http://dsa-reference.example.com/"
}

4.4. CAdES

Puedes configurar una política de firma CAdES para firmar cualquier tipo de documento

En el atributo signatureType puedes configurar el formato de firma.

CADES_B

Firma básica

CADES_T

Firma con sello de tiempo

CADES_LT

Firma con sello de tiempo a largo plazo

CADES_LTA

Firma con sello de tiempo a largo plazo avanzado

{
  "signatureType" : "CADES_B",
  "packaging" : "ENVELOPING"
}

5. Filtros de certificados

Puede aplicar los filtros de certificados en las operaciones de firma y autenticación.

{
    "certificateFilter": {
        "autoSend": true,
        "certFilter": {
            "operator": "contains",
            "filterValues": [
                "CALERO"
            ]
        },
        "caFilter": {
            "operator": "contains",
            "filterValues": [
                "FNMT"
            ]
        },
        "nationalIdFilter": {
            "operator": "contains",
            "filterValues": [
                "47000000Y"
            ]
        }

    }
}

6. Callback

Cuando se realiza una operación de firma o validación, se puede configurar un callback para recibir la respuesta de la operación.

POST {{callbackURL}} HTTP/1.1
{
    "totalCount": 1,
    "type": "SIGNATURE",
    "certificate": {
        "numberUserId": "47000000Y",
        "name": "MANUEL JESUS",
        "surname1": "LOPEZ",
        "surname2": "CALERO",
        "ca": "C=ES,O=FNMT-RCM,OU=Ceres,CN=AC FNMT Usuarios",
        "type": "X.509",
        "cn": "C=ES,SERIALNUMBER=IDCES-47000000Y,GIVENNAME=MANUEL JESUS,SURNAME=LOPEZ CALERO,CN=LOPEZ CALERO MANUEL JESUS - 47000000Y",
        "isValidated": true,
        "isExpired": false,
        "isRevoked": false
    },
    "expires": 1728440171250,
    "requestCode": "eyJ0eXAi....",
    "operationId": "1728440171250_a43856a5a11045aa",
    "callbackURL": "https://webhook.site/eb7b4ff4-a036-49d1-b6b5-3cc006ef429d",
    "certificateFilter": {
        "autoSend": false,
        "discardExpiredCertificates": true,
        "certFilter": {},
        "caFilter": {},
        "nationalIdFilter": {}
    },
    "operations": [
        {
            "documentId": "SCKR-DOAG-OF1O-....",
            "status": "FINISHED",
            "signedLink": "https://sandbox.viafirma.com/signservices/d/SCKR-DOAG-OF1O-.....",
            "fileName": "833860cc-ad5e-4b9a-b7d1-381af8cfa722.pdf",
            "sourceId": "postman_test_d3be9428-12da-4715-b7a3-b45aa983370b"
        }
    ]
}

7. Códigos de error

Código de error Clave Código de respuesta HTTP Description

8

BAD_PARAMS

400

9

CONFIGURATION_PROBLEM

400

36

DOCUMENT_NOT_FOUND

500

37

DOCUMENT_SIGNED_NOT_FOUND

404

38

DOCUMENT_ORIGINAL_NOT_FOUND

404

39

DOCUMENT_SOURCE_INVALID

406

50

TRAIL_ERROR

500

51

TRAIL_UNAVAILABLE

500

70

CERTIFICATE_NOT_FOUND

406

71

CERTIFICATE_CIPHER_NOT_FOUND

406

No se ha encontrado el certificado cifrado de datos biométricos

41

TEMPLATE_NOT_FOUND

404

42

TEMPLATE_TSA_NOT_FOUND

404

110

PERSISTENCE_ERROR

500

65

TSA_UNKNOWN_HOST

500

100

VIAFIRMA_CORE_ERROR

500

350

FORTRESS_UNAVAILABLE

500

400

REQUEST_CREATE_CONFIGURATION_ERROR

406

401

REQUEST_UPDATE_CONFIGURATION_ERROR

406

501

CLIENT_CALLBACK_ERROR

500

801

LICENSE_NOT_VALID

500

996

TEMPORAL_PERSISTENCE_ERROR

500

997

SERVICE_NOT_AVAILABLE

404

999

UNKNOWN_ERROR

500

8. Referencias