Firma desatendida

Última revisión: 24 Diciembre 2024

El API de Viafirma Documents te permite definir SETs con Política de firma desatendida, con certificado digital, lo que denominamos como SERVER en la definición de la política de firmas.

"signatures" : [ {
    "type" : "SERVER"
}

Cuando la política de firma de un SET solo incluye una firma desatendida no es necesario registrar a ningún firmante (recipient) en el SET. La solicitud de firma pasará automáticamente a un proceso asíncrono encargado de procesar la firma.

El certificado digital configurado para la firma desatendida podrá estar instalado en algunas de las siguientes ubicaciones:

• Viafirma Fortress
• Viafirma Documents (backend)

Formatos de firma admitidos

• Formatos admitidos para PDF: PADES_B, PADES_T,PADES_LT,PADES_LTA
• Formatos admitidos para XML: XADES_B, XADES_T, XADES_LT, XADES_LTA

Firma desatendida con método asíncrono

El servicio genera una solicitud y devuelve un código del proceso, a partir del cual podrá ser consultado el estado de la firma y en cuyo caso, se podrá solicitar el link de descarga. Recomendado para procesos de alta concurrencia o procesos en lote.

• SERVICIO: {urlbase}/documents/api/v3/set
• METHOD: POST
• CONTENT/APPLICATION: JSON

{
    "groupCode": "string",
    "recipients": [
        {}
    ],
    "messages": [
        {
            "document": {
                "templateType": "base64",
                "templateReference": "<base64_content>"
            },
            "metadataList": [
                {
                    "key": "string",
                    "value": "string"
                }
            ],
            "policies": [
                {
                    "signatures": [
                        {
                            "type": "SERVER"
                        }
                    ]
                }
            ]
        }
    ]
}

Donde:

• groupCode string (obligatorio)

• recipients (obligatorio)

  NOTA: en casos de uso de firma desatendida debes mantener en la estructura de tu payload el objeto recipients, pero sin ningún elemento. Es importante que ninguna política de firma esté asignada a un recipient.

• 
  Para pasar el documento en tu llamada al API puedes optar por las siguientes opciones:
  
  * ```templateType```: string (obligatorio) Valores disponibles: ```base64,url,messsage,uploaded
  

  • templateReference: string (required) Valores disponibles: base64_value,URL_value,messageCode,token

  También puedes hacer uso de plantillas previamente definidas, para cuyo caso podrás hacer uso del documento incluido en la plantilla por referencia:

  • templateCode: string (obligatorio) template_code_sample_001

  NOTA: si haces uso de plantillas para un caso de uso de firma desatendida asegúrate de no incluir ningún tipo de evidencias electrónicas en la configuración de las políticas, ni tampoco el uso de formularios. En los procesos de firma desatendida no son válidos mecanismos en los que deba participar un firmante.

• policies signatures:
  • type: string (obligatorio) Valor para firma desatendida: SERVER
  • typeFormatSign: string (opcional) si no se informa se aplica el formato definido por defecto en el sistema. En caso contrario, los valores disponibles son los siguientes: PADES_B,PADES_T,PADES_LT,PADES_LTA,XADES_B,XADES_T,XADES_LT,XADES_LTA

Response

200 OK

{
    "code": "string",
    "status": "string",
    "messages": [
        {
            "code": "string",
            "status": "string",
            "policies": [
                {
                    "signatures": [
                        {
                            "type": "SERVER",
                            "code": "string",
                            "status": "PENDING",
                            "lastUpdated": 0
                        }
                    ]
                }
            ]
        }
    ]
}

En la respuesta obtendrás el código asignado a tu SET, con el que podrás hacer seguimiento del estado:

Ej. "code": "ZK4B1693412686160T897"

La respuesta al SET incluirá un array de documentos (messages), tantos como hayas incluido en tu SET. Recuerda que un SET te permite firmar 1 ó N documentos. Este código individual te servirá no solo para la descarga del documento firmado sino para conocer el estado de su firma.

Ej. "code": "ZK4B1693412686178R908"

        {
            "code": "ZK4B1693412686178R908",
            "status": "RECEIVED",
            "policies": [
                {
                    "signatures": [
                        {
                            "type": "SERVER",
                            "code": "ZK4B1693412686178R908P001S001",
                            "status": "PENDING",
                            "lastUpdated": 0
                        }
                    ]
                }
            ]
        }

Si tu caso de uso también necesita informar una URL al que se debe informar cuando el proceso finalice consulta los capítulos Callback de respuesta automática, relativos al uso del callbackURL, atributo que de igual forma podrás usar en tus proceso de firma desatendida.

Firma desatendida con certificado en Fortress

Si tienes acceso a un certificado en Viafirma Fortress, también podrás utilizarlo para realizar una firma desatendida. Para ello incluye el identificador de ese certificado en tu petición.

    {
        "groupCode": "groupCode",
        "recipients": [
            {
            }
        ],
        "messages": [
            {
                "document": {
                    "templateType": "url",
                    "templateReference": "{{pdf_url_sample}}"
                },
                "policies": [
                    {
                        "signatures": [
                            {
                                "type": "SERVER",
                                **"certificateId": "12345678"**,
                                "typeFormatSign": "PADES_T",
                                "stampers": [
                                    {
                                        "type": "QR_BARCODE128",
                                        "width": 300,
                                        "height": 38,
                                        "xAxis": 0,
                                        "yAxis": 0,
                                        "page": 1
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }

Para más información de como hacerlo o saber cuál es el código que debes usar, consulta en el siguiente apartado.