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

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 https://firmar.online.

 

Asociación del dispositivo

Una vez instalado SIGNply 30 en su dispositivo, deberás asociarlo a tu cuenta de firmar.online
Puedes instalar SIGNply 30 desde Google Play mediante el siguiente link
https://play.google.com/store/apps/details?id=com.edatalia.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, que 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 https://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

MÉTODO: GetDevices

https://api.firmar.online/v31/SignFromApp/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

MÉTODO: NewDocument:

https://api.firmar.online/v31/SignFromApp/NewDocument

Este método te permitirá enviar documentos a firmar en el dispositivo que selecciones.

  • Input

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) , Fixed (posición fija coordenadas X,Y) o Manual (ratio relación entre ancho y alto widget),
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

Manual: Si el tipo de posicionamiento es manual, el parámetro ratio es opcional (por defecto es 4).
ratio: Proporción entre el ancho y el alto. Debe ser un número (puede ser float) entre 1 y 4.

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

 

MÉTODO: NewDocumentOTP

/v31/SignFromApp/
https://api.firmar.online/v31/SignFromApp/NewDocumentOTP

Este método te permitirá enviar documentos a firmar en el dispositivo que selecciones. Pero antes de abrir el documento, solicitará el PIN enviado mediante SMS al teléfono indicado en el nodo correspondiente.

Este método tiene el mismo input y output que método NewDocument, simplemente añadiendo un nodo al input

  • Input

ver método NewDocument. Solamente se le añade el nodo OTP, con los siguientes parámetros:

otpWindowSize: 10, ventana de tiempo que dura el PIN. Cada entero son 30 segundos. Por defecto, el valor 10 supone 5 minutos
otpSystemSms: 2, operador mediante el que se envía el SMS
otpUser: “usuario@plataforma”, del operador de SMS
otptPassword: “ZH18sdfd”, del operador de SMS
otpFrom: “FirmaOnline”, texto que aparecerá como sender del SMS. Máximo 11 caracteres sin acentos.
otpText: “Introduzca el código ##OTP## para acceder al documento”, texto que aparecerá como mensaje del SMS. Máximo 70 caracteres sin acentos.
otpSendTo: “555634233”, numero de teléfono al que se envia el PIN- SMS

  • Output
    ver método NewDocument.

MÉTODO: GetDocument

https://api.firmar.online/v31/SignFromApp/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)
800 error en la gestión del documento en el dispositivo

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: