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 PUBLIC KEY

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.

3. SOLICITUD DE FIRMA

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

Los parámetros obligatorios para realizar 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
signer1 string array de firmantes en jSON
pdf 2 CURLFile documento original a firmar
document_lang 3 string Opcional - idioma de notificación

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 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 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_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

3 PARÁMETRO 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

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
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)

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. Solicitud Email Certificado

Requiere el Token y el id_show obtenidos previamente.

Los parámetros obligatorios para realizar un envío de email certificado son:

Método:

POST

URL:

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

Parámetros:
Nombre Parámetro Tipo Parámetro Valor Parámetro
action string emailrequest
token string su token
id_show string id_show
subject string Asunto de email de notificación
body string Cuerpo del Mensaje, puede contener código HTML
to 4.1 string Datos del destinatrio JSON Stringify
lang 4.2 char Opcional - Idioma de la solicitud, notificaciones y Auditoría.
attachment 4.3 file/array Opcional - Archivo adjunto a la solicitud

4.1 Ejemplo de datos destinatario:

{
  "name":"Jhon Smith",
  "email": "soporte@firmafy.com"
  
}

4.2 Idioma Notificaciones:

ES - Por defecto (no hace falta indicarlo)

EN - Inglés

IT - Italiano

FR - Francés

CA - Catalán

4.3 Adjuntos:

Tipo Parámetro Valor Parámetro
file cUrl object
Tipo Parámetro Valor Parámetro
array [{"filename": "Doc1.pdf","url": "xxxxx"},{"filename": "Doc2.pdf","base64": "base64"}]

5. Solicitud SMS Certificado

Requiere el Token y el id_show obtenidos previamente.

Los parámetros obligatorios para realizar un envío de SMS certificado son:

Método:

POST

URL:

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

Parámetros:
Nombre Parámetro Tipo Parámetro Valor Parámetro
action string smsrequest
token string su token
id_show string id_show
body string Texto del mensaje, máximo 160 caracteres
to 5.1 string Datos del destinatrio JSON Stringify
lang 5.2 char Opcional - Idioma de la auditoría

5.1 Ejemplo de datos destinatario:

{
  "name":"Jhon Smith",
  "country":34,
  "phone":612345678
}

5.2 Idioma Auditoría:

ES - Por defecto (no hace falta indicarlo)

EN - Inglés

IT - Italiano

FR - Francés

CA - Catalán

6. Suscripción a eventos - Webhook

Para obtener los cambios de estado que se produzcan en la solicitudes, 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 webhook
id_show string identificador del usuario
token string token de inicio de sesion
type6.1 int Evento al que se desea suscribir
method6.2 int Método de envío de datos
url_webhook string url donde Firmafy enviará la respuesta

6.1 PARÁMETRO type

Hay 2 tipos de evento para suscribirse:

6.1.1 Firmafy escucha los códigos de respuesta HTTP de su servidor para determinar que la entrega del webhook es exitosa o no. Todas las notificaciones que reciban como respuesta un status http 4xx o 5xx se registran como fallidas. Firmafy intentará entregar nuevamente la notificación hasta en 2 ocasiones más, cada 30 minutos.

6.2 PARÁMETRO 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"
	 }
	]
}

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"
}

6. Obtener consumo disponible

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 balance
id_show string identificador del usuario
token string token de inicio de sesion

Ejemplo de Respuesta:

{
    "error": false,
    "message": "Disponibles",
    "credits": 50,
    "sms": 25,
    "mb": 20.331583,
    "days": 23
}

En caso de realizar una solicitud de firma a la API y no disponer de créditos dipsonibles , se devuelve un mensaje:

{
"error": true,
    "message": "Se ha alcanzado el numero máximo de envios disponibles en su plan. En caso de querer adquirir un nuevo plan, visite www.firmafy.com/tarifas y pongase en contacto con su proveedor" 
}

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.