API FIRMAFY

La API de FIRMAFY se ha planteado como una herramienta multiplataforma que permitirá a nuestros clientes la integración de nuestro servicio con sus sistemas, de manera que puedan enviar documentación a sus clientes, comprobar el estado de las firmas, y demás operaciones mediante una interfaz rápida, segura, y fácil de integrar.

Para realizar las pruebas de integración puedes apoyarte en nuestro proyecto de POSTMAN.

Importante - Para otros idiomas diferentes a español , no traducir el nombre de los parámetros.

1. OBTENER TOKEN

En primer lugar para trabajar con la API es necesario obtener el token de acceso. Recomendamos antes de iniciar el proceso, ponerse en contacto con el equipo de soporte técnico de Firmafy a través del chat, para confirmar que se disponen de permisos de llamada.

Método:

POST

URL:

https://app.firmafy.com/ApplicationProgrammingInterface.php

Parámetros:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
action	string	login
usuario	string	(Usuario Firmafy)
password	string	(Clave Firmafy)

Respuesta

Ejemplo de respuesta con Login correcto

{
    "error": false,
    "data": "xxxxxxxxxxxxxxxxTOKENxxxxxxxxxxxxxxxx"
}

2. OBTENER ID USUARIO

El siguiente paso es obtener el id (id_show) sobre el que se va a hacer la solicitud de firma.

Método:

POST

URL:

https://app.firmafy.com/ApplicationProgrammingInterface.php

Parámetros:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
action	string	Consultar_Cliente_Nif
token	string	(su token)
cif	string	(su cif/dni)

Respuesta

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
error	bool	true/false
message	string	(mensaje que aporta información adicional)
data	Object	(información con el parámetro id_show )

Ejemplo de respuesta con id devuelto correctamente

	"error": false,
	"message":"Cliente",
    "data": {
        
        "id_show": "25x1x2bxxx2fdaxeedx3730x9f8cxxxx"
    }

3. SOLICITUD DE FIRMA

Con el Token y el id_show ya se puede realizar la solicitud de firma.

Los parámetros obligatorios para realiar una solicitud de firma son los siguientes:

Método:

POST

URL:

https://app.firmafy.com/ApplicationProgrammingInterface.php

Parámetros:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
action	string	request
token	string	su token
id_show	string	id_show
¹signer	string	array de firmantes en jSON
²pdf	CURLFile	documento original a firmar

¹ PARÁMETRO `signer` ( Array de Firmantes )

El parámetro signer contiene la estructura del o de los firmantes para los que se realiza la solcitiud de firma. Ha de contener aquellos datos necesarios para que Firmafy pueda garantizar la integridad del firmante. A continuación se muestra un signer de dos firmantes, uno como Persona Física y otro como Persona Jurídica.

[
  {
    "role": "PERSONA FISICA",
    "nombre": "Wence Criado",
    "nif": "12345678A",
    "cargo": "Trabajador",
    "email": "soporte@firmafy.com",
    "telefono": 600000000,
    "empresa": "",
    "cif": "",
    "type_notifications": "email"
  },
  {
    "role": "PERSONA JURIDICA",
    "nombre": "Crismary Ramírez",
    "nif": "98765432B",
    "cargo": "Responsable",
    "email": "hola@firmafy.com",
    "telefono": 777777777,
    "empresa": "FIRMAFY",
    "cif": "B11111111",
    "type_notifications": "email,sms"
  } 
]

Al igual que en la aplicación web, para realizar la solicitud de firma son obligatorios los datos personales:

Nombre Parámetro	Valor Parámetro
role	PERSONA FISICA / PERSONA JURIDICA
nombre	Nombre Completo
nif	DNI / NIE
cargo	Etiqueta identificativa del firmante
email	Email para notificar al firmante
telefono	Móvil del firmante donde recibe el OTP
empresa	Nombre de empresa ( Si es P. JURÍDICA )
cif	Cif Empresa ( Si es P. JURÍDICA)
type_notifications	*Medio por el que recibe el aviso de firma (email y/o sms)

*Hay que prestar mucha atención al parámetro type_notifications ya que la vía de notififación puede ser diferente para cada firmante, solo en caso de que se use "type_notifications" : "sms" el parámetro email puede ir vacío. Esta notificación es para avisar de la solicitud de firma y de la copia del documento firmado. El OTP siempre se envíará por SMS

² PARÁMETRO `pdf`

Existen otras opciones además de CURl para enviar el documento PDF, para ello habría que omitir el parámetro pdf anterior y utilizar los siguientes en función del que se elija:

Enviar en base64:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
pdf_base64	string	PDF codificado en base64
pdf_name	string	Nombre del archivo

Enviar a través de una url pública:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
pdf_url	string	Url del documento PDF
pdf_name	string	Nombre del archivo

3.1 PARÁMETROS OPCIONALES A LA SOLICITUD DE FIRMA

Con los parámetros anteriores ya tendríamos los elementos suficientes para hacer una solicitud de firma, aunque existen otros parámetros opcionales para personalizar la solicitud.

A continuación se muestran todos los parámetros disponibles y en qué consiste cada uno.

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
templante_name	string	Nombre Plantilla

Podemos utilizar una Plantilla creada en plataforma para que vía API podamos utilizar el Asunto y el Mensaje del email que queremos que reciban nuestros firmantes, además de utilizar la ubicación de los elementos de firma en el documento.

MUY IMPORTANTE, siempre que se utilice una PLANTILLA, el número de hojas del documento a enviar tiene que coincidir con el número de hojas de la PLANTILLA creada.

Si no se indica template_name, se utilizarán el Asunto y Mensaje predeterminados de Firmafy , además de ubicar la firmas en el lateral izquierdo de todas las páginas.

Existe la posibilidad de no utilizar Plantilla y de indicar manualmente la ubicación de las firmas, además del asunto y el mensaje de la solicitud. Para ello utilizar los siguientes parámetros:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
³ coordenadas	string	JSON con ubicación de firmas
subject	string	Asunto del Email
message	string	Mensaje del Email
cco	string	Indica los emails donde requiere enviar copia del PDF firmado ( separados por ; )
signer_priority	bool	Activa la firma en orden
mail_notification	bool	true/false (Omite enviar notificación de solicitud de firma)
fecha_vencimiento	datetime	Y-m-d H:i:s (Pasada la fecha, no se puede firmar)

³ PARÁMETRO `coordenadas`

Si se quiere indicar las coordenadas vía API de la ubicación de las firmas, hay que tener en cuenta las siguientes reglas:

Usamos tamaño A4, la escala debe ser medida en milímetros, siendo el máximo de medidas 210x297mm (x,y)
El punto que se toma como referencia corresponde a la esquina superior izquierda, desde allí comenzamos a dibujar.
El tamaño recomendado para el cuadro de firma es de 40x15mm (ancho x alto)
Se debe indicar el número del firmante siguiendo el mismo orden que en el array de firmantes.
La propiedad side puede ser 1 o 0 (ver ejemplo) e indica un giro de 90º en el cuadro de firma para la firma lateral.
Una página puede tener tantos cuadros de firma como se necesiten, incluso repetir el mismo firmante, siempre que se indique la posición correcta.
En una página no es necesario incluir todos los firmantes si no es necesario.
Por cada página se debe construir un array que contenga los cuadros de firma de la misma.
Se debe pasar un array para cada página.

A continuación se muestra un ejemplo de un documento de 3 páginas, la primera página tiene 2 cuadros de firma ubicados en el lateral y la tercera página sólo tiene un cuadro de firma del segundo firmante.

[
    [
        {
            "signer": 1,
            "x": 5,
            "y": 120,
            "side": 1,
            "width": 40,
            "height": 10
        },
        {
            "signer": 2,
            "x": 5,
            "y": 170,
            "side": 1,
            "width": 45,
            "height": 15
        }
    ],
    [],    
    [ 
        {
            "signer": 2,
            "x": 80,
            "y": 210,
            "side": 0,
            "width": 45,
            "height": 15
        }
    ]
]

3.2 Ejemplo de respuesta de solicitud enviada correctamente

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
error	bool	true/false
message	string	(mensaje que aporta información adicional)
data	string	(CSV del documento)

{
    "error": false,
    "message": "Documento Enviado",
    "data": "xxxxxxx"
}

4. Obtener el estado del envío a través del Webhook

Para obtener los cambios de estado que se produzcan en la solicitudes de firma y así obtener el documento firmado y la auditoría, es necesario estar suscrito a los eventos de Webhook.

Método:

POST

URL:

https://app.firmafy.com/ApplicationProgrammingInterface.php

Parámetros:

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
action	string	addWebhook
id_show	string	identificador del usuario
token	string	token de inicio de sesion
⁴ type	int	Tipo de evento al que se desea suscribir
url_webhook	string	url donde Firmafy enviará la respuesta

⁴ PARÁMETRO `type`

Hay 2 tipos de evento para suscribirse:

1 : Documento Firmado ( Cuando todos los firmantes han firmado el documento )
2 : Aviso de Firma Completada ( Cuando alguno de los firmantes ha firmado el documento )

No es necesario suscribirse al evento por cada solicitud, ya que si la URL a notificar es la misma en todas las solicitudes, bastaría con hacerlo solo 1 vez.

Un ejemplo de la estructura JSON que se devuelve es la siguiente:

{
 "type":"Firmar Documento",
 "daterequest":"2021-02-09 16:02:34",
 "datesign":"2021-02-09 16:07:25",
 "status":"FIRMADO",
 "subject":"Firmafy | Solicitud de Firma",
 "csv":"xxxxxxxxxxxxxx",
 "size":"35687",
 "sender":"SYSTEM TEST",
 "docsigned":"https://drive.google.com/uc?id=xxxxxxxxxxxxxxxxxxx&export=download",
 "docaudit":"https://drive.google.com/uc?id=xxxxxxxxxxxxxxxxxxxx&export=download",
 "signer":"[array]"
}

Por cada firmante:

[
 {
  "name":"xxxxxx",
  "phone":"xxxxx",
  "nif":"xxxxxxx",
  "email":"soporte@firmafy.com",
  "status":"ACTIVO",
  "compliance":"true/false",
  "datesign":"2021-02-09 16:06:32"
 }
]

5. Invalidar una Solicitud de Firma

Esta acción desactiva los enlaces de los firmantes que haya pendientes de firma

Nombre Parámetro	Tipo Parámetro	Valor Parámetro
action	string	invalidar_documento
token	string	(su token)
csv	string	CSV del documento

Ejemplo:

{
  "action":"invalidar_documento",
  "token":"",
  "csv":"xXXXXXXXXXX"
}

Recomendamos que para la integración de la API, se pongan en contacto con nuestro servicio de soporte técnico `soporte@firmafy.com` y así formar parte de la comunidad de Dev’s en nuestro canal de SLACK.

API FIRMAFY

1. OBTENER TOKEN

Método:

URL:

Parámetros:

Respuesta

2. OBTENER ID USUARIO

Método:

URL:

Parámetros:

Respuesta

3. SOLICITUD DE FIRMA

Método:

URL:

Parámetros:

1 PARÁMETRO signer ( Array de Firmantes )

2 PARÁMETRO pdf

3.1 PARÁMETROS OPCIONALES A LA SOLICITUD DE FIRMA

3 PARÁMETRO coordenadas

3.2 Ejemplo de respuesta de solicitud enviada correctamente

4. Obtener el estado del envío a través del Webhook

Método:

URL:

Parámetros:

4 PARÁMETRO type

5. Invalidar una Solicitud de Firma

Recomendamos que para la integración de la API, se pongan en contacto con nuestro servicio de soporte técnico soporte@firmafy.com y así formar parte de la comunidad de Dev’s en nuestro canal de SLACK.

¹ PARÁMETRO `signer` ( Array de Firmantes )

² PARÁMETRO `pdf`

³ PARÁMETRO `coordenadas`

⁴ PARÁMETRO `type`

Recomendamos que para la integración de la API, se pongan en contacto con nuestro servicio de soporte técnico `soporte@firmafy.com` y así formar parte de la comunidad de Dev’s en nuestro canal de SLACK.