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

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