RClick

RClick permite a los usuarios de RSign integrar de forma sencilla firmas electrónicas en sus aplicaciones web, además de generar certificados de firma para los firmantes.

Este artículo incluye los siguientes temas:

• Configuración necesaria en RSign
• Configuración requerida en la aplicación web del cliente
• Pruebas funcionales

Configuración necesaria en RSign

Estos son los pasos que el administrador de la cuenta debe seguir para usar la función RClick:

1. Establezca la configuración Habilitar RClick en S (habilitado).

Cuando está habilitado, se activan dos controles adicionales: el RClick ID, que identifica de manera única la aplicación web del cliente, y el RClick Key, un código seguro que la aplicación web del cliente debe enviar a RSign durante las llamadas a la API. 

2. Habilite la configuración Mostrar el ID de control.

3. Cree una plantilla que refleje el formulario o documento donde el usuario ingresará su información y firma en la página web. Para que la plantilla se vea como la página web en la que el firmante aplicará su firma, adjunte el logotipo de su empresa al documento antes de cargarlo en la plantilla. Coloque los campos de control donde aparezcan los datos transaccionales en la página web del cliente para que contengan esa información.

4. Tome nota del código de la plantilla.

Configuración requerida en la aplicación web del cliente

Los desarrolladores de la aplicación del cliente pueden insertar un bloque de firma RClick, que es un fragmento de código JavaScript, en su aplicación web. El bloque de firma RClick les permite enviar a RSign, mediante llamadas a la API, los datos de autenticación y de la transacción que se muestran en la página web, junto con la imagen de la firma del firmante. RSign combina los datos de la transacción del cliente y la firma electrónica del firmante con el documento de la plantilla, y aplica su certificado digital para proporcionar a la aplicación que realiza la llamada un documento final firmado y la certificación de finalización.

Estos son los pasos que deben seguir los desarrolladores en la aplicación web del cliente para usar la función RClick:

1. Obtenga la estructura del payload JSON para enviar los datos de la transacción mediante una API de RSign.

Para garantizar que los datos de la transacción mostrados en la página web del cliente se asignen correctamente a la plantilla, RSign ofrece la API GetSignerControls. Esta API obtiene la estructura del payload JSON que contiene los IDs de control de todos los controles posicionados dentro del documento. Recupera el payload, asigna los valores correspondientes a los IDs de control dentro de la estructura JSON y transmítaselo a RSign mediante una llamada a la API. Para hacerlo, siga estos pasos:

- Invocar la API GetSignerControls: Para hacerlo, necesitará un token de autenticación. Para obtenerlo, instale un cliente REST desde Chrome Web Store en su navegador Chrome.

- Invocar la API Authenticate User enviando el siguiente payload:

API URL: https://api3.use.rsign.com/api/V1/Authentication/AuthenticateUser

Payload:
{
"EmailId": "johndoe@rpost.com",
"Password": "rpostpassword"
}

En el plugin, ingrese su nombre de usuario y contraseña de RSign y seleccione Post en el menú desplegable.
Luego haga click en Send Request.

El cliente del navegador enviará la solicitud y devolverá el AuthToken. Copie el contenido resaltado y consérvelo para llamadas posteriores a la API.

- Llame a la API GetSignerControl ingresando esta URL: https://api3.use.rsign.com/api/V1/Envelope/GetSignerControls/62649

Nota: El número final corresponde al código de la plantilla creada para reflejar el formulario en la página web del cliente.

En Authentication, ingrese el AuthToken que copió en el paso anterior,

Seleccione Get en el menú desplegable. Luego haga click en Send Request.

- Esta API devuelve el siguiente payload. El código de la aplicación del cliente completará los valores de los controles:

2. Inserte el bloque de firma RSign en una página web del cliente.

- Cree dos elementos DIV en el código HTML del cliente donde debe colocarse el control HTML. Nombre los elementos div como rs-Signature1 y hdnSignatureID1. 
- Inserte el fragmento de código JavaScript RClick que se muestra a continuación en la página HTML.
- Este cargará el script ‘sign.rclick.js’ proporcionado por RSign.
- Al crear la plantilla, el ID HTML del prefijo del control de firma debe ser signControl y, al invocar, se debe pasar el mismo ID HTML signControl.
- Los valores de Control ID en el payload no son obligatorios en la versión actual.

// Comments in green colors
const script= document.createElement('script');

// Set RClick external file source. This will change when the code moves to production.
script.src = ' {{Base}}/scripts/custom/sign.rclick.js'; // Change base with host URL

// Set async to true for asynchronous loading
script.async = true;

// Append the script tag to the document head
document.head.appendChild(script);

// loadRClickScript function that will be called once the script is loaded
const loadRClickScript = () => {
  const data = JSON.stringify({
    rclickId:rclickId, // Available in RSign SETTINGS -> Advanced Tab
    rclickKey:rclickKey, // Available in RSign SETTINGS -> Advanced Tab
    token:authToken, // Authentication token returned from Authenticate User API
    environment:'STG', // STG is staging env. After successful testing change to PROD.
    signControls:[{
      signControlId: 'rs-Signature1', // div control id in the client application for signature control 
      signHiddenControlId: 'hdnSignatureID1' // div control id in the client application to store the primary key of the client signature. 
    } 
]
});
rclick.run(data); // The script is loaded. Now we can use functions defined in the external file.
};

const url =
  ' {{Base}}/api/V1/Envelope/SendClickSignEnvelope'; //Base is the hostname: https://app.rsign.com
  fetch(url, {
    method: 'POST',
    headers: {
     'Content-Type': 'application/json','AuthToken': authToken 
    },
    body: JSON.stringify(submitPayload),
  })
  .then((response) => response.json()) // fetch the response from RClick API
  .then(result => {
  alert("Document digital signature completed."); // For testing purposes only. 
  let res= JSON.stringify(result);
  alert("RClick response:" + res); // For testing purposes only.
  console.log("RClick response:",result)
  return result;
  })
  .catch((error) => {
    console.log('Document read error');
  });

3. La aplicación del cliente envía la información de la transacción a RSign.
Envíe el ID de la plantilla, el asunto, el cuerpo, el rol del firmante, el nombre y el correo electrónico. Reemplace el código en rojo con el valor de “data” del payload recibido anteriormente. 

submitPayload = {
"templateID":62649,
"subject": "enter subject text here", // This value comes from popup. Signed Documents from Username
"body":"enter body text here", // This value comes from popup.

"signerList":[ 
{"roleName":"Manager","name":"John Doe","email":"johndoe@noemail.com","dataControls":[
{"controlID":"E294C207-13FD-4508-95FC-90C5D9C555FA","controlHtmlID":"signControl74069","controlValue":""}, // no need to send signcontrol value, RClick will get it from hidden control (hdnSignatureID1)
{"controlID":"76597505-F0DE-47EE-AF59-F721BE198242","controlHtmlID":"textControl41531","controlValue":"55"},
{"controlID":"76597505-F0DE-47EE-AF59-F721BE198242","controlHtmlID":"textControl41830","controlValue":"66"},
{"controlID":"76597505-F0DE-47EE-AF59-F721BE198242","controlHtmlID":"textControl56794","controlValue":"77"}]
"order": 1
}]
"sendEmail":1, // Send email when value is 1. Don’t send when it’s 0. 
"returnFinalSignedDocument":1 // Send final signed document when value is 1. Don’t send when it’s 0.
}

 response : 
{
  "StatusCode": 200, 
  "StatusMessage":"OK",
  "Success":true,
  "Message":"Success",
  "EvelopeStatus":"Completed",
  "EnvelopeCode":"54352548-4999-FAAF-3257-CACF",
  "FinalSignedDocumentInBase64":"JVBERi0xLjcKJeLjz9MKODAgMCBvYmoKPDwvQnl0ZVJhbmdlI"
}

Pruebas funcionales

Para fines de prueba, se ha implementado una página web prototipo en el entorno de staging / QA de RPost.
Puede acceder al prototipo aquí: settings22.d1.rpost.info
Solo para facilitar las pruebas de integración, el prototipo muestra un popup que permite enviar parámetros de la API a través de la interfaz de usuario.

El popup Signature Payload que se muestra en la página web acepta tres parámetros::

- Token: Este es el token de autenticación recibido después de invocar la API Authenticate User de RSign.
- RClick ID: Este es un identificador único generado por RSign para identificar la aplicación web del cliente. 
- RClick Key: Este es un parámetro único generado por RSign que la aplicación web del cliente debe enviar a RSign durante una llamada a la API.

Nota: El administrador del cliente debe obtener el RClick ID y el RClick Key para su aplicación desde Configuración de RSign>Compañía>Configuración Avanzada.

Como si fuera el firmante, haga click en el control de firma para aplicar su firma.

Una vez que haga click en el control de Firma, se abrirá el popup Agregar Firma. Firme y luego haga click en OK. 

Una vez que la firma se aplica al documento, seleccione ambas casillas en la parte inferior de la pantalla y haga click en Enviar para completar la transacción.

La aplicación del cliente envía el Código de Plantilla (TemplateID), Asunto (Subject), Cuerpo del correo (Body) y la Lista de firmantes (Signers list) a RSign.

Ingrese el valor en el campo de texto de la lista de firmantes con el siguiente formato. Asegúrese de que el ID del control HTML en el payload coincida con los IDs de los controles HTML colocados en el documento. Además, asegúrese de que el control HTML de la firma comience con signControl.

[
{"roleName":"Manager","name":"John Doer","email":"jdoer@yahoo.com","dataControls":[
{"controlID":"","controlHtmlID":"nameControl68146","controlValue":"Peter Johnson"},
{"controlID":"","controlHtmlID":"textControl56448","controlValue":"Golden Habitat, Kondapur"},
{"controlID":"","controlHtmlID":"dateControl92618","controlValue":"08/02/2024"},
{"controlID":"","controlHtmlID":"baserate","controlValue":"145.05"},
{"controlID":","controlHtmlID":"accomodation","controlValue":"0.00"},
{"controlID":"","controlHtmlID":"brokenlunch","controlValue":"20.10"},
{"controlID":"","controlHtmlID":"nightschoolbrokenlunch","controlValue":"0.00"},
{"controlID":"","controlHtmlID":"supplimentaryperformance","controlValue":"78.89"},
{"controlID":"","controlHtmlID":"otherexpenses","controlValue":"0.00"},
{"controlID":"","controlHtmlID":"overtime","controlValue":"0.00"},
{"controlID":"","controlHtmlID":"holidaycredit","controlValue":"15.62"},
{"controlID":"","controlHtmlID":"travelallowance","controlValue":"13.87"},
{"controlID":"","controlHtmlID":"fittingfee","controlValue":"0.00"},
{"controlID":"","controlHtmlID":"adjustment","controlValue":"0.00"},
{"controlID":"","controlHtmlID":"reasonforadjustment","controlValue":"Just for checking"},
{"controlID":"","controlHtmlID":"Total","controlValue":"273.53"},
{"controlID":"","controlHtmlID":"signControl1","controlValue":""}
],
"order": 1
}]

El documento final firmado se devuelve a la aplicación web del cliente en formato base 64. Verifique que se envíe por correo electrónico a la dirección indicada.