OneSpan Sign para nuevos usuarios: cómo crear y enviar su primer paquete (API REST)
La finalización de la serie "OneSpan Sign for New Users" está cerca. Hasta ahora, he cubierto ejemplos simples de uso firmas electrónicas , la interfaz de usuario de OneSpan Sign, Java SDK y .NET SDK. Puedes ver la lista completa de publicaciones al final de este blog. Los dos últimos blogs de la serie cubrirán el uso de la API REST de OneSpan Sign, que cubrirá, creará y enviará un paquete de documentos.
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é C # y Microsoft Visual Studio. Continúe y obtenga un proyecto y un archivo .cs creado. Llamé a mi proyecto "CreateAndSendPackageREST" y mi archivo .cs, "CreateAndSendPackageREST.cs". Si necesita ayuda para configurar esto, vea mi primera Blog de .NET SDK (puede ignorar la parte del SDK de .NET y pasar a las secciones "Descarga de Microsoft Visual Studio" y "Crear y configurar su proyecto C #") para obtener instrucciones más detalladas.
Firmas electrónicas - Guía del principiante
Esta comunicación esencial de 25 páginas presenta conceptos legales importantes y consideraciones clave a la hora de crear procesos comerciales digitales con firmas electrónicas.
Descargar ahoraCrear y enviar un paquete
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 .cs que creó anteriormente y copie en el siguiente código. Cubriré el código con más detalle a continuación.
utilizandoSistema;utilizandoDiagnostico del sistema;utilizandoSystem.IO;utilizandoSystem.Net;utilizandoSystem.Net.Http;utilizandoSystem.Net.Http.Headers;utilizandoSystem.Text;espacio de nombresCreateAndSendPackageREST{públicoclaseCreateAndSendPackage{públicoestáticovacíoPrincipal(cuerda[] args){cuerdaapiKey ="YOUR_API_KEY";cuerdaurl ="https://sandbox.esignlive.com/api";cuerdajsonString ="{\" roles \ ": [{\" bloqueado \ ": falso, \" emailMessage \ ": {\" content \ ": \" \ "}, \" attachRequirements \ ": [], \ "reasignar \": falso, \ "tipos especiales \": [], \ "id \": \ "Remitente \", \ "data \": nulo, \ "tipo \": \ "SIGNER \ ", \" index \ ": 0, \" firmantes \ ": [{\" auth \ ": {\" desafíos \ ": [], \ "esquema \": \ "NINGUNO \"}, \ "empresa \": \ "Silanis \", \ "firstName \": \ "yourFirst \", \ "lastName \": \ "yourLast \ ", \" phone \ ": \" \ ", \" email \ ": \" your.email @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, \" SpecialTypes \ ": [], \" id \ ": \" Signer \ ", \" data \ ": null, \" type \ ": \" SIGNER \ ", \" index \ ": 0, \" signers \ ": [{\" auth \ ": {\" challenge \ ": [], \ "esquema \": \ "NINGUNO \"}, \ "empresa \": \ "\", \ "nombre \": \ "signerFirst \", \ "apellido \": \ "signerLast \" , \ "phone \": \ "\", \ "email \": \ "signer.email @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, \ "extractoAnchor \ ": nulo, \" izquierda \ ": 550, \" arriba \ ": 165, \" validación \ ": nulo, \" altura \ ": 50, \" datos \ ": nulo, \" tipo \ ": \ "FIRMA \", \ "valor \": \ "\"}], \ "nombre \": \ "\"}], \ "nombre \": \ "sampleAgreement \"}], \ "nombre \ ": \" Test Package REST \ ", \" type \ ": \" PACKAGE \ ", \" language \ ": \" en \ ", \" emailMessage \ ": \" \ ", \" description \ " : \ "Nuevo paquete \", \ "autocompletar \": verdadero, \ "estado \": \ "ENVIADO \"} ";StringContent jsonContent =nuevoStringContent (jsonString, Encoding.UTF8,"aplicación / json");byte[] fileByteArray = File.ReadAllBytes ("PATH_TO_YOUR_PDF.pdf");ByteArrayContent content =nuevoByteArrayContent (fileByteArray);content.Headers.ContentDisposition =nuevoContentDispositionHeaderValue ("datos de formulario");content.Headers.ContentDisposition.Name ="\"archivo\"";content.Headers.ContentDisposition.FileName ="\" NAME_OF_YOUR_FILE.pdf \ "";content.Headers.ContentType =nuevoMediaTypeHeaderValue ("Solicitud PDF");MultipartFormDataContent form =nuevoMultipartFormDataContent ();form.Add (contenido,"\"archivo\"","\" NAME_OF_YOUR_FILE.pdf \ "");form.Add (jsonContent,"\"carga útil\"");HttpClient myClient =nuevoHttpClient ();myClient.DefaultRequestHeaders.Authorization =nuevoAuthenticationHeaderValue ("Básico", Clave API);myClient.DefaultRequestHeaders.Add ("Aceptar","aplicación / json");varrespuesta = myClient.PostAsync (nuevoUri (url) +"/ paquetes /", forma) .Resultado;Debug.WriteLine (response.Content.ReadAsStringAsync (). Resultado);}}}
Rompiendo el código
Ahora que tiene el código copiado en su archivo .cs, recorreré el código, sección por sección, dejándole saber dónde necesitará ingresar información para su paquete y describiendo lo que hace cada sección. Como este es un ejemplo muy simple, todo se hace en el método principal. Desglosando el Código
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.
1 cadena apiKey = "YOUR_API_KEY"; 2 string url = "https://sandbox.esignlive.com/api";
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". En este ejemplo, establecí el "estado" en "ENVIADO". Hacer esto enviará el paquete y notificará a los firmantes. Si desea guardar este paquete como borrador, haga el valor "DRAFT" en su lugar.
La siguiente línea del código tomará su cadena JSON y creará el objeto StringContent que pasará como carga en su comando API REST.
StringContent jsonContent = new StringContent (jsonString, Encoding.UTF8, "aplicación / json");
Las siguientes dos líneas se leerán en su archivo PDF y lo usarán para crear su objeto ByteArrayContent para su llamada REST. Asegúrese de cambiar el marcador de posición a la ruta de su archivo.
1 byte [] fileByteArray = File.ReadAllBytes ("PATH_TO_YOUR_PDF.pdf");
2 ByteArrayContent content = nuevo ByteArrayContent (fileByteArray);
Las siguientes líneas definen el encabezado de disposición de contenido del objeto de contenido del archivo pdf.
1 content.Headers.ContentDisposition = new ContentDispositionHeaderValue ("datos de formulario");
2 content.Headers.ContentDisposition.Name = "\" archivo \ "";
3 content.Headers.ContentDisposition.FileName = "\" NAME_OF_YOUR_FILE.pdf \ "";
4 content.Headers.ContentType = new MediaTypeHeaderValue ("aplicación / pdf");
El siguiente bloque de código es donde crea su formulario multiparte y agrega los objetos de contenido creados anteriormente para pasar con su llamada REST. Asegúrese de configurar el nombre del archivo.
1 MultipartFormDataContent form = new MultipartFormDataContent (); 2 form.Add (contenido, "\" archivo \ "", "\" NAME_OF_YOUR_FILE.pdf \ ""); 3 form.Add (jsonContent, "\" payload \ "");
A continuación, creará el HttpClient que usará para realizar su solicitud POST y establecerá la autorización de encabezado adecuada y aceptará los valores.
1 HttpClient myClient = new HttpClient ();
2 myClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue ("Básico", apiKey);
3 myClient.DefaultRequestHeaders.Add ("Aceptar", "aplicación / json");
Finalmente, realizará la llamada POST, pasando su formulario a OneSpan Sign, creando su paquete de documentos. La línea de depuración mostrará el resultado en la consola de salida de depuración.
1 respuesta var = myClient.PostAsync (nueva Uri (url) + "/ packages /", form) .Result; 2 Debug.WriteLine (response.Content.ReadAsStringAsync (). Resultado);
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 como se define en su solicitud:
Eso es. Ha creado con éxito un nuevo paquete, que incluye un archivo, firmantes y colocar cuadros de firma con la API REST.
¡Gracias por leer! Si tiene preguntas o características que le gustaría ver cubiertas desde la perspectiva de un nuevo usuario, no dude en publicar en la sección de comentarios. Los enlaces a todas las publicaciones de esta serie de blogs se pueden encontrar a continuación. Si quieres ver más publicaciones mías, mira mi página de autor.
- Michael Williams
