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.
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.
POST
https://app.firmafy.com/ApplicationProgrammingInterface.php
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | login |
usuario | string | (Usuario Firmafy) |
password | string | (Clave Firmafy) |
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
error | bool | true/false |
data | string | token |
{
"error": false,
"data": "xxxxxxxxxxxxxxxxTOKENxxxxxxxxxxxxxxxx"
}
El siguiente paso es obtener el public_key (id_show) para enviar solicitudes desde la API. Para usuarios registrados en Firmafy podrás ubicarlo en el menú “Configuración” de tu Panel Cliente.
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:
POST
https://app.firmafy.com/ApplicationProgrammingInterface.php
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | request |
token | string | su token |
id_show | string | id_show |
signer1 | string | array de firmantes en jSON |
pdf 2 | CURLFile | documento original a firmar |
document_lang 3 | string | Opcional - idioma de notificación |
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 array signer de dos firmantes, uno como Persona Física y otro como Persona Jurídica.
[
{
"nombre": "Wence Criado",
"nif": "12345678A",
"cargo": "Trabajador",
"email": "soporte@firmafy.com",
"telefono": 600000000,
"type_notifications": "email"
},
{
"nombre": "Fran Cortes",
"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 |
---|---|
nombre | Nombre Completo |
nif | DNI / NIE |
cargo | Etiqueta identificativa del firmante |
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
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:
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
pdf_name | string | Nombre del archivo |
pdf_base64 | string | PDF codificado en base64 |
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
pdf_name | string | Nombre del archivo |
pdf_url | string | Url del documento PDF |
document_lang
Si se quiere notificar bajo otro idioma diferente a Español ( por defecto, no hay que indicar el parámetro en español ), indicar como valor el idioma deseado disponible:
Valor Parámetro | Descripción |
---|---|
EN | Inglés |
IT | Italiano |
CA | Catalán |
FR | Francés |
IT | Italiano |
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 |
---|---|---|
template_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.
Existe la posibilidad de indicar Plantilla para utilizar las coordenadas de los elementos y además, pasar como parámetros el asunto y el mensaje (sobreescriben a los de la plantilla).
Para ello utilizar los siguientes parámetros:
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
3 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 | 1/0 (Omite enviar notificación de solicitud de firma, si es true por defecto no enviar parámetro) |
fecha_vencimiento | datetime | Y-m-d H:i:s (Pasada la fecha, no se puede firmar) |
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:
side
puede ser 1 o 0 (ver ejemplo) e indica un giro de 90º en el cuadro de firma para la firma lateral.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
}
]
]
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"
}
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.
POST
https://app.firmafy.com/ApplicationProgrammingInterface.php
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | webhook |
id_show | string | identificador del usuario |
token | string | token de inicio de sesion |
type4 | int | Evento al que se desea suscribir |
method5 | int | Método de envío de datos |
url_webhook | string | url donde Firmafy enviará la respuesta |
type
Hay 2 tipos de evento para suscribirse:
method
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 del POST en HTTP que se devuelve es la siguiente:
{
"type":"Firmar Documento"(string),
"daterequest":"2021-02-09 16:02:34", (datetime)
"datesign":"2021-02-09 16:07:25", (datetime),
"status":"FIRMADO", (string)
"subject":"Firmafy | Solicitud de Firma", (string)
"csv":"xxxxxxxxxxxxxx", (string)
"size":"35687",(int)
"sender":"SYSTEM TEST",(string)
"filename":"Documento.pdf", (string)
"docoriginal": pdf, (multipart form-data)
"docsigned": pdf, (multipart form-data)
"docaudit": pdf, (multipart form-data)
"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"
}
]
}
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"
}
soporte@firmafy.com
y así formar parte de la comunidad de Dev’s en nuestro canal de SLACK.