Firma en bloque

Última revisión: 12 Diciembre 2025

Desde el API se permite crear solicitudes de firma en bloque asociadas a un usuario (o firmante) a partir de las solicitudes pendientes de firma que tenga el mismo agrupándolas en una única solicitud de firma. Estos documentos se podrán firmar según la configuración con un certificado centralizado en Viafirma Fortress o mediante un OTP SMS.

Agrupar solicitudes pendientes de firma

El servicio genera una solicitud de firma a partir de todas las solicitudes pendientes de firma asociadas al {userCode} indicado, el servicio devolverá un link donde, en función de la configuración se permitirá firmar todas las solicitudes en estado WAITING_CLIENT_SIGNATURE.

  • SERVICIO: {urlbase}/documents/api/v3/messages/batchLink
  • METHOD: POST
  • CONTENT/APPLICATION: JSON
{
  "userCode":"string",
  "groupCode":"string",
  "otpRecipient": "string",
  "index": 0,
  "max": 0,
  "signType": "string",
  "redirectURL": "string",
  "setCode": "string"
}

Parámetros

  • userCode (required) : código de usuario o recipientKey al que esté asociado el documento en estado WAITING_CLIENT_SIGNATURE
  • groupCode (required) : código de grupo
  • otpRecipient (optional) : email o móvil al que se mandará el OTP en caso de seleccionar firma OTP
  • index (optional) : índice del páginado a mostrar para la firma en bloque
  • max (optional) : número máximo de documentos a firmar
  • signType (optional) : mecanismo de firma en bloque autorizado. Valores permitidos:
    • FORTRESS: Firma con certificado centralizado.
    • OTP_SMS: Firma mediante código OTP.
    • CLIENT: Firma mediante aplicación local.
    • SIGNATURE: Firma digitalizada (captura de rúbrica en pantalla). Nota: El usuario realiza el trazo de su firma una única vez y esta se aplica automáticamente a todos los documentos del lote.
    • null: Permite todos los mecanismos y el usuario final elige.
  • redirectURL (optional) : URL a la que redirigirá una vez completado el proceso de firma
  • setCode (optional) : código del SET que se quiere firmar. Si se informa, el bloque se limita a los documentos de ese SET y la respuesta detalla en excludedMessages los que han quedado fuera. Si no se informa, el comportamiento es el histórico: se agrupan todos los documentos pendientes del usuario en el grupo, pertenezcan al SET que pertenezcan.

IMPORTANTE

El enlace devuelto es una foto del instante: la lista de documentos se fija al construirlo, viaja dentro del token y no se recalcula después. Un documento sólo entra en el bloque si en ese momento está en estado WAITING (o WAITING_CLIENT_SIGNATURE cuando signType es CLIENT).

Al crear un SET los documentos quedan en estado RECEIVED, que significa recibido y encolado: todavía falta generarlos y dejarlos firmables, y ese procesado es asíncrono. Por eso, antes de pedir el enlace hay que esperar a que todos los documentos estén listos, consultando GET {urlbase}/documents/api/v3/set/summary/{setCode} hasta que:

  • messages tenga tantos elementos como documentos se enviaron,
  • ningún messages[].status valga RECEIVED (todos en WAITING),
  • abortando si aparece ERROR, EXPIRED o MAX_ERROR_REACHED.

Consultar el estado del SET (GET /v3/set/status/{setCode}) no sirve para esta espera: tanto el estado del SET como el de sus destinatarios se escriben al crearlo, antes de procesar ningún documento.

Ejemplo

{
  "userCode": "[email protected]",
  "groupCode": "group001",
  "index": 0,
  "max": 10,
  "signType": "SIGNATURE",
  "redirectURL": "https://mi-empresa.com/fin"
}

Ejemplo acotado a un SET

Mismo servicio, informando setCode para firmar únicamente los documentos de un envío concreto:

{
  "userCode": "[email protected]",
  "groupCode": "group001",
  "index": 0,
  "max": 10,
  "signType": "SIGNATURE",
  "redirectURL": "https://mi-empresa.com/fin",
  "setCode": "C3AS1781794739341T745"
}

Respuesta cuando el SET tiene tres documentos pero uno sigue procesándose:

{
  "code": "C3AS1781794739349R114",
  "link": "https://sandbox.viafirma.com/sign-page/batch/C3AS1781794739349R114",
  "scheme": "viafirmadesktop://sign?code=C3AS1781794739349R114",
  "total": 2,
  "messageCodes": [
    "C3AS1781794739349R114",
    "C3AS1781794739349R115"
  ],
  "evidenceCodes": [
    "C3AS1781794739349R114P001E001",
    "C3AS1781794739349R115P001E001"
  ],
  "excludedMessages": [
    { "messageCode": "C3AS1781794739349R116", "status": "RECEIVED" }
  ]
}

El bloque incluye dos de los tres documentos: el tercero seguía en RECEIVED, es decir, encolado y todavía sin generar. Esperando a que GET {urlbase}/documents/api/v3/set/summary/{setCode} no devuelva ningún documento en RECEIVED antes de pedir el enlace, excludedMessages habría llegado vacío y total habría sido 3.

Respuesta

  • RESPONSE: 200 HTTP status code 200/OK
  • RRESPONSE CONTENT TYPE: application/json
{
  "code": "string",
  "link": "string",
  "scheme": "string",
  "total": 0,
  "messageCodes": [ "string" ],
  "evidenceCodes": [ "string" ],
  "excludedMessages": [
    { "messageCode": "string", "status": "string" }
  ]
}
  • code: código identificativo de la solicitud
  • link: URL de la solicitud de firma en bloque
  • scheme: URL para apertura por protocolo de la aplicación de escritorio (si es necesario)

Respuestas Error

Respuestas alternativas en caso de fallo: se devolverán HTTP status codes distintos de 200/OK. En ese caso siempre se devolverá un JSON con la descripción del problema:

    {
      "code": "string",
      "type": "string",
      "message": "string",
      "trace" : "string"
    }

results matching ""

    No results matching ""