firmafy_api

Logo

View the Project on GitHub devgrupo2000/firmafy_api

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

| Nombre Parámetro | Tipo Parámetro | Valor Parámetro | | —————–| ————– | ————— | | error | bool | true/false | | data | string| token |

{
    "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 )
	"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
1signer string array de firmantes en jSON
2pdf CURLFile documento original a firmar

1 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

2 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:

Nombre Parámetro Tipo Parámetro Valor Parámetro
pdf_base64 string PDF codificado en base64
pdf_name string Nombre del archivo
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
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 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)

3 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:

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
4 type int Tipo de evento al que se desea suscribir
url_webhook string url donde Firmafy enviará la respuesta

4 PARÁMETRO type

Hay 2 tipos de evento para suscribirse:

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.