Referencia de la API

La API de FIRMAFY expone interfaces de arquitectura REST orientadas a la integración multiplataforma. Permite a los sistemas cliente solicitar flujos de firma electrónica y escuchar eventos asíncronos del proceso.

Para facilitar las pruebas de integración en entornos de desarrollo, proporcionamos una colección interactiva:

1. Obtención del Token de Sesión

El protocolo de autenticación inicial requiere la generación de un JWT/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.

Parámetros de la Petición (Payload):

Respuesta

Ejemplo de respuesta con Login correcto:

{
    "error": false,
    "data": "xxxxxxxxxxxxxxxxTOKENxxxxxxxxxxxxxxxx"
}

2. Obtener Public Key (id_show)

El siguiente paso es obtener el public_key (id_show) para enviar solicitudes desde la API. Este hash actúa como la Llave Pública (Public Key) que vincula la solicitud entrante con su cuenta de cliente (Tenant ID). Para usuarios registrados en Firmafy podrás ubicarlo en el menú "Configuración" de tu Panel Cliente.

3. Solicitud de Firma Electrónica

Con el Token y el id_show ya se puede realizar la solicitud de firma. Soporta firmas simples, avanzadas con OTP y biométricas.

Modalidades de envío del PDF

Resto de Parámetros de la Transacción:

Estructura del Objeto: signer (Array de Firmantes)

Contiene la estructura del o de los firmantes para los que se realiza la solicitud de firma, aportando los datos necesarios para garantizar la integridad legal del proceso.

Ejemplo de inicialización del parámetro signer:

[
  {
    "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"
  }
]

Especificación Técnica del Parámetro: coordenadas

Si opta por indicar manualmente la ubicación exacta de los cuadros de firma omitiendo las plantillas preestablecidas, debe estructurar un mapa bidimensional respetando las siguientes directrices criptográficas y de maquetación:

• Escala y Dimensiones: Se toma como referencia un lienzo físico estándar A4, medido en milímetros (mm), con dimensiones tope de 210mm x 297mm (ejes x, y).
• Punto de Origen: El punto de anclaje de referencia es la esquina superior izquierda del folio (coordenadas 0,0). El dibujo del contenedor se renderiza hacia abajo y hacia la derecha.
• Dimensiones Recomendadas: El cuadro técnico de firma posee un estándar óptimo de 40mm x 15mm (ancho x alto).
• Indexación de Firmantes: El parámetro signer dentro del objeto debe coincidir estrictamente con el orden de asignación declarado en el array principal de firmantes (empezando en index 1).
• Propiedad side (Giro): Admite valores numéricos booleanos (1 o 0). Indican una rotación matemática de 90 grados en el cuadro de firma, utilizado comúnmente para la incrustación limpia de firmas en los márgenes laterales del documento.
• Tratamiento por Hojas: Cada página del documento original se representa mediante un array independiente que encapsula sus respectivos cuadros de firma. Se debe enviar un array por cada página del PDF de forma secuencial, dejando elementos vacíos ([]) si una hoja no requiere firma visual.

Ejemplo de Maquetación de un PDF de 3 páginas:

[
    [
        {
            "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
        }
    ]
]

Envío Multidocumento: attachment y force_flatten

Permite enviar varios PDF en una única solicitud de firma. Los firmantes, el asunto, el mensaje y el resto de parámetros de la transacción son comunes a todos los documentos.

Estructura del parámetro attachment

Array JSON (o JSON String) con un objeto por documento. El orden del array es el orden de los documentos.

Parámetro force_flatten

Define cómo se tratan los documentos de attachment. Sólo tiene efecto junto a attachment.

Criterios comunes

• Cada adjunto se descarga o decodifica y se valida como PDF. Si alguno falla, se rechaza toda la solicitud.
• El tamaño que se compara con el almacenamiento disponible del plan es la suma de todos los adjuntos.
• En modo multidocumento, template_name no se aplica. Sí se aplican subject, message y signer_priority.
• En modo multidocumento sin coordenadas, se coloca un cuadro de firma por firmante en el lateral izquierdo de todas las páginas de todos los documentos.

Coordenadas en multidocumento

Cuando los documentos se firman por separado, coordenadas añade un nivel más: un array por documento, que contiene un array por página, que contiene los cuadros de firma.

• El número de elementos del primer nivel debe coincidir exactamente con el número de adjuntos.
• Cada documento debe incluir exactamente un array por cada una de sus páginas.
• Cada cuadro de firma debe incluir, como mínimo, signer, side, x e y. Las medidas y el resto de propiedades son las mismas que en el envío de un único documento.
• Diferencia importante: una página enviada vacía ([]) no queda sin firma, sino que recibe los cuadros de firma por defecto en el lateral izquierdo.

Errores específicos del envío multidocumento

Ejemplo de attachment con dos documentos:

[
    {
        "id": "contrato",
        "filename": "Contrato.pdf",
        "url": "https://www.ejemplo.com/contrato.pdf"
    },
    {
        "id": "anexo",
        "filename": "Anexo.pdf",
        "base64": "JVBERi0xLjQKJ..."
    }
]

Ejemplo de coordenadas para esos dos documentos (2 y 1 páginas):

[
    [
        [
            { "signer": 1, "x": 5, "y": 120, "side": 1, "width": 40, "height": 15 }
        ],
        [
            { "signer": 1, "x": 30, "y": 250, "side": 0, "width": 40, "height": 15 },
            { "signer": 2, "x": 120, "y": 250, "side": 0, "width": 40, "height": 15 }
        ]
    ],
    [
        [
            { "signer": 2, "x": 80, "y": 210, "side": 0, "width": 40, "height": 15 }
        ]
    ]
]

Respuesta de Solicitud Correcta:

{
    "error": false,
    "message": "Documento Enviado",
    "data": "xxxxxxx"
}

4. Solicitud Email Certificado

Endpoint para el despacho de correos electrónicos con certificación criptográfica de entrega y trazabilidad de lectura, sin requerimiento de intervención de firma manuscrita por parte del receptor. Requiere el Token y el id_show obtenidos previamente.

Parámetros de la Petición:

Ejemplo 4.1 de datos del destinatario:

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

Ejemplo 4.2 de archivo adjunto (Opción 1 — cURL File):

curl -X POST https://app.firmafy.com/ApplicationProgrammingInterface.php \
  -F "action=emailrequest" \
  -F "token=tu_token_de_sesion" \
  -F "id_show=tu_public_key" \
  -F "subject=Asunto del email" \
  -F "body=Cuerpo del mensaje" \
  -F "to={\"name\":\"Jhon Smith\",\"email\":\"soporte@firmafy.com\"}" \
  -F "attachment=@/ruta/al/archivo.pdf"

Ejemplo 4.3 de tratamiento de archivos adjuntos (Opción 2):

[
  {"filename": "Doc1.pdf","url": "xxxxx"},
  {"filename": "Doc2.pdf","base64": "base64"}
]

Payload Mínimo Completo (Estructura Base):

{
  "action": "emailrequest",
  "token": "tu_token_de_sesion",
  "id_show": "tu_public_key",
  "subject": "Notificación Importante",
  "body": "<h1>Hola</h1><p>Este es un email certificado.</p>",
  "to": "{\"name\":\"Jhon Smith\",\"email\":\"soporte@firmafy.com\"}"
}

5. Solicitud SMS Certificado

Endpoint para el despacho de mensajes cortos (SMS) con valor probatorio legal (certificación de entrega). Requiere el Token y el id_show obtenidos previamente.

Parámetros de la Petición:

Ejemplo 5.1 de datos del destinatario:

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

Payload Mínimo (Estructura Base):

{
  "action": "smsrequest",
  "token": "tu_token_de_sesion",
  "id_show": "tu_public_key",
  "body": "Recuerde su cita mañana a las 10:00H.",
  "to": "{\"name\":\"Jhon Smith\",\"country\":34,\"phone\":612345678}"
}

6. Suscripción a Eventos (Webhooks)

Para obtener los cambios de estado que se produzcan en la solicitudes, es necesario estar suscrito a los eventos de Webhook. Elimina la necesidad de hacer *polling* continuo.

Parámetros de Suscripción:

6.1.1 Control de Reintentos: 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.

Nota: 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.

Ejemplo del POST en HTTP que se devuelve:

{
 "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",
 "filename":"Documento.pdf", 
 "docoriginal": "pdf (multipart form-data)", 
 "docsigned":  "pdf (multipart form-data)", 
 "docaudit": "pdf (multipart form-data)", 
 "signer":[
    {
      "name":"xxxxxx",
      "phone":"xxxxx",
      "nif":"xxxxxxx",
      "email":"soporte@firmafy.com",
      "status":"ACTIVO",
      "compliance":"true/false",
      "datesign":"2021-02-09 16:06:32"
    }
 ]
}

Payload Mínimo para Suscribirse (Ejemplo):

{
  "action": "webhook",
  "token": "tu_token_de_sesion",
  "id_show": "tu_public_key",
  "type": 1,
  "method": 2,
  "url_webhook": "https://api.tu-servidor.com/firmafy-listener"
}

7. Invalidar una Solicitud de Firma

Esta acción desactiva los enlaces de los firmantes que haya pendientes de firma, bloqueando el acceso al documento.

Parámetros de la Petición:

Payload Mínimo (Estructura Base):

{
  "action": "invalidar_documento",
  "token": "tu_token_de_sesion",
  "csv": "xXXXXXXXXXX"
}

8. Obtener Consumo Disponible (Balance)

Este endpoint permite obtener el consumo disponible de tu cuenta.

Parámetros de la Petición:

Ejemplo de Respuesta:

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

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.