SET: new message set

for ONE or SEVERAL signatories and for ONE or SEVERAL DOCUMENTS

Latest update: 2022-01-12

This service explains how to define a new SET with a single document to be signed by several signatories.

Service

  • Method: POST
  • Service: /documents/api/v3/set
  • Content Type: application/type JSON en el Body de la request.
  • Input params: MessageSet
MessageSet{
  groupCode    string
  expires    string($date-time)
  recipients    [Recipient{}]
  customization    {}
  messages    [Message{}]
  metadataList    [Param{}]
}
  • Response Content Type: application/type JSON in the Body of the response.
  • Response Status: 200 OK
  • Response Body:
{
        "code": "string",
      "status": "string",
    "messages": [Message{}]
}
  • Response Status: Other than 200 NO OK
  • Response Body:
{
       "code": 9,
       "type": "String",
    "message": "string",
      "trace": "string"
}

MessageSet Description

  • groupCode: (string) required.
  • title (string) optional.
  • description (string) optional.
  • expires: (integer - epoch timestamp in milliseconds) optional; you can define a process expiration date expressed in milliseconds. If omitted, the expiration date defined in the API configuration will be considered, and if it is not defined, the expiration date configured in the properties of the group.
  • retryTime: (integer) optional; number of reminders measured in days that are automatically notified by the system. Reminders stop being sent when the process ends or expires. For example, a retryTime of 2 means that a reminder will be sent every 2 days.
  • retryCount: (integer) optional; maximum number of reminders to be sent.
  • recipients: Recipient array to define the list of recipients/signers of the request. See definition of this object below.
  • customization: required; it will help you to customize the SET request notifications, which will prevail over the custom notifications that the templates involved may have. See definition of this object below.
  • messages: required; Message array, where you can define templates, documents and other elements linked to the SET. See definition of this object below.
  • metadataList: optional; Param array to define the metadata linked to the SET. See definition of this object below.
  • userCode: (string) optional; User code sending the request.
  • externalCode: (string) optional; External code associated with the SET, typically used to associate a system's own identifier that is integrated with Documents.
  • externalStatus: (string) optional; External status associated with the SET.
  • AutoFinalize: (boolean) optional; Auto-finalize the request upon OTP-SMS or OTP-Mail block signature, if there are no more mandatory evidences or attachments to be filled in.
  • callbackMails: (string); Used to send mails to users not recipients (more information at https://doc.viafirma.com/documents/api/latest/en/response_callback.html).
  • callbackURL: (string); Used to inform via POST to the specified URL each time the SET status is changed. URLs that are secured with Basic Auth can be used, in which case the "callbackAuthorization" param should be used (more information at https://doc.viafirma.com/documents/api/latest/en/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'

Example

{
  "groupCode" : "<here_your_groupCode>",
  "recipients": [
    {
      "key": "FIRMANTE_01_KEY",
      "phone": "<here_mobile_with_prefix>",
      "mail": "<here_email_recipient_1>",
      "name": "Nombre firmante 1",
      "id": "DNI o Cédula firmante 1"
    },{
      "key": "FIRMANTE_02_KEY",
      "phone": "<here_mobile_with_prefix>",
      "mail": "<here_email_recipient_2>",
      "name": "Nombre firmante 2",
      "id": "DNI o Cédula firmante 2"
    }
  ],
  "metadataList" :[{
          "key" : "FIRMANTE_01_NAME",
          "value" : "Juan Gil"
    },{
          "key" : "FIRMANTE_02_NAME",
          "value" : "Susana Mora"
    }],
  "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>"
      },
      "metadataList" :[{
          "key" : "metadata_doc01_01",
          "value" : "test_value_doc01_01"
      }]
  }]
}

Recipient Description

Recipient{
  key    string
  mail    string
  phone string (optional)
  name    string (optional)
  id    string (optional)
  order integer (optional)
  presential boolean (optional)
}
  • key: (string) (required); unique identifier of the recipient/signer. It has to match the identifier recipientKey defined in the evidence or signatures to be attached by the recipient/signatory.
  • mail: (string) (required); email notifying the unique link for this recipient.
  • phone: (string) available as a property that you can use at the metadata level. It is not yet implemented to notify the SET via SMS as it is done with individual messages. For future versions this property will be used to notify via SMS..
  • name: (string) (optional); name of recipient/signatory.
  • id: (string) (optional); identifier of the recipient/signatory, such as ID card, passport, identity card, etc.
  • order: (integer) (optional); specifies the order in which this signer will receive the notification to access the signing process.
  • presential (boolean) (optional); if true, the response will include an unique signature link for this recipient, without any email notification. This option is similar to Embedded Signature process, used with/message/dispatch. This feature is available from v3.6.44.

IMPORTANT: all these properties are available in the dynamic settings of notifications and policies. For example, you can define in the signature properties a text such as: signature.

Customization Description

Customization{
 smsFrom             string (optional)
 requestMailSubject         string (required)
 requestMailBody         string (required)
 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
}

MetadataList Description

Param{
  key    string
  value    string
 }
  • key: (string) metadata identifier;
  • value: (string) metadata value;

Message Description

NOTE: to explain the use of SET we will not explain all the properties and possibilities of using this Message object, but only the minimum necessary properties. If you want to explore all the properties of the object we recommend you to make use of Swagger and go through the description of the whole model.

Message{
  document    Document{}
  metadataList     Param{}
}

results matching ""

    No results matching ""