SDK viafirma platform

Invocación a Viafirma Desktop por protocolo

No es necesario utilizar el cliente Java SDK para preparar las operaciones de autenticación y firma mediante invocación por protocolo a Viafirma Desktop, pudiendo realizarse directamente llamadas al servicio REST. El resto de la integración se mantiene igual, tal y como se explicó en los apartados concretos de autenticación y firma invocando a la aplicación por protocolo.

Preparación de operación de autenticación

  • URL: /api/rest/services/auth
  • Seguridad: BASIC Auth pasando el API key / password
  • Método: POST
  • Body de ejemplo:
    {
      "autoSend": true,
      "certFilter": {
          "operator": "contains",
          "filterValues": ["FNMT"]
      },
      "caFilter": {
          "operator": "contains",
          "filterValues": ["FNMT"]
      },
      "numberUserIdFilter": {
          "operator": "contains",
          "filterValues": ["4"]
      },
      "locale": "es",
      "sessionId": "XXXXX"
    }
    
  • Valores:

    • autoSend: indica si la aplicación debe realizar un envío de los datos del certificado sin interacción del usuario (sólo posible cuando hay un único certificado).
    • certFilter: objeto con datos de filtrado del certificado (opcional). Internamente utiliza el filtro genérico (busca los valores en cualquier campo del certificado, con un OR). Dentro del objeto certFilter está el operador de filtrado (equals, contains, starts_with, ends_with) y los valores de los filtros: filterValues.
    • caFilter: filtro específico para filtrar por CAs; si se mete más de un valor, hace lógica de tipo OR. Por ejemplo, con un operador contains, y valores FNMT y DNI, filtraría todos los certificados que sean de FNMT o DNI electrónico.
    • numberUserIdFilter: filtro específico para filtrar por el serial number del certificado (cédula, DNI, CIF, etc.); si se mete más de un valor, hace lógica de tipo OR. Por ejemplo, con un operador contains, y valores 4 y 5, filtraría todos los certificados que tengan un 4 o 5 en su serialNumber.
    • locale: Locale del usuario que está interactuando con la aplicación a integrar (obtenido del objeto request).
    • sessionId: ID de sesión del usuario que está interactuando con la aplicación a integrar (obtenido del objeto request).

    Los nodos del JSON caFilter y numberUserIdFilter solo están disponibles desde la versión 3.17.1 de viafirma platform y requieren una versión mínima 1.6.7 de Viafirma Desktop.

Preparación de operación de firma

Importante: desde las versiones viafirma-client 2.14.6 y viafirma platform 3.15.6, el objeto policy deja de ser un parámetro de la llamada, ya que obligaba a que para hacer una firma en lotes, todos los ficheros compartan la Policy de firma. A partir de estas versiones, la policy es un parámetro a nivel de fichero:

  • URL: /api/rest/services/signature
  • Seguridad: BASIC Auth pasando el API key / password
  • Método: POST
  • Body de ejemplo:
    {
      "autoSend": true,
      "certFilter": {
          "operator": "CONTAINS",
          "filterValues": ["09431554J", "FNMT"]
      },
      "files": [{
          "filename": "test.pdf",
          "base64Content": "xxxx",
          "signaturePolicy": {
              "signatureFormat": "PAdES_BES",
              "signatureType": "ATTACHED",
              "parameters": {
                  "DIGITAL_SIGN_PAGE": "0",
                  "DIGITAL_SIGN_STAMPER_HIDE_STATUS": "true",
                  "DIGITAL_SIGN_IMAGE_STAMPER_AUTOGENERATE": "false",
                  "DIGITAL_SIGN_STAMPER_TEXT": "Documento firmado",
                  "DIGITAL_SIGN_STAMPER_TYPE": "QR-BAR-H",
                  "DIGITAL_SIGN_RECTANGLE": "{'x':10,'y':10,'height':540,'width':75}"
              }
          }
      }],
      "locale": "es",
      "sessionId": "xxxx"
    }
    
  • Valores:

    • autoSend: indica si la aplicación debe realizar un envío de los datos del certificado sin interacción del usuario (sólo posible cuando hay un único certificado).
    • certFilter: objeto con datos de filtrado del certificado (opcional). Dentro del objeto certFilter está el operador de filtrado (equals, contains, starts_with, ends_with) y los valores de los filtros: filterValues.
    • files: campo obligatorio con la lista de objetos de tipo fichero, compuestos por un nombre de fichero (filename), su contenido en base64 (base64Content), y una signaturePolicy:
    • signaturePolicy: objeto obligatorio, para cada fichero enviado a firmar, con los datos de la política de firma. Incluye el formato de firma (signatureFormat), el tipo de firma (signatureType), y parámetros de política de firma. Todos estos parámetros coinciden en valores a los descritos dentro de la documentación de integración en otros apartados. Es importante tener en cuenta que cuando se añadan parámetros (parameters) en la policy, el JSON debe coincidir con la serialización del objeto como string. Por ello, la página (entero) se incluye como "0" o "1", un parámetro boolean va como "true" o "false", pero un parámetro objeto como el rectángulo se envía como {'x':10,'y':10,'height':540,'width':75}. Para construir el JSON correcto deberán analizarse las opciones (valores y tipos: cadenas, números, booleanos, objetos) de las Policy Params del SDK.
    • locale: Locale del usuario que está interactuando con la aplicación a integrar (obtenido del objeto request).
    • sessionId: ID de sesión del usuario que está interactuando con la aplicación a integrar (obtenido del objeto request).

    NOTA: viafirma platform no puede obtener el sessionId y locale del usuario, dado que el objeto request que recibe es el de la aplicación integrada, no el del usuario.

Ambas operaciones devuelven simplemente un parámetro llamado operationId:

{
    "operationId": "XXXXX"
}

Para poder invocar a la aplicación Viafirma Desktop por protocolo, hay que crear un enlace que siga este formato:

viafirmawpfclient://?url=URL_VIAFIRMA_PLATFORM&operationId=OPERATION_ID

Donde URL_VIAFIRMA_PLATFORM es la dirección del servidor de Viafirma Platform, siguiendo el formato https://testservices.viafirma.com/viafirma, y OPERATION_ID es el parámetro operationId recuperado de la llamada de preparación de la operación de autenticación o firma.

La estrategia de iniciar un proceso de polling Javascript es idéntica a los casos de integración cuando se usa el SDK Java o .NET; en estos casos, viafirma-client únicamente está encapsulando las llamadas a los servicios REST descritos en este apartado.

Una vez que con el polling se verifica que la operación de autenticación o firma está finalizada, se puede invocar a la lógica de servidor de la aplicación para poder descargar la información de la autenticación o firma, disponiendo del ID de operación y el session ID.

Descarga de información de validación del certificado

  • URL: URL_VIAFIRMA/api/rest/services/auth/validation/OPERATION_ID (sustituyendo los valores correctos de URL_VIAFIRMA y OPERATION_ID)
  • Query params:
    • delete = true: elimina la información de la operación en el servidor
    • sessionId = : se envía el ID de sesión del usuario, que deberá coincidir con el enviado en la preparación de la operación.
  • Seguridad: BASIC Auth pasando el API key / password
  • Método: GET

El JSON de respuesta incluye los siguiente campos:

  • operationId: ID de operación devuelto en el primer proceso de preparación de la operación
  • numberUserId: número de identificador del usuario (NIF, cédula...)
  • name: Nombre del usuario
  • surname1: Primer apellido
  • surname2: Segundo apellido
  • email: Email del usuario
  • ca: Autoridad de Certificación emisora (por ejemplo Fábrica Nacional de Moneda y Timbre)
  • shortCa: Autoridad de Certificación emisora - descripción corta (por ejemplo FNMT)
  • jobTitle: Cargo del usuario
  • type: Tipo de certificado
  • cn: Common Name
  • organization: Nombre de la organización / empresa del usuario
  • certificateProperties: lista de variables del certificado (en formato key/value)
  • isValidated: booleano - obtiene valor true si el certificado ha sido validado correctamente
  • isExpired: booleano - obtiene valor true si el certificado está caducado
  • isRevoked: booleano - obtiene valor true si el certificado está revocado

Descarga de información de firma

  • URL: URL_VIAFIRMA/api/rest/services/signature/OPERATION_ID (sustituyendo los valores correctos de URL_VIAFIRMA y OPERATION_ID)
  • Query params:
    • delete = true: elimina la información de la operación en el servidor
    • sessionId = : se envía el ID de sesión del usuario, que deberá coincidir con el enviado en la preparación de la operación.
  • Seguridad: BASIC Auth pasando el API key / password
  • Método: GET

Los datos incluidos en el JSON son:

  • operationId: ID de operación devuelto en el primer proceso de preparación de la operación.
  • signatureId: ID de firma de Viafirma (si son varios documentos, los IDs van separados por comas).
  • certificateValidationData, datos del certificado, con los mismos campos que la respuesta de autenticación:
    • numberUserId: número de identificador del usuario (NIF, cédula...)
    • name: Nombre del usuario
    • surname1: Primer apellido
    • surname2: Segundo apellido
    • email: Email del usuario
    • ca: Autoridad de Certificación emisora (por ejemplo Fábrica Nacional de Moneda y Timbre)
    • shortCa: Autoridad de Certificación emisora - descripción corta (por ejemplo FNMT)
    • jobTitle: Cargo del usuario
    • type: Tipo de certificado
    • cn: Common Name
    • organization: Nombre de la organización / empresa del usuario
    • certificateProperties: lista de variables del certificado (en formato key/value)
    • isValidated: booleano - obtiene valor true si el certificado ha sido validado correctamente
    • isExpired: booleano - obtiene valor true si el certificado está caducado
    • isRevoked: booleano - obtiene valor true si el certificado está revocado