SET: Nueva solicitud de firma

Este servicio permite crear una nueva solicitud de firma (SET) para uno o varios documentos, que pueden ser firmados por uno o varios destinatarios.

Solicitud (Request)

Método y URL POST https://{urlbase}/documents/api/v3/set

Cabeceras (Headers)

El cuerpo de la solicitud de firma debe contener un objeto JSON

JSON del SET(Solicitud de firma)

A continuación se describen las claves utilizadas en el cuerpo en la solicitud de firma.

Clave Recipient

Define a cada uno de los firmantes o destinatarios de la solicitud.

Clave Message

Contiene la información del documento a firmar.

Clave Document

Respuestas (Responses)

Ejemplos de solicitud de firma.

A continuación se muestra un ejemplo para crear una solicitud con dos documentos y dos firmantes. Esta solicitud usa una plantilla de configuración del documento. Puedes ver como configurar tu propia plantilla en la web de Viafirma Documents usando el siguiente enlace.

{
  "groupCode": "MY_GROUP_001",
  "title": "Acuerdo de servicio - Lote 123",
  "description": "Solicitud de firma con dos documentos y dos firmantes",
  "recipients": [
    {
      "key": "signer01",
      "name": "Ana Pérez",
      "mail": "[email protected]",
      "phone": "+34123456789"
    },
    {
      "key": "signer02",
      "name": "Luis García",
      "mail": "[email protected]",
      "phone": "+34987654321"
    }
  ],
  "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" }
      ],
      "policies": [
        {
          "signatures": [
            { "type": "CLIENT", "recipientKey": "signer01" },
            { "type": "CLIENT", "recipientKey": "signer02" }
          ]
        }
      ]
    },
    {
      "document": {
        "templateType": "pdf",
        "templateCode": "ANEXO_01"
      },
      "policies": [
        {
          "signatures": [
            { "type": "CLIENT", "recipientKey": "signer01" },
            { "type": "CLIENT", "recipientKey": "signer02" }
          ],
          "attachments": []
        }
      ]
    }
  ]
}

Respuesta Exitosa (Success)

Código de estado: 200 OK

Cuerpo de la respuesta:

{
  "code": "string",
  "status": "string",
  "messages": [
    {
      "code": "string",
      "status": "string",
      "policies": []
    }
  ]
}

Respuesta de Error (Error)

Código de estado: 4xx o 5xx (distinto de 200)

Cuerpo de ejemplo:

{
  "code": 999,
  "type": "String",
  "message": "Descripción del error",
  "trace": "Detalles del error"
}

Para consultar el listado de errores, visita el siguiente enlace.

En el siguiente enlace puedes ver ejemplos de las diferentes solicitudes de fima que puedes realizar y las respuestas que debes recibir.

Notas y buenas prácticas

• Para firma desatendida (server-side) se utiliza el mismo endpoint, ajustando las políticas a tipo SERVER.
• Se recomienda usar callbackURL para recibir notificaciones automáticas de cambio de estado. También podrás consultar el estado de un callbackURL e incluso realizar un reenvío en caso de error.
• Para pruebas rápidas, puede usarse templateType: "url" apuntando a un PDF público.
• Si se sube un archivo al entorno sandbox, primero se solicita el enlace (GET /uploads/link/pdf), se realiza el PUT del archivo y luego se usa el token devuelto como templateReference.