Guía rápida de integración para la Firma Presencial

El siguiente documento tiene como objetivo dar detalles de las configuraciones y parámetros básicos para poder integrar la funcionalidad de la firma digitalizada manuscrita en tus aplicaciones de negocio mediante API Rest.

Arquitectura de la solución

Pasos a seguir

Te dejamos aquí los pasos a seguir para realizar la integración mediante API en tu empresa, pero si lo prefieres puedes visitar este enlace interactivo en el que te lo mostramos de manera más detallada.

Descárgate la colección API Rest para utilizarla en tus peticiones.
Regístrate en nuestra WebApp: app.firmar.INFO (este es el entorno Sandbox para pruebas)
Genera tu API-Key (desde ajustes de la WebApp)
Solicita tu paquete de firmas a tu contacto comercial
Listo. Ya podrás consumir los cuatro servicios del PSC:
- Firma Remota (enviar a firmar)
- Firma Presencial (firmar en el dispostivo asociado)
- eFirma

Nota: Para realizar el paso a PRODUCCIÓN solo deberás modificar el endpoint y actualizar tu API Key.

Firma presencial

En esta sección revisaremos el API Rest y su uso para invocar la funcionalidad de firma digitalizada manuscrita.
Esta solución permite enviar documentos a un dispositivo móvil que tenga instalada la aplicación de edatalia SIGNply.

Seguimiento de los envíos: WebHook

Desde la WebApp podrás informar una URL a la que la plataforma informará los cambios de estado de los documentos. De esta manera podrás lanzar tu petición GET en el momento adecuado.

Ingresa a la WebApp
Ve a «Intregación API»
En la sección WebHook agrega la URL deseada y guarda el cambio

Asocia los dispositivos donde podrás visualizar y firmar los documentos:

Desde tu dispositivo Móvil descárgate la aplicación SFA firmar.online

Desde la WebApp ve a la pestaña Dispositivos (en firma presencial) y haz click en «asociar dispositivo»

Desde SFA permite el uso de la cámara y captura el código QR mostrado en la WebApp

Conociendo la API

La colección pública contiene ejemplos de peticiones que comparten la misma estructura y parámetros de configuración.
La colección invoca distintas VARIABLES.
- Si estás utilizando POSTMAN, estas variables están pre-configuradas para usar como referencia.
Lo PRIMERO. Modificar la variable API-KEY que has generado en la WebApp en el paso anterior.
- Tendrás 2 API – Key, una para Producción y otra para SandBox.
El endpoint contiene la variable: /…/…
Dependiendo del ambiente en el que quieras firmar, debes modificar la variable :
- Sandbox: https://restapi.firmar.info
- Producción: https://restapi.firmar.online

Firma Presencial – SignFromApp

Dentro de esta carpeta estan los métodos para comenzar un proceso de firma. En todos los casos al lanzar los métodos en la respuesta se devuelve un ID de documento/sobre que será necesario para recuperar del mismo.

Carpeta Nuevo Documento
- A01 – Nuevo_Documento: Este método POST permite lanzar una petición y que el documento se visualice en el dispositivo móvil.
Carpeta Ciclo de vida del documento
- Obtener estado del documento – Este método GET devuelve un resultado numérico con el estado del documento:
  0 None
  100 Created
  200 In Process
  300 Completed
  400 Canceled
  500 Rejected
  600 Deleted
  700 Expired
- Cancelar Proceso: Este método PUT cancela el proceso.
Carpeta Fin de Ciclo
- Obtiene los dispositivos asociados – Este método GET devuelve los ID de los dispositivos asociados al API-Key que esta realizando la petición.
- Obtener Histórico de documentos: Permite recuperar los ID y nombre de los envíos realizados con la API – Key.

Los parámetros básicos

Los parámetros de configuración básicos que modifican los envíos realizados son:

{ "deviceId": Aqui va el ID del dispositivo al que queremos enviar el documento. Lo podemos averiguar desde el dispositivo, desde la WebApp o realizando la petición "Obtener los dispositivos Asociados",
    "document": {
    "name": "Titulo del documento",
    "b64PDFContent": El documento informado en Base 64,
    "description": "Descripción del Documento PDF a firmar",
    "id": Este campo permite informar un nombre personalizado a la petición para luego poder recuperar el documento con este ID },
    "widget": { "customtext" :
                  [ { "text": Texto personalizado que ira en el widget de la firma. Se puede repetir esta linea para lograr incorporar más texto.],
     "text": Ubicación de la firma flotante. Aqui puedes informar la palabra a buscar en el documento
     "gapX": posicionamiento con desfasaje en el eje X,
     "gapY": posicionamiento con desfasaje en el eje Y,
     "width" : Ancho del widget de firma,
     "height" : Alto del widget de firma} ,
     "autoOpen": Valor: true o false. Esta opción fuerza la apertura del documento o en contrario permite dejar en la bandeja de entrada de SIGNply los documentos para que sean abiertos manualmente.}

Ejemplo de llamada completa

IMPORTANTE: El valor de los siguientes parámetros no es modificable.

"sendMethod": 4,
"authtype": 0,
"actionType": 30,

Un ejemplo de llamada sería el siguiente:

curl --location 'https://restapi.firmar.info/PSC/v40/DocumentSet/simple' \
--data-raw '{
    "documentSetName": "Nombre que queremos dar al envío",
    "description": "Descripcion que se podra visualizar en la App, bajo el nombre del documento",
    "sendermail": "noresponda@firmar.online",
    "Sendername": "Nombre del emisor - firmar.online",
    "expirationDaysTimeout": 3,
    "sendMethod": 4,
    "document": {
        "name": "Nombre que queremos dar al documento",
        "b64PDFContent": "PDF en Base64"
    },
    "recipient": {
        "name": "Nombre del firmante",
        "deviceId": "Identificador del dispositivo de firma",
        "authtype": 0,
        "actionType": 30,
        "widget": {
            "customtext": [
                {
                    "text": "Documento firmado digitalmente",
                    "fontSize": 3
                },
                {
                    "text": "Firmante: Nombre del firmante",
                    "fontSize": 3
                },
                {
                    "text": "Fecha ISO: ##TIMESTAMP##",
                    "fontSize": 2
                }
            ],
            "page": 99,
            "x": 50,
            "y": 10,
            "width": 100,
            "height": 50
        }
    }
}'