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.
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:
https://app.firmafy.com/ApplicationProgrammingInterface.php
POST
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | login |
usuario | string | (su usuario) |
password | string | (su clave) |
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
error | bool | true/false |
data | string | token |
{
"error": false,
"data": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Además de obtener el token que nos permitirá autenticarnos en futuras peticiones, necesitaremos saber cual es nuestro id de usuario (id_show).
https://app.firmafy.com/ApplicationProgrammingInterface.php
POST
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | Consultar_Cliente_Nif |
token | string | (su token) |
cif | string | (su cif/dni) |
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"
}'
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:
https://app.firmafy.com/ApplicationProgrammingInterface.php
POST
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) |
*CURLFile | (documento original a firmar) | |
template_session | string | true/false |
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 |
*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 - template_sessión: Indica que las plantillas pertenecen al id_show , no al usuario logueado en la clase Firmafy.php
*Importante - send_form: Indica que se trata de una plantilla de FORMULARIO, por lo que el firmante recibirá un formulario a rellenar.
*Importante - 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"
}
]
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"
}
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:
Número de páginas distinto al de la plantilla
Plantilla no encontrada
Agregar Respuesta Automática (Webhook)
Descripción: Devuelve automáticamente la respuesta al final de proceso de firma. Indicando el CSV del documento y el estado del mismo. Por ejemplo https://dominio.com/webhook_firmafy ?csv=XXX&estado=FIRMADO
URL: https://app.firmafy.com/ApplicationProgrammingInterface.php
Método: POST
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | add_edit_webhook |
token | string | (su token) |
id_show | string | id_usuario |
url_webhook | string | url donde enviaremos la respuesta |
Para realizar esta acción es necesario contar con los privilegios correspondientes.
Cuando queramos registrar a usuarios, y seguidamente asociarle un plan deberemos hacerlo de la siguiente manera:
https://app.firmafy.com/ApplicationProgrammingInterface.php
POST
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
action | string | nc_nuevo_usuario_plan |
token | string | (su token) |
data | string | (json1) |
A continuación se muestran dos ejemplos de la estructura que debe tener el parametro data
en json
.
Para registrar y asociarle el plan a una persona física :
{
"datos_usuario": {
"email": "XXXXX"
},
"datos_contacto": {
"dni": "XXXXX",
"nombre": "XXXXX",
"primer_apellido": "XXXXX",
"segundo_apellido": "XXXXX",
"cargo": 1,
"direccion": "XXXXX",
"ciudad": "XXXXX",
"codigo_postal": "XXXXX",
"movil": 000000000,
"email": "XXXXX"
},
"producto": {
"id_producto": "XXXXX"
}
}
Para registrar y asociarle el plan a una empresa:
{
"datos_usuario": {
"email": "XXXXX"
},
"datos_facturacion": {
"nif": "XXXXX"
},
"datos_contacto": {
"empresa": "XXXXX",
"dni": "XXXXX",
"nombre": "XXXXX",
"primer_apellido": "XXXXX",
"segundo_apellido": "XXXXX",
"cargo": 1,
"direccion": "XXXXX",
"ciudad": "XXXXX",
"codigo_postal": "XXXXX",
"movil": 000000000,
"email": "XXXXX"
},
"producto": {
"id_producto": "XXXXX"
}
}
Nombre Parámetro | Tipo Parámetro | Valor Parámetro |
---|---|---|
error | bool | true/false |
message | string | (mensaje que aporta información adicional) |
data | string | (información sobre el proceso) |
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:
message
contendría el mensaje Acción no realizada a usuario existente: El usuario ya ha disfrutado del plan solicitado.
y data
El usuario ya ha disfrutado del plan solicitado. Puede ponerse en contacto con Firmafy
id_producto
incorrecto, en message
se obtendría El nombre del plan indicado no existe
message
contendrá un resumen de aquellos datos incorrectos: Error procesando el JSON: JSON incorrecto. El DNI no es correcto
y data
datos_usuario: Los datos de usuario son correctos | datos_contacto: [datos_contacto] El dni no es correcto | datos_facturacion: Los datos de facturación de LA PERSONA FÍSICA son correctos | datos_producto: El producto indicado es correcto
El formato json no es correcto
Usuario no creado. El email indicado tiene asociado otro dni. Por favor, ponte en contacto con firmafy.