Zum Hauptinhalt springen

C# SDK

Wir empfehlen, direkt gegen die API zu programmieren, da das technische Referenzdokument und Ihre KI dies unkompliziert machen. Ein C# SDK kann mit der OpenAPI3-Spezifikation unserer API und dem openapi generator generiert werden. Wenn Sie jedoch ein SDK möchten, empfehlen wir Ihnen, das bereitgestellte generierte Projekt zu verwenden, da es Korrekturen für einige Probleme wie Nullable-Felder enthält.

Hier klicken für das C#-Repo..

Das Paket enthält eine eigene Dokumentation (im Verzeichnis docs/), aber die folgenden Beispiele zeigen Ihnen, wie Sie loslegen.

Holen Sie sich Ihren API-Schlüssel​

  • Melden Sie sich für ein Testkonto an.

  • Konfigurieren Sie API, wenn Sie dazu aufgefordert werden, und senden Sie eine E-Mail an den Support, um einen API-Schlüssel zu erhalten. Sie müssen ein gewisses Verständnis für die Verwendung von REST-APIs nachweisen, und in Ihrer E-Mail Folgendes angeben: Ihren Firmennamen und Adresse, Ihren Namen und Ihre Rolle, beschreiben Sie Ihren Anwendungsfall und geben Sie eine kurze Zusammenfassung Ihrer Programmier- und REST-Erfahrung.

  • Sobald er ausgestellt wurde, steht Ihr API-Schlüssel in der Web-App zur Verfügung. Sie werden sehen, dass Sie sich in der Sandbox befinden – fügen Sie hier alle E-Mails hinzu, an die Sie Ihre Testdokumente senden werden.

Ihr API-Schlüssel wird im „Authorization“-Header übergeben und hat das Format: Apikey username:secret. Ihr Benutzername und Secret werden in der Web-App deutlich angezeigt.

Holen Sie sich das SDK und Beispielprojekte​

Klonen Sie mit den von Ihnen gewählten Git-Tools das C# SDK-Repository.

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

Konfigurieren des Beispielprojekts:​

Öffnen Sie die LegalesignCsharpSDK.sln und erstellen Sie das Projekt. Sie sollten drei Projekte in der Lösung sehen; wir konzentrieren uns auf das LegalesignTest, das Ihnen den Einstieg in REST API-Aufrufe erleichtert.

Um Zeit zu sparen, können Sie Ihren Benutzernamen, Secret, Gruppennamen, Ziel-E-Mail, Vor- und Nachnamen als Text-Eigenschaften der Felder txtUsername, txtSecretKey usw. in Form1 hinzufügen. Andernfalls müssen Sie diese eingeben, wenn Sie das Winform-Projekt ausführen (stellen Sie sicher, dass dies als Startprojekt markiert ist). Wenn Sie sie hart kodieren, denken Sie daran, diese Informationen zu entfernen, sobald Sie mit dem Projekt fertig sind.

Sehen wir uns den ersten Codeblock in Form1.cs an:

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

Sie sehen, wie hier der von Ihnen angegebene Benutzername und Secret verwendet und bei jedem späteren Aufruf in die Konfiguration übergeben werden. So werden API-Aufrufe autorisiert.

Testen einer GET-Anfrage:​

Stellen wir sicher, dass Sie eine einfache GET-Anfrage machen können, um zu überprüfen, ob Ihre Authentifizierung richtig konfiguriert ist.

Der folgende Code wird ausgeführt, wenn Sie auf die Schaltfläche Get Groups klicken. Nehmen Sie sich etwas Zeit, um zu sehen, wie die Konfigurationsinformationen über makeConfig() übergeben werden. Führen Sie das Projekt aus, geben Sie Ihren Benutzernamen und Schlüssel in die Felder ein, falls Sie diese nicht in der Text-Eigenschaft hinterlegt haben, und klicken Sie auf die Schaltfläche Get Groups.

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

Bei Erfolg erhalten Sie eine JSON-Liste Ihrer Gruppen.

Falls nicht, überprüfen Sie, ob der Wert für die Autorisierung korrekt ist.

Dieser Code ruft alle Dokumente ab, die auf eine Unterschrift warten – ein häufiger Anwendungsfall. Testen Sie dies, indem Sie die Schaltfläche Get Documents prüfen und ausführen.

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

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

Die Aufrufe 'get_statuses()' und 'get_status()' sind schnellere Möglichkeiten, grundlegende Dokumentinformationen abzufragen.

Sie sollten beginnen zu verstehen, wie das SDK funktioniert. Gehen Sie zurück zur Readme-Datei des Pakets, dort finden Sie alle API-Objekte zum Ausprobieren und deren Methoden.

Testen einer POST-Anfrage​

Als nächstes senden wir ein benutzerdefiniertes HTML-Dokument zur Unterschrift in einem API-Aufruf, dann laden wir eine PDF hoch und senden dieses.

Ein HTML-Dokument zum Signieren senden:​

Hier ist ein kleines HTML-Beispiel für Demo-Zwecke, das ein Signaturfeld enthält. Ersetzen Sie die Werte für Gruppe, Namen und E-Mail.

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

Wie wissen wir, dass es durchgegangen ist? OpenAPI wirft bei Nicht-2XX-Antworten eine Ausnahme. Sie möchten alle Ihre Anfragen in einen try/catch-Block einfügen.

Jedes Mal, wenn Sie POST ausführen, möchten Sie wahrscheinlich die neue Objekt-ID haben. Diese befindet sich im Location-Header der Antwort. Im nächsten Beispiel sehen wir, wie man ein PDF hochlädt, um es an Unterzeichner zu senden, und die ID für die neue Vorlage zurückerhält.

Hochladen und Versenden eines PDFs​

Wahrscheinlich werden Sie Text-Tags in Ihren PDFs verwenden, um zu definieren, wo Personen unterschreiben oder Formulare ausfüllen sollen. Der Parameter processTags=true teilt dem System mit, dass es Ihr Dokument durchsuchen und Felder für Informationen und Unterschriften für den Empfänger erstellen soll. Ein einfaches Beispiel für ein PDF mit Tags ist im Stammverzeichnis des SDK-Projekts enthalten.

Laden wir eine PDF mit der 'with_http_info'-Version der POST-Anfrage hoch, um die ID zu erhalten

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

Da wir process_tags auf true gesetzt haben, wurden alle Tags verarbeitet, sodass Ihr PDF bereit ist. Wie zuvor benötigen wir die ID für das PDF, damit wir es senden können. Zum Glück haben wir diese im Textfeld txtPdfLocation gespeichert.

Der letzte Codeausschnitt aus Send with Template zeigt, wie wir den PDF-Standort verwenden, um ein vorab geladenes Dokument zum Signieren zu senden.

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

Los geht's mit dem Programmieren​

Lesen Sie unbedingt die mit OpenAPI generierte Dokumentation zu verschiedenen Aufruftypen und Optionen.

Einige häufige Fallstricke sind:

Der Gruppenname muss genau mit einem in Ihrer Organisation vorhandenen übereinstimmen.

Ihre Anfrage wird abgelehnt, wenn Ihre Zugangsdaten falsch, veraltet oder gesperrt sind.

Eine 401-Antwort erhalten Sie, wenn Sie sich in der Sandbox befinden und versuchen, ein Dokument an jemanden zu senden, der nicht auf Ihrer Sandbox-E-Mail-Liste steht.

Viel Spaß beim Programmieren!

Letztes Update am

Export This Article

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