Saltar al contenido principal

SDK de C#

Recomendamos programar directamente contra la API, la referencia técnica y tu IA lo hacen sencillo. Se puede generar un SDK en C# usando la especificación OpenAPI3 de nuestra API y openapi generator. Sin embargo, si quieres un SDK te recomendamos usar el proyecto generado proporcionado, ya que incluye correcciones para algunos problemas como campos anulables.

Haz clic aquí para el repositorio de C#.

El paquete contiene su propia documentación (en docs/), pero los ejemplos a continuación te mostrarán cómo empezar.

Obtén tu clave API​

  • Regístrate para una cuenta de prueba.

  • Configura para API cuando se te pida, y envía un correo a Soporte para obtener una clave API. Debes demostrar un nivel de comprensión sobre el uso de REST API, incluye en tu correo: nombre y dirección de tu empresa, tu nombre y rol, describe tu caso de uso, y da un resumen breve de tu experiencia en programación/REST.

  • Una vez emitida, tu clave API estará disponible en la aplicación web. Verás que estás en sandbox - agrega cualquier correo electrónico al que enviarás tus documentos de prueba.

Tu clave API va en el encabezado "Authorization", y toma la forma: Apikey usuario:secreto. Tu usuario y secreto serán indicados claramente en la aplicación web.

Obtén el SDK y proyectos de ejemplo​

Con tus herramientas git preferidas clona el repositorio del SDK C#.

git clone https://github.com/legalesign/LegalesignCsharpSDK.git legalesignSDK

Configura el proyecto de ejemplo:​

Abre LegalesignCsharpSDK.sln y compila el proyecto. Deberías ver tres proyectos incluidos en la solución, nos enfocaremos en LegalesignTest que te ayudará a empezar a hacer llamadas a la REST API.

Para ahorrar tiempo, puedes agregar tu nombre de usuario, secreto, nombre de grupo, correo electrónico destino, nombre y apellido como las propiedades Text para txtUsername, txtSecretKey, etc. en Form1. Si no, tendrás que proporcionarlos cuando ejecutes el proyecto Winform (asegúrate de que esté marcado como el proyecto de inicio). Si los codificas directamente recuerda eliminar esa información una vez que termines con el proyecto.

Veamos el primer bloque de código en Form1.cs:

private Configuration makeConfig() {
    Configuration c = new Configuration();
    c.AddApiKey("Authorization", $"ApiKey {txtUsername.Text}:{txtSecretKey.Text}");
            
    return c;
}

Puedes ver cómo esto usa el nombre de usuario y el secreto que proporcionas y lo pasa a la configuración para cada llamada que haremos después. Así es como se autorizan las llamadas a la API.

Prueba una solicitud GET:​

Asegurémonos de que puedas hacer una solicitud GET simple, para verificar que tu autenticación está configurada correctamente.

El siguiente código se ejecuta cuando haces clic en el botón Get Groups. Tómate un tiempo para notar dónde se pasa la información de Configuración usando makeConfig(). Ejecuta el proyecto, ingresa tu nombre de usuario y clave en los cuadros si no los has codificado en la propiedad Text y haz clic en el botón Get Groups.

private void btnCall_Click(object sender, EventArgs e)
{           
    GroupApi group = new GroupApi(makeConfig());
    GroupListResponse groupList = group.GetGroups();
            
    richTextBox1.Text = groupList.ToJson();
}

Si tiene éxito obtendrás una lista en JSON de tus grupos.

Si no, verifica que tengas el valor de Authorization correcto.

Este código obtiene cualquier documento esperando ser firmado, un caso de uso común. Prúebalo examinando y luego ejecutando el botón Get Documents.

private void button2_Click(object sender, EventArgs e)
{
    DocumentApi docs = new DocumentApi(makeConfig());
    DocumentListResponse documentList = docs.GetDocuments();

    richTextBox1.Text = documentList.ToJson();
}
sugerencia

Las llamadas 'get_statuses()' y 'get_status()' son formas más rápidas de consultar información básica del documento.

Deberías estar empezando a entender cómo funciona el SDK. Regresa al archivo Readme del paquete, y verás todos los objetos API para probar, y todos sus métodos.

Prueba una solicitud POST​

Luego enviaremos un HTML personalizado para firmar en una llamada API, después subiremos un PDF y lo enviaremos.

Envía un documento HTML para firmar:​

Aquí hay una pequeña cantidad de HTML para propósitos de demostración, que contiene un elemento de firma. Reemplaza los valores de grupo, nombre y correo electrónico.

private void btnPost_Click(object sender, EventArgs e)
{
    DocumentApi docs = new DocumentApi(makeConfig());

    List<DocumentSignerPost> signers = new List<DocumentSignerPost>();
    signers.Add(new DocumentSignerPost(email: txtEmail.Text, firstname: txtFirstname.Text, lastname: txtLastname.Text));

    //You must provide group id as lowercase
    DocumentPost dp = new DocumentPost(
        group: $"/api/v1/group/{txtGroupName.Text.ToLower()}/",
        name: "dotnetdocument",
        text: rtbBodyHTML.Text,
        signers: signers,
        doEmail: true,
        footerHeight:30,
        footer: "Legalesign ID: {{doc_id}}");

    try
    {
        InlineResponse201 resp = docs.PostDocument(dp);
        richTextBox1.Text = resp.ToJson();
    }
    catch (Exception ex) {
        throw ex;
    }
}

¿Cómo sabemos que se envió? OpenAPI lanza una excepción para respuestas que no son 2XX. Querrás poner todas tus solicitudes en un bloque try/catch.

Cada vez que hagas un POST, probablemente querrás el ID del nuevo objeto. Está en el encabezado Location de la respuesta. En nuestro siguiente ejemplo veremos cómo subir un PDF para enviarlo a los firmantes, y obtener el ID de esa nueva plantilla.

Subir y enviar un PDF​

Probablemente usarás las text-tags dentro de tus PDFs para definir dónde las personas firmarán o completarán cualquier formulario. Usar el parámetro processTags=true indica al sistema que revise tu documento y cree campos para información y firmas para que el destinatario firme. Un ejemplo básico de un PDF con etiquetas está incluido en la raíz del proyecto SDK.

Vamos a subir un PDF usando la versión 'with_http_info' de la solicitud POST para obtener el ID

private void btnUploadPdf_Click(object sender, EventArgs e)
{
    DialogResult result = openFileDialog1.ShowDialog();

    if (result == System.Windows.Forms.DialogResult.OK)
    {
        TemplatepdfApi pdf = new TemplatepdfApi(makeConfig());

        // Get the file and convert the contents to a base64 byte array.
        Byte[] bytes = File.ReadAllBytes(openFileDialog1.FileName);
        String contents = Convert.ToBase64String(bytes);
        Byte[] encodedBytes = Convert.FromBase64String(contents);

        try
        {
            // Upload the pdf for our group to use with a title and a tag
            ApiResponse &lt;object&gt; response = pdf.PostPdfTemplateWithHttpInfo(new TemplatePdfFieldPost(group: $"/api/v1/group/{txtGroupName.Text.ToLower()}/",
                pdfFile: encodedBytes, processTags: true, title: "test tagged document"));

            // Just to demonstrate how to read response headers we'll put the returned
            // header in the output rich text box. The 'Location' header contains the new
            // Template ID.
            richTextBox1.Text = JsonConvert.SerializeObject(response.Headers);
                    
            // We'll save this so we can use it when calling Send with Template
            txtPDFLocation.Text = response.Headers["Location"];
        }
        catch (Exception ex)
        {
            throw ex;
        }
    }
}

Debido a que configuramos process_tags en true, todas las etiquetas han sido procesadas y tu PDF está listo para usar. Como antes, necesitamos el ID del PDF para poder enviarlo. Por suerte lo guardamos en la caja de texto txtPdfLocation.

El último fragmento de código de Send with Template muestra cómo usamos esa ubicación de PDF para enviar un documento pre-cargado para ser firmado.

private void btnSendTemplate_Click(object sender, EventArgs e)
{
    DocumentApi docs = new DocumentApi(makeConfig());

    List<DocumentSignerPost> signers = new List<DocumentSignerPost>();
    signers.Add(new DocumentSignerPost(email: txtEmail.Text, firstname: txtFirstname.Text, lastname: txtLastname.Text));

    //You must provide group id as lowercase
    DocumentPost dp = new DocumentPost(
        group: $"/api/v1/group/{txtGroupName.Text.ToLower()}/",
        name: "dotnetdocument",
        template: txtPDFLocation.Text,
        signers: signers,
        doEmail: true,
        footerHeight: 30,
        footer: "Legalesign ID: {{doc_id}}");

    try
    {
        InlineResponse201 resp = docs.PostDocument(dp);
        richTextBox1.Text = resp.ToJson();
    }
    catch (Exception ex)
    {
        throw ex;
    }
}

Ponte a programar​

Asegúrate de revisar la documentación generada por OpenAPI para diferentes tipos de llamadas y opciones.

Algunos errores comunes son:

El nombre del grupo debe coincidir exactamente con uno que ya tengas en tu organización.

Tu solicitud será denegada si tus credenciales son incorrectas, están desactualizadas o bloqueadas.

Un 401 regresará si estás en sandbox y tratas de enviar un documento a alguien que no está en la lista de correos sandbox.

¡Feliz programación!

Última actualización el

Export This Article

Save a copy of this page as PDF or plain text.