OneSpan Sign Cómo se hace: Solicitar archivos adjuntos

Como remitente, puede solicitar a un firmante que cargue un archivo adjunto durante la ceremonia de firma. Por ejemplo, como corredor de seguros de automóviles, puede exigir a su cliente que presente una copia de su permiso de conducir junto con los documentos firmados. Una vez que se hayan proporcionado los anexos solicitados, tendrá la opción de aceptar o rechazar el anexo. En caso de rechazo, podrá proporcionar información en forma de un breve mensaje y el firmante tendrá la oportunidad de cargar un archivo diferente. En este blog, le mostraré cómo solicitar, descargar y aceptar/rechazar archivos adjuntos con el OneSpan Sign Java SDK, .NET SDK y REST API.

El Código

Ahora que conocemos nuestro objetivo, vamos a sumergirnos directamente en el código. Cubriré exactamente la misma información en cada segmento. Pase a la sección que le corresponda. El código de ejemplo completo de este blog se puede encontrar en la Comunidad de Desarrolladores Code Share: Java, .NET y REST.

SDK de Java

Empezaré con el SDK de Java. A continuación se muestra un código de ejemplo sobre cómo editar el bloque de firmantes para solicitar un archivo adjunto. El método withDescription( ) le permite proporcionar una descripción al firmante sobre la carga de archivos que está buscando y el método isRequiredAttachment() define que está requiriendo el archivo adjunto. Ninguno de ellos es obligatorio al construir su objeto AttachmentRequirement. Si necesita una comparación con la creación de objetos de documento básicos o si es la primera vez que crea un paquete con el SDK de Java, consulte este blog.

.withSigner(newSignerWithEmail("[email protected]") .withFirstName("John") .withLastName("Doe") .withCustomId("Signer1") .withAttachmentRequirement(newAttachmentRequirementWithName("Driver's license") .withDescription("Por favor, cargue una copia de su licencia de conducir")
		.isRequiredAttachment() .build()))

Por lo tanto, es posible que también desee consultar el estado de cada archivo adjunto en su paquete. OneSpan Sign devolverá los objetos AttachmentRequirement como una lista. El código siguiente recorrerá cada objeto AttachmentRequirement e imprimirá el nombre, el estado y el identificador de cada archivo adjunto solicitado para ese firmante en particular.

DocumentPackage myPackage = client.getPackage(packageId); List signer1Attachments = myPackage.getSigner("[email protected]").getAttachmentRequirements(); for(AttachmentRequirement attachment : signer1Attachments){ System.out.println(attachment.getName() + " " + attachment.getStatus() + " " + attachment.getId()); }

Además, tiene la opción de descargar los archivos adjuntos de tres maneras diferentes:

• Un solo archivo adjunto (requiere la identificación del archivo adjunto)
• Todos los accesorios en un paquete
• Todos los archivos adjuntos de un firmante en particular

//Download individual attachment DownloadedFile downloadedAttachment = client.getAttachmentRequirementService().downloadAttachmentFile(packageId, attachmentId); Files.saveTo(downloadedAttachment.getContents(), downloadedAttachment.getFilename()); //Download all attachments in package DownloadedFile downloadedAllAttachmentsForPackage = client.getAttachmentRequirementService().downloadAllAttachmentFilesForPackage(packageId); Files.saveTo(downloadedAllAttachmentsForPackage.getContents(), "downloadedAllAttachmentsForPackage.zip"); //Download all attachments for signer in package DownloadedFile downloadedAllAttachmentsForSigner1InPackage = client.getAttachmentRequirementService().downloadAllAttachmentFilesForSignerInPackage(myPackage, signer1); Files.saveTo(downloadedAllAttachmentsForSigner1InPackage.getContents(), "downloadedAllAttachmentsForSigner.zip");

Después de revisar el archivo adjunto, tiene la posibilidad de rechazar o aceptar el archivo adjunto. En esta última situación, puede incluir una respuesta en forma de un pequeño mensaje que explique el rechazo.

client.getAttachmentRequirementService().rejectAttachment(packageId, signer1, "Driver's license", "Expired driver's license");

Es importante tener en cuenta que los paquetes con archivos adjuntos requeridos no se autocompletarán. Esto es para que el remitente tenga la oportunidad de revisar el archivo adjunto y aceptarlo o rechazarlo. Si se han cargado y aprobado todos los anexos necesarios, puede completar el paquete actualizando el estado de su paquete a COMPLETADO.

DocumentPackage myPackage = client.getPackage(packageId); myPackage.setStatus(PackageStatus.COMPLETED); client.updatePackage(packageId, myPackage);

SDK DE .NET

A continuación, cubriré el SDK de .NET. A continuación se muestra un código de ejemplo sobre cómo editar el bloque de firmantes para solicitar un archivo adjunto. El método WithDescription( ) le permite proporcionar una descripción al firmante sobre la carga de archivos que está buscando y el método IsRequiredAttachment() define que está requiriendo el archivo adjunto. Ninguno de ellos es obligatorio al construir su objeto AttachmentRequirement. Si necesita una comparación con la creación de objetos de documento básicos o si es la primera vez que crea un paquete con el SDK de .NET, consulte este blog.

.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]") .WithFirstName("John") .WithLastName("Doe") .WithCustomId("Signer1") .WithAttachmentRequirement(AttachmentRequirementBuilder.NewAttachmentRequirementWithName("Licencia de conducir") .WithDescription("Cargue una copia de su licencia de conducir")
        .IsRequiredAttachment() .Build())

Por lo tanto, es posible que también desee consultar el estado de cada archivo adjunto en su paquete. OneSpan Sign devolverá los objetos AttachmentRequirement como una lista. El código siguiente recorrerá cada objeto AttachmentRequirement e imprimirá el nombre, el estado y el identificador de cada archivo adjunto solicitado para ese firmante en particular.

DocumentPackage myPackage = client.GetPackage(packageId); IList signer1Attachments = myPackage.GetSigner("[email protected]").Attachments; foreach (AttachmentRequirement attachment in signer1Attachments) { Debug.WriteLine(attachment.Name + " " + attachment.Status + " " + attachment.Id); }

Además, puede descargar los archivos adjuntos de tres maneras diferentes:

• Un solo archivo adjunto (requiere la identificación del archivo adjunto)
• Todos los accesorios en un paquete
• Todos los archivos adjuntos de un firmante en particular

//Download individual attachment DownloadedFile downloadedAttachment = client.AttachmentRequirementService.DownloadAttachmentFile(packageId, attachmentId); System.IO.File.WriteAllBytes(downloadedAttachment.Filename, downloadedAttachment.Contents); //Download all attachments in package DownloadedFile downloadedAllAttachmentsForPackage = client.AttachmentRequirementService.DownloadAllAttachmentFilesForPackage(packageId); System.IO.File.WriteAllBytes("downloadedAllAttachmentsForPackage.zip", downloadedAllAttachmentsForPackage.Contents); //Download all attachments for signer in package DownloadedFile downloadedAllAttachmentsForSigner1InPackage = client.AttachmentRequirementService.DownloadAllAttachmentFilesForSignerInPackage(myPackage, signer1); System.IO.File.WriteAllBytes("downloadedAllAttachmentsForSigner.zip", downloadedAllAttachmentsForSigner1InPackage.Contents);

Después de revisar el archivo adjunto, tiene la posibilidad de rechazarlo. En esta situación, puede incluir una retroalimentación en forma de un pequeño mensaje explicando el rechazo.

client.AttachmentRequirementService.RejectAttachment(packageId, signer1, "Driver's license", "Expired driver's license");

Es importante tener en cuenta que los paquetes con archivos adjuntos requeridos no se autocompletarán. Esto es para que el remitente tenga la oportunidad de revisar el archivo adjunto y aceptarlo o rechazarlo. Si se han cargado y aprobado todos los anexos necesarios, puede completar el paquete actualizando el estado de su paquete a COMPLETADO.

DocumentPackage myPackage = eslClient.GetPackage(packageId); myPackage.Status = DocumentPackageStatus.COMPLETED; eslClient.UpdatePackage(packageId, myPackage);

API REST

Por último, cubriré la API REST. El ejemplo JSON de abajo muestra cómo editar su objeto de roles para solicitar un archivo adjunto. Si necesita una comparación con la creación de objetos de documento básicos o si es la primera vez que crea un paquete con la API REST, consulte este blog.

[code language="javascript"]{ "roles": [ { "id": "cliente", "type": "SIGNER", "index": 1, "attachmentRequirements": [ { "description": "Por favor, suba una copia escaneada de su licencia de conducir", "required": true, "id": "lD6p5QnWk905", "data": null, "status": "INCOMPLETE", "comment": "", "name": "Driver's license" } ], "signers": [ { "firstName": "John", "lastName": "Smith", "email": "[email protected]" } ], "name": "client" }, { "id": "contractor", "type": "SIGNER", "index": 2, "signers": [ { "firstName": "Bob", "lastName": "Murray", "email": "[email protected]" } ], "name": "contractor" } ] } Accordingly, you may also want to query the status of each attachment in your package. El código siguiente recuperará cada objeto attachmentRequirements de su paquete.

HttpClient myClient = new HttpClient(); myClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", apiKey); myClient.DefaultRequestHeaders.Add("Accept", "application/json"); var roles = myClient.GetAsync(new Uri(apiUrl + "/packages/{packageId}/roles")).Result; JObject roles_json = JObject.Parse(roles.Content.ReadAsStringAsync().Result); var results = roles_json["results"]; foreach (var attachment in results) { var attach = attachment["attachmentRequirements"]; Debug.WriteLine(attach); }

Para descargar un archivo adjunto individual, necesitará el paquete y la identificación del archivo adjunto. El código de ejemplo que aparece a continuación muestra cómo realizar la solicitud:

var attachment = myClient.GetAsync(new Uri(API_URL + "/packages/{packageId}/attachment/{attachmentId}").Result; ByteArrayContent = new ByteArrayContent(attachment.Content.ReadAsByteArrayAsync().Result); File.WriteAllBytes("PATH_TO_DOWNLOAD", content.ReadAsByteArrayAsync().Result);

Para descargar todos los archivos adjuntos como un archivo zip en un paquete, hará su solicitud a https://sandbox.onespan.com/api/packages/{packageId}/attachment/zip. Para descargar todos los archivos adjuntos como un archivo zip para un firmante en particular, hará su solicitud a https://sandbox.onespan.com/api/packages/{packageId}/attachment/zip/{roleId}. Después de revisar el archivo adjunto, tiene la posibilidad de aceptarlo o rechazarlo. En esta última situación, puede incluir una respuesta en forma de un pequeño mensaje que explique el rechazo. Para rechazar un archivo adjunto, hará una petición PUT a https://sandbox.onespan.com/api/packages/{packageId}/roles/{roleId} con el siguiente JSON: [code language="javascript"]{ "attachmentRequirements": [ { "id": "q66CYiDrxTU1", "status": "REJECTED", "comment": "Invalid copy". } ] } Es importante tener en cuenta que los paquetes con archivos adjuntos requeridos no se autocompletarán. Esto es para que el remitente tenga la oportunidad de revisar el archivo adjunto y aceptarlo o rechazarlo. Si se han cargado y aprobado todos los archivos adjuntos necesarios, puede completar el paquete realizando una solicitud PUT a https://sandbox.onespan.com/api/packages/{packageId}, con el siguiente JSON: [code language="javascript"]{ "status" : "COMPLETED" }

Ejecutar su código

Una vez que haya ejecutado su código, si inicia sesión en OneSpan Sign y se dirige a la configuración del firmante en su paquete, debería encontrar sus solicitudes de adjuntos en la pestaña de adjuntos.

Durante la ceremonia de firma, el firmante se presentará al diálogo que aparece a continuación solicitando que cargue el archivo adjunto requerido.

Si navega al directorio de su espacio de trabajo, encontrará los archivos adjuntos descargados.

Ahí lo tienes. Ha solicitado correctamente los archivos adjuntos Si tiene preguntas sobre este blog o cualquier otra cosa relacionada con la integración de OneSpan Sign en su aplicación, visite los foros de la comunidad de desarrolladores: https://developer.onespan.com.

Eso es todo de mi parte. Gracias por leer Si te ha resultado útil este artículo, compártelo en Facebook, Twitter o LinkedIn

Haris Haidary

Evangelista técnico junior

LinkedIn | Twitter