firmafy_api

Logo

View the Project on GitHub devgrupo2000/firmafy_api

Firmafy para desarrolladores

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.

Empezamos la integración: Login

Descripción:

Lo primero que debemos obtener para comenzar a operar con la API de Firmafy es el token que nos autenticará en el sistema. La validez del token será de 4 horas.

Un ejemplo de ello puede verse a continuación:

URL:

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

Método:

POST

Parámetros:
Nombre Parámetro Tipo Parámetro Valor Parámetro
action string login
usuario string (su usuario)
password string (su clave)
Respuesta
Nombre Parámetro Tipo Parámetro Valor Parámetro
error bool true/false
data string token 
{
    "error": false,
    "data": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Obtener id usuario (id_show)

Descripción:

Además de obtener el token que nos permitirá autenticarnos en futuras peticiones, necesitaremos saber cual es nuestro id de usuario (id_show).

URL:

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

Método:

POST

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 del usuario entre la que está su id_show) 
    "data": {
        ...
        "id_show": "25d122ba412fda5eed63730c9f8c25f3"
    }'

Solicitar firma

Descripción:

Una vez estemos autenticados y hayamos obtenido nuestro token, podremos comenzar a solicitar las firmas de nuestros clientes al documento que elijamos. Para ello, haremos uso de la plantilla previamente creada en app.firmafy.com, en la cual ya habremos indicado la posición de las firmas para el documento que nos interese enviar.

Un ejemplo de ello puede verse a continuación:

URL:

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

Método:

POST

Parámetros:
Nombre Parámetro Tipo Parámetro Valor Parámetro
action string Solicitar_Firma
token string (su token)
signer array (array con los firmantes en json)
pdf *CURLFile (documento original a firmar)
template_name string (nombre plantilla)
send_form bool true/false)
id_show string (id_usuario)
type_notifications string email,sms
mail_notification bool true/false
fecha_vencimiento datetime Y-m-d H:i:s
Ejemplo signer:

*Se puede optar por enviar el PDF base64, en ese caso hay que sustuir el parámetro pdf por:

pdf_base64 (string) PDF codificado en base64 y añadir

pdf_name (string) Nombre del archivo

Valores posibles de “role”: PERSONA FISICA , PERSONA JURIDICA

*Importante - send_form: Indica que se trata de una plantilla de FORMULARIO, por lo que el firmante recibirá un formulario a rellenar.

*Importante - template_name: Indica el nombre de la plantilla creada previamente ( si no se indica, las firmas van el lateral de todas las páginas )

*Importante - type_notifications: para poder notificar por sms , debe de tener SMS disponibles, de lo contrario se enviará por email.

*Importante - mail_notification: se omite enviar el enlace al cliente.

Valores posibles de “cargo”: Administrador , Interesado, Empresario etc… (cualquier dato identificativo para el firmante).

A continuación se muestra un ejemplo con dos firmantes:

[
  {
    "role": "PERSONA FISICA",
    "nombre": "Jhon Smith",
    "nif": "12345678A",
    "cargo": "Gerente",
    "email": "prueba@gmail.com",
    "telefono": 666666666,
    "empresa": "",
    "cif": "",
    "type_notifications": "email"
  },
  {
    "role": "PERSONA FISICA",
    "nombre": "Jhon Smith 2",
    "nif": "98765432B",
    "cargo": "Responsable",
    "email": "prueba2@gmail.com",
    "telefono": 777777777,
    "empresa": "",
    "cif": "",
    "type_notifications": "email,sms"
  } 
]
Respuesta
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"
}
Excepciones

Si se produjese alguna excepción, obtendríamos en la respuesta el valor de error a true y el valor de message variará en función de la excepción producida, aportando información sobre la misma, para que podamos depurar dicho error.

Ejemplo de excepciones controladas:

Consultar estado envío

Agregar Respuesta Automática (Webhook)

Descripción: Devuelve automáticamente la respuesta al final de proceso de firma. Indicando el CSV del documento, rutas de descarga de documento firmado, ruta de descarga de auditoría e información de los firmantes. Un ejemplo de la estructura 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 recibirás algo así:

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

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

Método: POST

CONSULTAR CON SOPORTE

Invalidar Solicitud de Firma

Función para invalidar solicitud de firma y desactivar links de los firmantes

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