Ejemplos de solicitud de firma.

En Viafirma, una solicitud de firma representa un proceso mediante el cual uno o varios firmantes deben firmar uno o varios documentos. Dependiendo del escenario, puedes crear solicitudes basadas en plantillas o configurarlas manualmente, añadiendo distintos tipos de firmas y evidencias (certificado, imagen, check, OTP).

Además puedes programar acciones automatizadas como el cierre de la solicitud (autoFinalize), la ejecución de llamadas de retorno (callback), o la gestión de firmas en persona (presencial).

Casos Base

Con plantilla

Crea una solicitud de firma a partir de una plantilla ya predefinida en Viafirma Documents. Desde Viafirma te recomendamos utilizar plantillas siempre que sea posible.

A continuación se muestra un ejemplo para crear una solicitud con plantilla. Puedes obtener el templateCode desde el backend de Viafirma Document o obtenerlo a través del siguiente servicio.

{
    "groupCode": "MY_GROUP_001",
    "title": "Acuerdo de servicio - Lote 123",
    "description": "Solicitud de firma con plantilla",
    "recipients": [
        {
            "key": "signer01",
            "name": "Ana Pérez",
            "mail": "[email protected]",
            "phone": "+34123456789"
        }
    ],
    "customization": {
        "requestMailSubject": "Contrato listo para firmar",
        "requestMailBody": "Hola {{recipient.name}}, revisa y firma el documento.",
        "requestSmsBody": "Por favor firma tu contrato en el enlace recibido"
    },
    "messages": [
        {
            "document": {
                **"templateType": "pdf",**
                **"templateCode": "TEMPLATE_CONTRATO_V1"**
            },
            "metadataList": [
                {
                    "key": "orderId",
                    "value": "123-XYZ"
                }
            ]
        }
    ]
}

Sin plantilla

Crea una solicitud de firma desde cero añadiendo documentos y firmantes manualmente.

Descripción: A continuación se muestra un ejemplo para crear una solicitud con sin plantilla. Sube tu documento o usa un enlace con la dirección del mismos.Modifica manualmente las politicas y podrás usar diferentes tipos de firma y evidencias. | Tipo | Descripción | Campos clave | | ----------- | -------------------------------------------------- | ------------------------------ | | Certificado | Firma digital basada en certificado local o remoto | signature.type: "CLIENT" | | Imagen | Firma manuscrita en imagen | signature.type: "IMAGE" | | Check | Validación mediante check box | signature.type: "CHECK" metadataList "key" : "email","value" : "recipientKey.mail" | | OTP | Firma por email | signature.type: "GENERIC" metadataList "key" : "email","value" : "recipientKey.mail" |

En el siguiente JSON de ejemplo puedes ver como usamos cada una de estos ejemplos:

{
  "groupCode": "MY_GROUP_001",
  "title": "Acuerdo de servicio - Lote 123",
  "description": "Solicitud de firma con plantilla",
  "recipients": [
    {
      "key": "signer01",
      "name": "Ana Pérez",
      "mail": "[email protected]",
      "phone": "+34123456789"
    }
  ],
  "customization": {
    "requestMailSubject": "Contrato listo para firmar",
    "requestMailBody": "Hola {{recipient.name}}, revisa y firma el documento.",
    "requestSmsBody": "Por favor firma tu contrato en el enlace recibido"
  },
  "messages": [
    {
      "document": {
        **"templateType": "url",**
        **"templateReference": "https://host/dummy.pdf"**
      },
      "metadataList": [
        { "key": "orderId", "value": "123-XYZ" }
      ],
      ,
    "policies" : [ {
      "evidences" : [ {
        "type" : "GENERIC",
        "id" : "1760962205205",
        "enabled" : true,
        "visible" : true,
        "code" : "H1MH1760962203467R524P001E001",
        "status" : "PENDING",
        "helpText" : "Ejemplo de Código OTP por email de Ana",
        "positions" : [ {
          "rectangle" : {
            "x" : 134,
            "y" : 648,
            "width" : 125,
            "height" : 62
          },
          "page" : 1
        } ],
        "metadataList" : [ {
          "key" : "email",
          "value" : "{{signer01.mail}}",
          "internal" : false
        }, {
          "key" : "providerId",
          "value" : "Mail",
          "internal" : false
        },{
          "key" : "groupCode",
          "value" : "groupCode-mail-{{signer01.key}}",
          "internal" : false
        } ],
        "imageText" : "{{signer01.name}}\nFirmado digitalmente vía email\n{{signer01.mail}}",
        "recipientKey" : "signer01",
        "imageTextLocation" : "RIGHT",
        "imageTextSize" : 20
      }, {
        "type" : "IMAGE",
        "id" : "1760962205205",
        "enabled" : true,
        "visible" : true,
        "code" : "H1MH1760962203467R524P001E002",
        "status" : "PENDING",
        "helpText" : "Ejemplo de evidencia de imagen por Ana",
        "positions" : [ {
          "rectangle" : {
            "x" : 332,
            "y" : 614,
            "width" : 125,
            "height" : 62
          },
          "page" : 1
        } ],
        "recipientKey" : "signer01",
        "imageTextSize" : 30
      }, {
        "type" : "GENERIC",
        "id" : "1760962205205",
        "enabled" : true,
        "visible" : true,
        "code" : "H1MH1760962203467R524P001E003",
        "status" : "PENDING",
        "helpText" : "Casilla Check de Ana",
        "positions" : [ {
          "rectangle" : {
            "x" : 217,
            "y" : 539,
            "width" : 16,
            "height" : 16
          },
          "page" : 1
        } ],
        "metadataList" : [ {
          "key" : "providerId",
          "value" : "Check",
          "internal" : false
        }, {
          "key" : "text",
          "value" : "Acepto los términos y condiciones",
          "internal" : false
        }, {
          "key" : "requiredValue",
          "value" : "true",
          "internal" : false
        } ],
        "recipientKey" : "signer01",
        "imageTextSize" : 30
      } ],
      "signatures" : [ {
        "type" : "SERVER",
        "code" : "H1MH1760962203467R524P001S001",
        "status" : "PENDING",
        "helpText" : "Sello del documento",
        "stampers" : [ {
          "type" : "DEFAULT",
          "rotation" : "ROTATE_90",
          "width" : 36,
          "height" : 842,
          "xAxis" : 0,
          "yAxis" : 0,
          "page" : 1
        } ],
        "lastUpdated" : 0
      }, {
        "type" : "CLIENT",
        "code" : "H1MH1760962203467R524P001S002",
        "status" : "PENDING",
        "helpText" : "Firma con certificado digital de Ana",
        "stampers" : [ {
          "type" : "TEXT",
          "width" : 300,
          "height" : 38,
          "xAxis" : 61,
          "yAxis" : 60,
          "page" : 1
        } ],
        "lastUpdated" : 0,
        "recipientKey" : "signer01"
      } ]
    } ]
    }
  ]
}

Combinaciones

Añade múltiples firmantes añadiendo nuevos recipients. La clave "order" nos crea una secuencia en el proceso de firma.

"recipients": [
        {
            "key": "{{internalUserKey}}",
            "name": "{{internalUserName}}",
            "mail": "{{internalUserEmail}}",
            "userCode": "{{internalUserCode}}",
            "order": 1
        },
        {
            "key": "{{internalUserKey2}}",
            "name": "{{internalUserName2}}",
            "mail": "{{internalUserEmail2}}",
            "userCode": "{{internalUserCode2}}",
            "order": 2
        }
]

Añade múltiples documentos dentro del objeto messages.

"messages": [
        {
            "document": {
                "templateType": "uploaded",
                "templateReference": "{{token_file}}"
            },
            "policies": [
                {
                    "evidences": [
                        {}
                    ],
                    "signatures": [
                        {    
                        }
                    ]
                }
            ]
        },
        {
            "document": {
                "templateType": "uploaded",
                "templateReference": "{{token_anexo}}"
            },
            "policies": [
                {
                    "signatures": [
                        {
                        }
                    ]
                }
            ]
        }

Parámetros importantes

A continuación se describen los parámetros clave que pueden influir en el comportamiento de una solicitud de firma en Viafirma.

⚙️ autofinalize

Si está activado (true), el proceso se completa automáticamente una vez que todos los firmantes han firmado.
Esto resulta útil cuando no necesitas validaciones adicionales tras la última firma. Se añade al objeto principal.

Ejemplo:

{
  "groupCode": "MY_GROUP_001",
  "title": "Acuerdo de servicio - Lote 123",
  "description": "Solicitud de firma con dos documentos y dos firmantes",
  "autofinalize": true
}

💡 Consejo: si tu backend necesita procesar o validar el documento antes de cerrarlo, deja este parámetro en false.

🔁 callback

Permiten notificar a tu backend cuando el proceso de firma termina. Para más información sigue el siguiente enlace.

📨 Ejemplo de callbackUrl

{
  "groupCode": "MY_GROUP_001",
  "title": "Acuerdo de servicio - Lote 123",
  "description": "Solicitud de firma con dos documentos y dos firmantes",
  "autofinalize": true
  "callbackUrl": "https://miapp.com/firmas/callback"
}

Tu endpoint recibirá información sobre el estado final de la solicitud (SIGNED, REJECTED, EXPIRED, etc.), junto con el requestId.

🔒 Nota de seguridad: valida siempre la autenticidad del callback (por IP, token o firma digital) antes de procesar los datos en tu sistema.

📥 Descarga del documento

Puedes obtener el documento firmado mediante el endpoint de descarga:

GET /api/public/signature/{requestId}/download

Cuando tu callback avise a tu sistema de un estado finalizado , puedes descargar el documento firmado.

👥 presencial

Indica si el firmante es presencial (firma en punto físico) o firma de manera remota. Se añade al objeto recipient.

🖐️ Ejemplo de recipient presencial:

{
  "key": "{{internalUserKey}}",
  "name": "{{internalUserName}}",
  "mail": "{{internalUserEmail}}",
  "userCode": "{{internalUserCode}}",
  "order": 1,
  "presencial": true
}

💬 Caso típico: uso en oficinas donde el cliente firma físicamente asistido por un agente.