SET: nuevo conjunto de mensajes

para UNO o VARIOS firmantes y para UNO o VARIOS DOCUMENTOS

Última revisión: 14 Jun 2022

En este servicio te explicamos cómo definir un nuevo SET con un único documento que debe ser firmado por varios firmantes.

Servicio

  • Método: POST
  • URL Base para Sandbox: https://sandbox.viafirma.com/documents
  • Servicio: urlbase/api/v3/set
  • Content Type: application/type JSON en el Body de la request.
  • Params de entrada: MessageSet
MessageSet{
  groupCode     string
  title          string (since api v3.7.0)
  description     string (since api v3.7.0)
  expires     integer (epoch timestamp in milliseconds)
  retryTime      integer
  retryCount     integer (since api v3.7.20)
  recipients     [Recipient{}]
  customization     {}
  messages     [Message{}]
  metadataList     [Param{}]
  externalCode   string (since api v3.7.14)
  externalStatus string (since api v3.7.14)
  userCode     string (since api v3.7.14)
  autoFinalize string (since api v3.7.26)
  callbackMails string (since api v3.7.32)
  callbackURL string (since api v3.7.31)
  callbackAuthorization string (since api v3.7.31)
  callbackRedirectURL string (since api v3.7.41)
  callbackRedirectURLTargetWindow string (since api v3.7.41)
}
  • Response Content Type: application/type JSON en el Body de la response.
  • Response Status: 200 OK
  • Response Body:
{
  "code": "string",
  "status": "string",
  "messages": [Message{}]          
}
  • Response Status: Distinto de 200 NO OK
  • Response Body:
{
       "code": 9,
       "type": "String",
    "message": "string",
      "trace": "string"
}

Descripción de MessageSet

  • groupCode: (string) obligatorio.
  • title (string) opcional.
  • description (string) opcional.
  • expires: (integer - epoch timestamp in milliseconds) opcional; puedes definir una fecha de expiración del proceso expreasada en milisegundos. Si se omite se tomará en cuenta la fecha de expiración definida en la configuración del API, y si ésta no la tiene definida, se tendrá en cuenta la configurada en las propiedades del grupo.
  • retryTime: (integer) opcional; número de recordatorios medidos en días que el sistema notifica automáticamente. Los recordatorios dejan de enviarse cuando el proceso finaliza o caduca. Por ejemplo, un retryTime de 2 significa que cada 2 días se enviará un recordatorio.
  • retryCount: (integer) opcional; número máximo de recordatorios que se enviarán.
  • recipients: array de Recipient para definir la lista de destinatarios/firmantes del proceso. Ver definición de este objeto más abajo.
  • customization: obligatorio; te ayudará a personalizar las notificaciones del proceso SET, que prevalecerán sobre las notificaciones personalizadas que pudieran tener las plantillas involucradas. Ver definición de este objeto más abajo.
  • messages: obligatorio; array de Message, donde podrás definir las plantillas, documentos y otros elementos asociados al SET. Ver definición de este objeto más abajo.
  • metadataList: opcional; array de Param para definir los metadatos asociados al SET. Ver definición de este objeto más abajo.
  • userCode: (string) opcional; Código de usuario que envía la solicitud.
  • externalCode: (string) opcional; Código externo asociado el SET, se suele utilizar para asociar un identificador propio del sistema que se integra con Documents.
  • externalStatus: (string) opcional; Estado externo asociado al SET.
  • autoFinalize: (boolean) optional; Se autofinaliza la petición al realizar la firma en bloque de OTP-SMS o de OTP-Mail, si no hay mas evidencias o adjuntos obligatorios que rellenar.
  • callbackMails: (string) opcional; Se utiliza para informar de una lista de correos separados por coma donde se notificará al final del proceso, enviando según configuración el documento firmado y/o el fichero de audit trail (más información en https://doc.viafirma.com/documents/api/latest/es/response_callback.html).
  • callbackURL: (string) opcional; Se usa para informar mediante un POST a la URL indicada cada vez que se cambia el estado del SET. Se pueden usar URLs que estén securizadas con Basic Auth, en cuyo caso habría que usar el param “callbackAuthorization” (más información en https://doc.viafirma.com/documents/api/latest/es/response_callback.html).
  • callbackAuthorization: (string) opcional; Si la URL a la que haremos POST está securizada, se pueden definir las credenciales haciendo uso de este atributo, indicando la seguridad BASIC o X-Api-Key con uno de los siguientes formatos:
    • Basic {your_bearer_token}
    • X-Api-Key:{your_token}
  • callbackType: (string) opcional; Si queremos que el callback se realice con el JSON directamente en el body de la petición POST se puede indicar este atributo con valor 'JSON'
  • callbackRedirectURL (string) opcional; Si queremos redirigir a una URL externa cuando finalice el proceso.

Ejemplo

{
  "groupCode" : "<here_your_groupCode>",
  "title" :     "<here_your_title>",
  "description" : "<here_your_description>",
  "recipients": [
    {
      "key": "signer01",
      "phone": "<here_signer01_mobile_with_prefix>",
      "mail": "<here_signer01_email>",
      "name": "<here_signer01_name>",
      "id": "<here_signer01_id>"
    },{
      "key": "signer02",
      "phone": "<here_signer01_mobile_with_prefix>",
      "mail": "<here_signer02_email>",
      "name": "<here_signer02_name>",
      "id": "<here_signer02_id>"
    }
  ],
  "customization": {
    "requestMailSubject": "Contrato listo para firmar",
    "requestMailBody": "Hola {{recipient.name}}. <br /><br />Ya puedes revisar y firmar el contrato. Haz click en el siguiente enlace y sigue las instrucciones.",
    "requestSmsBody": "En el siguiente link puedes revisar y firmar el contrato"
  },
  "messages" : [{
      "document" : {
      "templateCode" : "<templateCode_1>"
    }
  },{
      "document" : {
      "templateCode" : "<templateCode_2>"
    }
  }]
}

Descripción de Recipient

Recipient{
  key    string
  mail    string (optional)
  phone string (optional)
  name    string (optional)
  id    string (optional)
  order integer (optional)
  presential boolean (optional)
  userCode string (optional) (since api v3.7.0)
  deviceCode string (optional) (since api v3.7.0)
  notificationType string
  appCode string (since api v3.7.14)
  label string (since api 3.7.7)
  optional boolean (since api 3.7.8)
  callbackType string (since api 3.7.29)
}
  • key: (string) (obligatorio); identificador único del destinatario/firmante. Tiene que coincidir con el identificador recipientKey definido en las evidencias o firmas que deban ser completadas por este destinatario/firmante.
  • mail: (string) (opcional); email en el que se notificará el link único para este destinatario.
  • phone: (string) disponible como propiedad que podrás usar a nivel de metadatos. También se utilizará para notificar el link único para este destinatario vía SMS si el atributo notificationType es SMS.
  • name: (string) (opcional); nombre del destinatario/firmante.
  • id: (string) (opcional); identificador del destinatario/firmante, como DNI, pasaporte, cédula, etc.
  • order: (integer) (opcional); indica el orden el que este firmante recibirá la notificación para acceder al proceso de firma.
  • presential: (boolean) (opcional); si se activa el servicio devuelve para cada firmante un link único de acceso a la página de firma. Esta opción es la equivalente al servicio /message/dispatch utilizado para firmas embebidas en sistemas de terceros. Propiedad disponible a partir de v3.6.44. A partir de la versión 3.7.32 si los firmantes tienen esta propiedad a true la solicitud se realizará de forma sincrona, de manera que hasta que no esté generado el documento no se devolverá la respuesta.
  • userCode: string (optional) usuario registrado en Viafirma que recibirá el SET en la APP de su dispositivo móvil
  • deviceCode: string (optional) dispositivo registrado en Viafirma que recibirá el SET en la APP de su dispositivo móvil
  • appCode: string (optional) codigo de aplicación registrado en Viafirma para identificar la APP instalada en su dispositivo móvil
  • notificationType: string (optional) indica el tipo de notificación que recibira el firmante. Valores: MAIL, MAIL_SMS o SMS. El valor por defecto es MAIL
  • callbackType: string (optional) indica el tipo de notificación de respuesta que recibira el firmante. Valores: MAIL, MAIL_SMS, SMS o NONE. El valor por defecto es MAIL
  • label: string (optional) alias que sepuede indicar al firmante para usarlo como variable.
  • optional: boolean (optional) este parámetro sirve para la firma solidaria. Si hay mas de un firmante al que hemos indicado optional=true, la solicitud se podrá completar con la firma de cualquiera de los firmantes sin necesitar que todos firmen la solicitud.

IMPORTANTE: todas estas propiedades están disponibles en la configuración dinámica de notificaciones y políticas. Por ejemplo, podrás definir en las propiedades de la firma un texto como este: Firma de.

Descripción de Customization

Customization{
 smsFrom             string (optional)
 requestMailSubject         string (optional)
 requestMailBody         string (optional)
 requestSmsBody            string (optional)
 callbackSmsBody         string (optional)
 callbackMailSuccessSubject     string (optional)
 callbackMailSuccessBody     string (optional)
 callbackMailExpiredSubject     string (optional)
 callbackMailExpiredBody     string (optional)
 callbackMailWaitingCheckSubject string (optional)
 callbackMailWaitingCheckBody     string (optional)
 callbackMailRejectedSubject     string (optional)
 callbackMailRejectedBody     string (optional)
 callbackMailErrorSubject    string (optional)
 callbackMailErrorBody        string (optional)
 callbackSmsReminderBody    string (optional)
 callbackMailReminderBody    string (optional)
 callbackMailReminderSubject    string (optional)
 successMessage    string
}

Descripción de MetadataList

Param{
  key    string
  value    string
 }
  • key: (string) identificador del metadato;
  • value: (string) valor del metadato;

Descripción de Message

NOTA: para la explicación del uso de SET no se explicarán todas las propiedades y posibilidades de uso de este objeto Message, solo las propiedades mínimas necesarias. Si quieres explorar todas las propiedades del objeto te recomendamos que hagas uso de Swagger y navegues por la descripción del modelo completo.

Message{
  document    Document{}
  metadataList     Param{}
}

results matching ""

    No results matching ""