Vai al contenuto principale

SDK C#

Raccomandiamo di programmare direttamente contro l'API, il riferimento tecnico e la tua IA lo rendono semplice. Un SDK C# può essere generato utilizzando la specifica OpenAPI3 della nostra API e openapi generator. Tuttavia, se desideri un SDK, ti consigliamo di utilizzare il progetto generato fornito, poiché include correzioni ad alcuni problemi come i campi nullable.

Click here for the C# repo..

Il pacchetto contiene la propria documentazione (in docs/), ma gli esempi seguenti ti mostreranno come iniziare.

Ottieni la tua API Key​

  • Iscriviti per un account di prova.

  • Configura per l'API quando richiesto, e invia un'email al Supporto per ottenere una API Key. Devi dimostrare una certa conoscenza nell'uso della REST API, includi nella tua email: il nome e l'indirizzo della tua azienda, il tuo nome e ruolo, descrivi il tuo caso d'uso, e fornisci un breve riassunto della tua esperienza di programmazione/REST.

  • Una volta rilasciata, la tua API key sarà disponibile nell'app web. Vedrai che sei in sandbox - aggiungi eventuali email a cui invierai i tuoi documenti di prova.

La tua API key va nell'intestazione "Authorization", e ha la forma: Apikey username:secret. Il tuo username e secret saranno chiaramente indicati nell'app web.

Ottieni l'SDK e i progetti di esempio​

Con i tuoi strumenti git preferiti clona il repository dell'SDK C#.

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

Configura il progetto di esempio:​

Apri LegalesignCsharpSDK.sln e compila il progetto. Dovresti vedere tre progetti inclusi nella soluzione, ci concentreremo sul LegalesignTest che ti farà iniziare a fare chiamate all'API REST.

Per risparmiare tempo potresti voler aggiungere il tuo username, secret, nome gruppo, email di destinazione, nome e cognome come proprietà Text per txtUsername, txtSecretKey ecc in Form1. Se no, dovrai fornire questi dati quando esegui il progetto Winform (assicurati che sia impostato come progetto di avvio). Se li inserisci hard-coded, ricordati di rimuovere queste informazioni al termine del progetto.

Diamo un'occhiata al primo blocco di codice in Form1.cs:

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

Puoi vedere come utilizza lo username e il secret che fornisci e li passa nella configurazione per ogni chiamata che faremo in seguito. Questo è il modo in cui le chiamate API vengono autorizzate.

Testa una richiesta GET:​

Assicuriamoci che tu possa fare una semplice richiesta GET, per verificare che la tua autenticazione sia configurata correttamente.

Il seguente codice viene eseguito quando clicchi sul pulsante Get Groups. Prenditi un momento per notare dove le informazioni di Configuration vengono passate usando makeConfig(). Esegui il progetto, inserisci il tuo username e la chiave nei campi se non li hai codificati nelle proprietà Text, e clicca sul pulsante Get Groups.

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

Se ha successo, otterrai una lista JSON dei tuoi gruppi.

Altrimenti ricontrolla di aver inserito correttamente il valore di Authorization.

Questo codice ottiene tutti i documenti in attesa di firma, un caso d'uso comune. Testalo esaminando e poi eseguendo il pulsante Get Documents.

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

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

Le chiamate 'get_statuses()' e 'get_status()' sono modi più veloci per interrogare informazioni di base sul documento.

Dovresti iniziare a capire come funziona l'SDK. Torna al file Readme del pacchetto, e vedrai tutti gli oggetti API da provare, e tutti i loro metodi.

Testa una richiesta POST​

Successivamente invieremo un po' di HTML personalizzato per la firma in una chiamata API, poi caricheremo un PDF e lo invieremo.

Invia un documento HTML da firmare:​

Ecco una piccola porzione di HTML a scopo dimostrativo, contenente un elemento firma. Sostituisci i valori di gruppo, nome e email.

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;
    }
}

Come facciamo a sapere se è andata a buon fine? OpenAPI genera un'eccezione per risposte non 2XX. Vorrai inserire tutte le tue richieste in un blocco try/catch.

Ogni volta che fai un POST, probabilmente vorrai l'ID del nuovo oggetto. È nell'header Location della risposta. Nel nostro prossimo esempio vediamo come caricare un PDF da inviare ai firmatari, e ottenere l'ID di quel nuovo template.

Carica e invia un PDF​

Probabilmente userai text-tags all'interno dei tuoi PDF, per definire dove le persone devono firmare o compilare moduli. Usare il parametro processTags=true fa sapere al sistema di analizzare il documento e creare campi per informazioni e firme da parte del destinatario. Un esempio base di PDF con tag è incluso nella root del progetto SDK.

Carichiamo un PDF usando la versione 'with_http_info' della richiesta POST per ottenere l'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;
        }
    }
}

Poiché abbiamo impostato process_tags a true, tutti i tag sono stati processati quindi il tuo PDF è pronto all'uso. Come prima, abbiamo bisogno dell'ID del PDF per poterlo inviare. Per fortuna lo abbiamo tenuto nella casella di testo txtPdfLocation.

L'ultimo frammento di codice da Send with Template mostra come usiamo quella posizione PDF per inviare un documento pre-caricato da firmare.

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;
    }
}

Inizia a programmare​

Assicurati di controllare la documentazione generata da OpenAPI per i diversi tipi di chiamate e opzioni.

Alcuni problemi comuni sono:

Il nome del gruppo deve corrispondere esattamente a uno che hai già nella tua organizzazione.

La tua richiesta sarà rifiutata se le tue credenziali sono errate, scadute o bloccate.

Un errore 401 ti verrà restituito se sei in sandbox e provi a inviare un documento a qualcuno che non è nella tua lista email sandbox.

Buona programmazione!

Ultimo aggiornamento il

Export This Article

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