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, que se corresponde con un valor de TypeFormatSign, el tipo de firma: signatureType, que toma un valor de TypeSign, 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. Los distintos parámetros de la Policy están recogidos en la documentación de integración.
    • 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.

Preparación de operación de firma biométrica

  • URL: /api/rest/services/biometricSignature
  • Seguridad: BASIC Auth pasando el API key / password
  • Método: POST
  • Body de ejemplo:
    {
  "file": {
      "filename": "test.pdf",
      "base64Content": "xxxx",
      "signaturePolicy": {
          "signatureFormat": "DIGITALIZED_SIGN",
          "signatureType": "ATTACHED",
          "parameters": {
              "digitalizedSignColor": "#FF0000",
              "digitalizedSignHelpText": "Texto de ayuda aportado por el integrador",
              "digitalizedSignRectangle": "{'x':400,'y':60,'height':120,'width':160}",
              "biometricAlias": "alias de un certificado para firmar la evidencia biométrica",
              "biometricPass": "password del certificado",
              "biometricCryptoPEM": "PEM de un certificado para cifrar",
              "alias": "alias de un certificado para firmar el documento tras asociar la evidencia",
              "pass": "Password del certificado de firma en servidor",
              "digitalizedSignatureInfo": "Firmante de ejemplo"
          }
      }
  },
  "locale": "es",
  "sessionId": "xxxx"
}
    En este caso, hay varias diferencia con el JSON de operación de firma con certificado:
  • Desaparece el bloque certFilter y el atributo autoSend.

  • Solo se admite un objeto de tipo fichero, y no un array. El fichero sigue teniendo la política asociada, pero en este caso deben usarse los parámetros de política de firma digitalizada.

  • Valores:

    • file: campo obligatorio con el fichero afirmar, que debe ser un PDF. Se compone del 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, en este caso DIGITALIZED_SIGN), el tipo de firma (signatureType: ATTACHED), los y parámetros de política de firma digitalizada.
    • 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.

Como ocurre en el resto de casos, el servidor simplemente un parámetro llamado operationId:

{
    "operationId": "XXXXX"
}

Realizando la invocación a la aplicación del mismo modo que las firmas con certificado:

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.

El resto de integración es idéntica a la firma con certificado por protocolo.

Consulta sobre el estado de la operación

  • URL: URL_VIAFIRMA/api/rest/services/operation/finished/OPERATION_ID (sustituyendo los valores correctos de URL_VIAFIRMA y OPERATION_ID)
  • Seguridad: BASIC Auth pasando el API key / password
  • Método: GET

Este servicio suele ser consultado por algún tipo de polling en la aplicación cliente, que permita conocer cuándo ha finalizado la operación por parte del usuario y se puede por tanto proceder a gestionar el nuevo estado (error, cancelado, ok - descargando la información de la operación).

El JSON de respuesta incluye los siguiente campos:

  • isFinished: boolean, true si la operación ha finalizado.
  • isCancelled: boolean, true si la operación ha sido cancelada por el usuario.
  • hasErrors: boolean, true si la operación ha finalizado con errores.
  • errorCode: código de error (en el caso de que la operación haya finalizado con errores).
  • errorMessage: mensaje de error (en el caso de que la operación haya finalizado con errores).
  • isSignature: oolean, true si la operación es una firma (false si es una autenticación).

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

results matching ""

    No results matching ""