Sobre este documento

Este documento tiene el objetivo de describir la configuración para el lanzamiento de la solución SIGNply 3.0 Firmar documentos PDF mediante llamadas API REST.

 

Introducción

Configuración para el lanzamiento de SIGNply 3.0 Firmar documentos PDF mediante llamadas API REST.

 

Alta en firmar.online

Para poder utilizar el servicio de firma digital sobre su dispositivo Android, debes contar con un plan de firmas activo en la plataforma app.firmar.online.

Asociación del dispositivo

Una vez instalado SIGNply 3.0 en su dispositivo, deberás asociarlo a tu cuenta de app.firmar.online.

Para instalar SIGNply 3.0 deberás acceder al siguiente documento: Descargas Webservice SIGNply

Para asociar el dispositivo a tu cuenta, accede a la plataforma app.firmar.online y deberás seguir los siguientes pasos:

  • Pulsar la rueda, arriba a la derecha, para acceder a las opciones de configuración

  • Seleccionar la pestaña Solicitar firma presencial

  • Activar el indicador Firmar en dispositivo asociado

  • Seleccionar la pestaña SIGNply
  • Pulsar el botón Añadir. Este botón mostrará un código QR:
    Si vas a añadir varios dispositivos, te recomendamos que los nombres mediante un Alias amigable. Por defecto, encontrarás la etiqueta Dispositivo N
  • Escanear el código QR que ves en pantalla desde tu dispositivo,
    • Entra en SIGNply en tu dispositivo
    • Pulsa la rueda de configuración
    • Pulsa el icono con un código QR que queda a la derecha
 

Métodos del Webservice API- REST

Podrás encontrar la definición de los métodos en swagger: https://api.firmar.online/index.html

En esta url se encuentran los ejemplos completos de cada método, se describirán sus campos más adelante.

Necesitas una API-KEY para poder lanzar peticiones al Webservice. Para conocer tu API-KEY, accede a la plataforma app.firmar.online y deberás seguir los siguientes pasos:

  • Pulsar la rueda, arriba a la derecha, para acceder a las opciones de configuración
  • Seleccionar la pestaña Integración API: En esta pantalla encontrarás tu clave
1. MÉTODO: GetDevices

Este método te permite recuperar el identificador de todos los dispositivos que tienes asociados a tu cuenta de firmar.online.

    • Input
      Para la llamada sólo necesitas informar tu API KEY_
      authenticationData: el Api-Key que te ha devuelto la plataforma,
    • Output
      El webservice devuelve la relación de dispositivos asociados.

devices
Identificador del dispositivo: Alias,
33f87f76-eae7-4727-bb0f-4f581de43273: Tablet oficina RRHH,
756e2f02-559d-4486-aba6-267848ecf591: Recepción Oficina Principal

2. MÉTODO: NewDocument
Input

Este método te permitirá enviar documentos a firmar en el dispositivo que selecciones.
authenticationData*: el Api-Key que te ha devuelto la plataforma,
idDevice*: el código del dispositivo que ha devuelto el GetDevices
document*: el documento PDF en Base64
configuration*: en este nodo se configura la firma digital
document*:

      • title*: el nombre que se mostrará en la lista de documentos pendientes de SIGNply
      • description*: Descripción del documento en esta misma lista
      • widget*: parametros relativos al posicionamiento del gráfico de la firma en el PDF
        • type*: Cómo queremos posicionar el Widget:
          Los posibles valores son Field (campo de firma), Float (buscar una cadena de texto dentro del contenido del PDF) o Fixed (posición fija coordenadas X,Y),
        • field: Si el tipo de posicionamiento es Field este nodo es obligatorio.
        • fieldname: Indica el nombre del campo de firma en el PDF
        • fixed: Si el fipo de posicionamiento es fixed será obligatorio informar la página y las coordenadas X e Y
          • page, Número de página donde queremos ubicar el grafo
          • x, y: Coordenadas X e Y. El punto 0,0 corresponde al vertice izquierdo inferior de la página
        • float: Si el fipo de posicionamiento es float será obligatorio informar.
          • text: cadena de caracteres a buscar dentro del PDF
          • gapX, gapY: desplazamiento horizontal y vertical con respecto al primer carácter de la cadena text.
            Los números positivos desplazan hacia la derecha y hacia arriba
          • height y width: Alto y Ancho del gráfico de la firma
          • customtext: permite incorporar líneas de texto al Widget.

line: en cada línea se informa el tamaño y el texto a mostrar. Pueden estar vacías.

      • channel: Canal por el que se devuelven los cambios de estado del documento.
        Si se deja este campo vacío, quedará custodiado en api firmar.online a la espera del envío a un dispositivo. Si por el contrario se se asigna el valor POST se enviará inmediatamente a la URL indicada en el siguiente campo.
      • url: URL donde estará ubicado el canal de devolución del documento. Se realiza mediante multipart/form-data y los nombres de los valores del formulario serían :
        fileSigned: Documento en Base 64.
      • nameFileSigned: Nombre del documento
        name: nombre del documento en la aplicación llamante
      • extras: relación de parejas clave – valor que se devolverán en la salida del webservice. Sirven de apoyo para la gestión documental de la Aplicación llamante
        ClaveExtra1: ValorExtra1
Output

El webservice devuelve el identificador del documento dentro de la plataforma

3. MÉTODO: GetDocument

Este método permite recuperar el estado del documento.
Si el documento ha sido firmado, también se devuelve como output en B64

Input
      • authenticationData*: el Api-Key que te ha devuelto la plataforma,
      • idDocument: el código del documento que ha devuelto método NewDocument
      • extras: Si informas los campos clave- valor podrás recuperar el documento. En caso de que hayas enviado más de un documento con las mismos valores, se devolverá el último enviado.
Output
      • authenticationData: el Api-Key que te ha devuelto la plataforma,
      • idDevice: el código del dispositivo que ha devuelto el GetDevices
      • document: el documento PDF en Base64
      • idDocument: identificador del documento
      • document: el documento en B64
      • name: Título del documento
      • statusCode

100: documento recibido en firmar.online API
200: documento enviado a dispositivo
300: documento firmado en dispositivo, recibido en firmar.online API
400: eliminado en la lista de documentos pendientes del dispositivo
500: rechazado en el dispositivo
600: error enviando documento a URL (channel = POST)
700: documento enviado a URL (channel = POST)

      • descriptionStatusCode: descripción del Status Code
      • reason: razón que se ha indicado al rechazar o eliminar un documento
      • extras: Los parámetros clave-valor informados en el método NewDocument
 

 

  • Share: