Operations for Interacting with Viafirma Documents Using a Table Field and Related Documents – Athento

The following operations describe how to interact with Viafirma Documents to perform custom requests, different from what the native integration of both products allows.

These operations rely on table-type fields that store dynamic configuration for requests you want to make from Athento for a group of documents.

Perform Signature Requests

This operation allows you to send signature requests using a table-type field that specifies the signatories and the documents they need to sign.

Below is an example of a table-type field and its structure.

The operation to install is

op_viafirma_document_request_table_metadata_v2

Once installed, it needs to be configured. The columns in the table will be used to configure the operation's parameters.

Here is a translation of the parameters of the operation. When the parameter requires the name of a column in the table, you should use the internal name of that column, as shown in the image above.

Attachments column identifier: Unique identifier of the column that will contain the names of the forms that will be requested as attachments.
Documents column identifier: Unique identifier of the column that will contain the names of the documents whose signature will be requested from the user. These names must correspond to those of the attached documents and must be unique.
Maximum number of reminders: The maximum number of reminders that will be sent.
Notification type: The type of notification that will be sent to the signatory.
Number of reminders: The number of reminders sent by ViaFirma measured in days.
OTP type: Field to indicate whether it is used (indicating the type) or not used.
Phone number column identifier: Unique identifier of the column that will contain the phone number.
Request description: Description of the request.
Request title: Title of the request.
Signature column identifier: Unique identifier of the column that will contain the information about the status of the signature of the documents by the signatory.
Signature order column identifier: Unique identifier of the column that will contain the signing order.
Signer email column identifier: Unique identifier of the column that will contain the email of the signatory.
Signer first name column identifier: Unique identifier of the column that will contain the first name of the signatory.
Signer second name column identifier: Unique identifier of the column that will contain the second name of the signatory if they have one.
Signer first surname column identifier: Unique identifier of the column that will contain the first surname of the signatory.
Signer second surname column identifier: Unique identifier of the column that will contain the second surname of the signatory.
Signer identification number column identifier: Unique identifier of the column containing user identifiers.
Table field: Field that defines the table.
Template code: Code of the template that can be used in the request process (Optional).
Put signature stamp on the document: Mark "Yes" if you want the document to carry the stamp with the signatories.
Stamper type: Select the type of stamp you want.
Signature stamper rotation: Enter the rotation at which you want the stamp to appear on the document.
Stamper position on the X axis: Enter the position on the X axis where you want the stamp to appear on the document.
Stamper position on the Y axis: Enter the position on the Y axis where you want the stamp to appear on the document.
Stamper page on the document: Enter the page of the document where you want the stamp to appear (put -1 if you want it to appear on the last page).
Stamper time zone: Enter the date format you want to appear on the stamp.
Url to redirect the user: URL to which the user will be redirected when they finish their signing process.
OTP notification text: Text that will be displayed in the OTP message.
Parameters for customizing sending messages:
- Request SMS body: Text that will be sent as an SMS when making a request.
- Request mail body: Text or HTML that defines the "body" of the email.
- Callback mail success subject: Text that defines the subject when the request is successfully completed.
- Callback mail success body: Text or HTML that defines the "body" when the request is successfully completed.
- Callback mail expired subject: Text that defines the subject when the request has expired.
- Callback mail expired body: Text or HTML that defines the "body" when the request has expired.
- Callback mail reminder subject: Text that defines the subject when the request is resent.
- Callback mail reminder body: Text or HTML that defines the "body" when the request is resent.

Note: Custom HTML messages allow the use of fields, sent_date, document_list, and ViaFirma's own metadata.

Signature Order

When the operation is executed, a call is made to ViaFirma Documents with all related documents to be signed. The documents will be signed in the imposed order. Until users with a lower order have not signed the documents, notifications for signing will not be sent to other users.

In this example, "Related 1.pdf" and "Related 2.pdf" will be sent to the first user. Until this user completes the signing process, the documents will not be sent to the next user.

Resend Requests per Signer

The operation that allows resending a reminder to all signers who have not completed the signing process is:

op_viafirma_document_resend_notification_recipient_v1

Operation parameters to configure:

Notification type: Type of notification that will be sent to the signer.
Phone number column identifier: Unique identifier of the column that contains the phone number.
Signature column identifier: Unique identifier of the column that contains information about the signature status for each signer.
Signer email column identifier: Unique identifier of the column that contains information about the signer's email.
Table field: Field that defines the table.
Way to obtain the signers: Method of obtaining the signers to whom the signature notification will be resent.
- To all signers whose signature is pending: It will be sent to all signers whose signature status is "PENDING."
- Row ID (must be sent in the data of the request): It will be sent to the signer of the indicated row. Note: for the use of this type of option, it must be done under a request, in the request (submission) of the operation, the row should be sent in the body. Example of body: {'rowId': 'row1'}
  - Example of request: <host>/file/api/file/<document_uuid>/run_operation/?op_uuid=<operation_uuid>&rowId=<row_id> where:
    - document_uuid: Unique identifier of the document where it will be launched.
    - op_uuid: Unique identifier of the operation.
    - row_id: Unique identifier of the row in the table field. This identifier can be found in the value of the field under the key DT_RowId.

Updating data or documents in Athento or Callback operations

The "callback" operations are operations that cannot be executed manually. They are executed when ViaFirma calls the generic callback URL at message level. These operations must be installed and configured before carrying out any process, because they work after a Viafirma callback and in case they are not installed or configured for this signature process, the callback information/process will be lost.

Update the requests

op_viafirma_document_message_callback_update_signature_status_table_metadata_v1

This operation allows the status to be updated after a "callback" from viafirma.

The parameters that must be configured for its operation are:

Signature column identifier: Unique identifier of the column that will contain the information of the signature status per signer.
Table field: Field that defines the table.

Download the signed document

op_viafirma_document_message_callback_download_binary_v1

This operation allows the content (binary) of the document that has been signed to be updated and thus have the document signed on the Athento platform.

It is not necessary to configure any parameter.

NOTE: This "callback" operation is only executed when the signature process is "RESPONSED" (documentation).

Download attachments

op_viafirma_document_message_callback_download_attachment_v1

This operation allows the attachments uploaded by the signers in the signing process to be downloaded and listed in Athento.