OneSpan Sign para nuevos usuarios: cree y envíe un paquete usando REST con Java

Cuando comencé con OneSpan Sign, comencé una serie de blogs llamada "OneSpan Sign para nuevos usuarios". Cubrí ejemplos simples del uso de OneSpan Sign UI, Java SDK, .NET SDK y REST API con C #. En su lugar, ha habido varias preguntas sobre el uso de REST con Java, así que decidí asociarme con Haris (nuestro nuevo Evangelista Junior Sign OneSpan). Haré el primero de los dos blogs más de la serie. El mío cubrirá la creación y el envío de un paquete de documentos, mientras que Haris hará un seguimiento para verificar el estado del paquete y descargar los documentos del paquete.

Si no tiene una cuenta de Sandbox, consulte mi primer blog para saber cómo puedes registrarte.

Configuración

Antes de comenzar, deberá configurar su entorno. Para este ejemplo, usaré Java y Eclipse. Continúe y cree un nuevo proyecto y un archivo .java. Llamé a mi proyecto "CreateAndSendPackageREST" y mi archivo .java, "CreateAndSendPackageREST.java". Si necesita ayuda para configurar esto, consulte mi primer blog .Java SDK para obtener instrucciones más detalladas sobre cómo configurar un proyecto.

Crear y enviar un paquete usando REST con Java

El código

Dado que la configuración del entorno y la configuración del proyecto se han cubierto en blogs anteriores, en esta serie, saltaré directamente al código. Abra el archivo .java que creó anteriormente y copie en el siguiente código. Cubriré el código con más detalle a continuación.

Comunidad de desarrolladores de OneSpan Sign

¡Únase a la comunidad de desarrolladores de OneSpan Sign! Foros, blogs, documentación, descargas de SDK y más.

Únete hoy

paquete com.esignlive.example;

import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLConnection;
import java.nio.file.Files;
 
clase pública SimpleCreateAndSendREST {
      
     
    public static void main (String [] args) lanza MalformedURLException, IOException {
         
        String requestURL = "https://sandbox.esignlive.com/api";
        String apiKey = "Your_API_Key";
        String charset = "UTF-8";
        File uploadFile1 = nuevo archivo ("C: /Eclipse/workspace_442/CreateAndSendPackage/sampleAgreement.pdf");
        Límite de cadena = Long.toHexString (System.currentTimeMillis ()); // Genera un valor aleatorio para el límite del formulario
        Cadena CRLF = "\ r \ n"; // Separador de línea utilizado en multipart / form-data.
        Cadena jsonContent = "{\" roles \ ": [{\" bloqueado \ ": falso, \" emailMessage \ ": {\" content \ ": \" \ "}, \" attachRequirements \ ": [], \ "reasignar \": falso, \ "tipos especiales \": [], \ "id \": \ "Remitente \", \ "data \": nulo, \ "type \": \ "SIGNER \", \ " index \ ": 0, \" firmantes \ ": [{\" auth \ ": {\" desafíos \ ": [], \" esquema \ ": \" NINGUNO \ "}, \" empresa \ ": \ "Silanis \", \ "firstName \": \ "PreparerFirst \", \ "lastName \": \ "PreparerLast \", \ "phone \": \ "\", \ "email \": \ "senderemail @example .com \ ", \" knowledgeBasedAuthentication \ ": null, \" language \ ": \" en \ ", \" title \ ": \" Silanis \ ", \" external \ ": null, \" professionalIdentityFields \ " : [], \ "userCustomFields \": [], \ "delivery \": {\ "email \": true, \ "provider \": false, \ "download \": true}, \ "group \" : nulo, \ "firma \": nulo, \ "dirección \": nulo, \ "datos \": nulo, \ "nombre \": \ "\", \ "tipos especiales \": []}], \ "nombre \": \ "Remitente \"}, {\ "bloqueado \": falso, \ "emailMessage \": {\ "content \": \ "\"}, \ "attachRequirements \": [], \ "reasignar \": falso, \ "tipos especiales \": [], \ "id \": \ "Firmante \", \ "datos \": nulo, \ "tipo \": \ "SIGNER \", \ " index \ ": 0, \" firmantes \ ": [{\" auth \ ": {\" desafíos \ ": [], \" esquema \ ": \" NINGUNO \ "}, \" empresa \ ": \ "\", \ "firstName \": \ "SignerFirst \", \ "SignerLast \": \ "Silanis \", \ "phone \": \ "\", \ "email \": \ "signeremail @example .com \ ", \" knowledgeBasedAuthentication \ ": null, \" language \ ": \" en \ ", \" title \ ": \" \ ", \" external \ ": null, \" professionalIdentityFields \ ": [], \ "userCustomFields \": [], \ "entrega \": {\ "correo electrónico \": falso, \ "proveedor \": falso, \ "descarga \": falso}, \ "grupo \": nulo, \ "id \": \ "Firmante \", \ "firma \": nulo, \ "dirección \": nulo, \ "datos \": nulo, \ "nombre \": \ "\", \ "specialTypes \": []}], \ "nombre \": \ "Firmante \"}], \ "documentos \": [{\ "aprobaciones \": [{\ "rol \": \ "Firmante \ ", \" firmado \ ": nulo, \" aceptado \ ": nulo, \" datos \ ": nulo, \" campos \ ": [{\" página \ ": 0, \" subtipo \ ": \" NOMBRE COMPLETO \ ", \" ancho \ ": 200, \" enlace \ ": nulo, \" extracto \ ": falso, \" extractoAnchor \ ": nulo, \" izquierda \ ": 175, \" arriba \ ": 165, \ "validación \": nulo, \ "altura \": 50, \ "datos \": nulo, \ "tipo \": \ "FIRMA \", \ "valor \": \ "\"}] , \ "nombre \": \ "\"}, {\ "rol \": \ "Remitente \", \ "firmado \": nulo, \ "aceptado \": nulo, \ "datos \": nulo, \ "campos \": [{\ "página \": 0, \ "subtipo \": \ "NOMBRE COMPLETO \", \ "ancho \": 200, \ "enlace \": nulo, \ "extracto \": falso, \ "extractAnchor \": null, \ "left \": 550, \ "top \": 165, \ "validation \": null, \ "height \": 50, \ "data \": null, \ "type \": \ "FIRMA \ ", \" value \ ": \" \ "}], \" name \ ": \" \ "}], \" name \ ": \" sampleAgreement \ "}], \" name \ ": \" Paquete de prueba REST \ ", \" type \ ": \" PACKAGE \ ", \" language \ ": \" en \ ", \" emailMessage \ ": \" \ ", \" description \ ": \" Nuevo Paquete \ ", \" autoComplete \ ": verdadero, \" estado \ ": \" ENVIADO \ "}";
 
        Conexión URLConnection = nueva URL (requestURL + "/ packages /"). OpenConnection ();
        connection.setDoOutput (verdadero);
        connection.setRequestProperty ("Content-Type", "multipart / form-data; boundary =" + boundary);
        connection.setRequestProperty ("Autorización", "Básico" + apiKey);
    connection.setRequestProperty ("Aceptar", "aplicación / json");
    OutputStream output = connection.getOutputStream ();
    PrintWriter writer = new PrintWriter (nuevo OutputStreamWriter (salida, juego de caracteres), verdadero);
 
        tratar {
 
             // Añadir archivo pdf.
             writer.append ("-" + límite) .append (CRLF);
             writer.append ("Content-Disposition: form-data; name = \" file \ "; filename = \" "+ uploadFile1.getName () +" \ ""). append (CRLF);
             writer.append ("Content-Type:" + URLConnection.guessContentTypeFromName (uploadFile1.getName ())). append (CRLF);
             writer.append ("Content-Transfer-Encoding: application / pdf"). append (CRLF);
             writer.append (CRLF) .flush ();
             Files.copy (uploadFile1.toPath (), salida);
             output.flush ();
             writer.append (CRLF) .flush ();
                 
             // agregar carga útil json
             writer.append ("-" + límite) .append (CRLF);
             writer.append ("Content-Disposition: form-data; name = \" payload \ ""). append (CRLF);
             writer.append ("Tipo de contenido: application / json; charset =" + charset) .append (CRLF);
             writer.append (CRLF) .append (jsonContent) .append (CRLF) .flush ();
 
             // Fin de multipart / form-data.
             writer.append ("-" + límite + "-"). append (CRLF) .flush ();
        }
        catch (IOException ex) {
            System.err.println (ex);
        }
 
        // obtener y escribir el código de respuesta
        int responseCode = ((HttpURLConnection) connection) .getResponseCode ();
        System.out.println (responseCode);
         
        // obtener y escribir la respuesta
        BufferedReader in = new BufferedReader (nuevo InputStreamReader (connection.getInputStream ()));
    String inputLine;
    Respuesta de StringBuffer = new StringBuffer ();
     
    while ((inputLine = in.readLine ())! = null) {
         respuesta.append (inputLine);
    }
        cercar();
      
    // imprimir resultado
    System.out.println (response.toString ());
    }
}
 

Rompiendo el Código

Como este es un ejemplo muy simple, todo se hace en el método principal.

En las primeras dos líneas, se define la información de conexión para su conexión OneSpan Sign. Si está utilizando el entorno de producción, use la url, https://apps.e-signlive.com/api. Asegúrese de reemplazar el texto del marcador de posición con su API_KEY. Puede encontrar este valor en la página CUENTA cuando inicie sesión en su cuenta de OneSpan Sign Sandbox. Si está utilizando la instancia de producción, deberá ponerse en contacto con el soporte para obtener esta clave.

1 cadena apiKey = "YOUR_API_KEY";
2 string url = "https://sandbox.esignlive.com/api";

Después de eso, verá que se establecen varias otras variables que usaremos en la creación de la llamada POST, como el valor del límite del formulario y el archivo que planea cargar.

1 String charset = "UTF-8";
2 File uploadFile1 = nuevo archivo ("C: /Eclipse/workspace_442/CreateAndSendPackage/sampleAgreement.pdf");
Límite de 3 cadenas = Long.toHexString (System.currentTimeMillis ()); // Genera un valor aleatorio para el límite del formulario
4 Cadena CRLF = "\ r \ n"; // Separador de línea utilizado en multipart / form-data

La siguiente línea es la cadena JSON que define su paquete. Por lo general, probablemente construirá su cadena JSON dinámicamente frente a tener una cadena estática gigante, como esta, pero lo hice de esta manera para dar una buena representación de la estructura de JSON que necesitará para crear su paquete correctamente. He dejado muchas propiedades vacías en la cadena que no son necesarias para la creación, por lo que puede ver algunas de las otras opciones disponibles y cómo se pasan en el JSON. He formateado el JSON para legibilidad, a continuación.

string jsonString = "{
	\ "roles \": [
	{
		\ "bloqueado": falso,
		\"Mensaje de correo electrónico\":
		{
			\"contenido\":\"\"
		},
		\ "AttachmentRequirements \": [],
		\ "reasignar \": falso,
		\ "specialTypes \": [],
		\ "id \": \ "Remitente \",
		\ "datos \": nulo,
		\ "type \": \ "SIGNER \",
		\ "index \": 0,
		\ "firmantes \": [
		{
			\ "auth \":
			{
				\ "desafíos \": [],
				\ "esquema \": \ "NINGUNO \"
			},
			\ "empresa \": \ "Silanis \",
			\ "firstName \": \ "YOUR_FIRST_NAME \",
			\ "apellido \": \ "YOUR_LAST_NAME \",
			\"teléfono\":\"\",
			\ "email \": \ "your.email @example .com \ ",
			\ "knowledgeBasedAuthentication \": nulo,
			\ "idioma \": \ "en \",
			\"título\":\"\",
			\ "externo \": nulo,
			\ "professionalIdentityFields \": [],
			\ "userCustomFields \": [],
			\"entrega\":
			{
				\ "email \": verdadero,
				\ "proveedor \": falso,
				\ "descargar \": verdadero
			},
			\ "grupo \": nulo,
			\ "firma \": nulo,
			\ "dirección \": nulo,
			\ "datos \": nulo,
			\"nombre\":\"\",
			\ "specialTypes \": []
		}],
		\ "nombre \": \ "Remitente \"
	},
	{
		\ "bloqueado": falso,
		\"Mensaje de correo electrónico\":
		{
			\"contenido\":\"\"
		},
		\ "AttachmentRequirements \": [],
		\ "reasignar \": falso,
		\ "specialTypes \": [],
		\ "id \": \ "Firmante \",
		\ "datos \": nulo,
		\ "type \": \ "SIGNER \",
		\ "index \": 0,
		\ "firmantes \": [
		{
			\ "auth \":
			{
				\ "desafíos \": [],
				\ "esquema \": \ "NINGUNO \"
			},
			\"empresa\":\"\",
			\ "firstName \": \ "SIGNER_FIRST_NAME \",
			\ "apellido \": \ "SIGNER_LAST_NAME \",
			\"teléfono\":\"\",
			\ "email \": \ "signer.email @example .com \ ",
			\ "knowledgeBasedAuthentication \": nulo,
			\ "idioma \": \ "en \",
			\"título\":\"\",
			\ "externo \": nulo,
			\ "professionalIdentityFields \": [],
			\ "userCustomFields \": [],
			\"entrega\":
			{
				\ "correo electrónico \": falso,
				\ "proveedor \": falso,
				\ "descargar \": falso
			},
			\ "grupo \": nulo,
			\ "id \": \ "Firmante \",
			\ "firma \": nulo,
			\ "dirección \": nulo,
			\ "datos \": nulo,
			\"nombre\":\"\",
			\ "specialTypes \": []
		}],
		\ "nombre \": \ "Firmante \"
	}],
	\"documentos\":[
	{
		\ "aprobaciones \": [
		{
			\ "role \": \ "Signer \",
			\ "firmado \": nulo,
			\ "aceptado \": nulo,
			\ "datos \": nulo,
			\"campos\":[
			{
				\ "página \": 0,
				\ "subtipo \": \ "NOMBRE COMPLETO \",
				\ "ancho \": 200,
				\ "enlace \": nulo,
				\ "extract \": falso,
				\ "extractAnchor \": nulo,
				\ "izquierda \": 175,
				\ "top \": 165,
				\ "validación \": nulo,
				\ "altura \": 50,
				\ "datos \": nulo,
				\ "type \": \ "SIGNATURE \",
				\"valor\":\"\"
			}],
			\"nombre\":\"\"
		},
		{
			\ "role \": \ "Remitente \",
			\ "firmado \": nulo,
			\ "aceptado \": nulo,
			\ "datos \": nulo,
			\"campos\":[
			{
				\ "página \": 0,
				\ "subtipo \": \ "NOMBRE COMPLETO \",
				\ "ancho \": 200,
				\ "enlace \": nulo,
				\ "extract \": falso,
				\ "extractAnchor \": nulo,
				\ "izquierda \": 550,
				\ "top \": 165,
				\ "validación \": nulo,
				\ "altura \": 50,
				\ "datos \": nulo,
				\ "type \": \ "SIGNATURE \",
				\"valor\":\"\"
			}],
			\"nombre\":\"\"
		}],
		\ "name \": \ "YOUR_FILE_NAME \"
	}],
	\ "name \": \ "Test Package REST \",
	\ "type \": \ "PACKAGE \",
	\ "idioma \": \ "en \",
	\"Mensaje de correo electrónico\":\"\",
	\ "descripción \": \ "Nuevo paquete \",
	\ "autoComplete \": verdadero,
	\ "estado \": \ "ENVIADO \"
} ";
 

La primera parte de la cadena JSON del paquete es el objeto "roles". Dentro de esto, puede configurar elementos como "id", "empresa", "nombre", "apellido", "correo electrónico" y "nombre" para personalizar sus roles de firmante. Algunas de las otras configuraciones notables serían "mensaje de correo electrónico", "título" y "entrega".

La siguiente sección de la cadena JSON del paquete es el objeto "documentos". Dentro de esto, establecerá elementos como el "nombre" y las "aprobaciones" (bloques de firma). En las "aprobaciones", los elementos principales para establecer serían el "tipo", el "subtipo", el "rol", la "página" y la configuración de ubicación. Estos definirán las firmas requeridas en cada documento.

Finalmente, las últimas configuraciones de la cadena JSON del paquete que querrá anotar son "nombre", "tipo", "estado", "mensaje de correo electrónico" y "autocompletar".

A continuación, definirá la conexión a la que enviará su solicitud. La primera línea abre la conexión a la URL de solicitud. Observe que el resto de la URL para la solicitud particular que se está haciendo se agrega a la URL base, aquí. El resto configura las propiedades de la solicitud y crea OutputStream e PrintWriter para comunicar la carga útil de la solicitud con OneSpan Sign.

1 conexión URLConnection = nueva URL (requestURL + "/ packages /"). OpenConnection ();
2 connection.setDoOutput (verdadero);
3 connection.setRequestProperty ("Content-Type", "multipart / form-data; boundary =" + boundary);
4 connection.setRequestProperty ("Autorización", "Básico" + apiKey);
5 connection.setRequestProperty ("Aceptar", "aplicación / json");
6 OutputStream output = connection.getOutputStream ();
7 Escritor PrintWriter = nuevo PrintWriter (nuevo OutputStreamWriter (salida, juego de caracteres), verdadero);

Dentro del bloque try, se crea el formulario multiparte real. A continuación, puede ver cómo se agregan el límite, los descriptores de parte del formulario y el contenido en cada parte del formulario.

// Añadir archivo pdf.
writer.append ("-" + límite) .append (CRLF);
writer.append ("Content-Disposition: form-data; name = \" file \ "; filename = \" "+ uploadFile1.getName () +" \ ""). append (CRLF);
writer.append ("Content-Type:" + URLConnection.guessContentTypeFromName (uploadFile1.getName ())). append (CRLF);
writer.append ("Content-Transfer-Encoding: application / pdf"). append (CRLF);
writer.append (CRLF) .flush ();
Files.copy (uploadFile1.toPath (), salida);
output.flush ();
writer.append (CRLF) .flush ();
                 
// agregar carga útil json
writer.append ("-" + límite) .append (CRLF);
writer.append ("Content-Disposition: form-data; name = \" payload \ ""). append (CRLF);
writer.append ("Tipo de contenido: application / json; charset =" + charset) .append (CRLF);
writer.append (CRLF) .append (jsonContent) .append (CRLF) .flush ();
 
// Fin de multipart / form-data.
writer.append ("-" + límite + "-"). append (CRLF) .flush ();
 
// Fin de multipart / form-data.
writer.append ("-" + límite + "-"). append (CRLF) .flush ();
 

Finalmente, realizará la llamada POST, pasando su formulario a OneSpan Sign, creando su paquete de documentos. En este ejemplo, escribo el código de respuesta y el contenido de la respuesta en el conole.

// obtener y escribir el código de respuesta
int responseCode = ((HttpURLConnection) connection) .getResponseCode ();
System.out.println (responseCode);
             
// obtener y escribir la respuesta
BufferedReader in = new BufferedReader (nuevo InputStreamReader (connection.getInputStream ()));
String inputLine;
Respuesta de StringBuffer = new StringBuffer ();
      
while ((inputLine = in.readLine ())! = null) {
    respuesta.append (inputLine);
}
cercar();
      
// imprimir resultado
System.out.println (response.toString ());
 

Si todo con su llamada REST es correcto, debería recibir un identificador de paquete como respuesta, como este:

Si inicia sesión en su cuenta de OneSpan Sign, puede ver que el paquete se ha creado según lo definido en su solicitud.

Eso es. Ha creado con éxito un nuevo paquete, que incluye un archivo, firmantes y colocar cuadros de firma utilizando REST con Java.

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.esignlive.com. Eso es todo de mi parte. ¡Gracias por leer! Si esta publicación le parece útil, compártala en Facebook, Twitter o LinkedIn.

- Michael Williams

Gorjeo El | Facebook El | LinkedIn