Aller au contenu principal

SDK C#

Nous recommandons de coder directement contre l’API, la référence technique et votre IA rendent cela simple. Un SDK C# peut être généré en utilisant la spécification OpenAPI3 de notre API et openapi generator. Cependant, si vous voulez un SDK, nous vous recommandons d’utiliser le projet généré fourni, car il inclut des correctifs pour certains problèmes comme les champs nullable.

Cliquer ici pour le dépôt C#.

Le package contient sa propre documentation (dans docs/), mais les exemples ci-dessous vous montreront comment commencer.

Obtenez votre clé API​

  • Inscrivez-vous pour un compte d’essai.

  • Configurez pour l’API lorsque cela est demandé, et envoyez un email au Support pour obtenir une clé API. Vous devez démontrer une certaine compréhension de l’utilisation de REST API, incluez dans votre email : le nom et l’adresse de votre entreprise, votre nom et rôle, décrivez votre cas d’utilisation, et donnez un bref résumé de votre expérience en programmation/REST.

  • Une fois délivrée, votre clé API sera disponible dans l’application web. Vous verrez que vous êtes en mode sandbox avec une limitation de 100 appels par heure.

Votre clé API va dans l’en-tête "Authorization", et prend la forme : Bearer <votre-clé-api>.
Votre clé API sera clairement indiquée dans le Developer Portal.

Obtenez le SDK et les projets d’exemple​

Avec vos outils git de prédilection, clonez le dépôt du SDK C#.

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

Configurez le projet Exemple :​

Ouvrez LegalesignCsharpSDK.sln et compilez le projet. Vous devriez voir trois projets inclus dans la solution, nous nous concentrerons sur LegalesignTest qui vous aidera à commencer à faire des appels à l’API REST.

Pour gagner du temps, vous voudrez peut-être ajouter votre nom d’utilisateur, secret, nom de groupe, email cible, prénom et nom de famille comme propriétés Text des champs txtUsername, txtSecretKey etc dans Form1. Sinon, vous devrez fournir ces informations lors de l’exécution du projet Winform (assurez-vous que ce projet est défini comme projet de démarrage). Si vous les codez en dur, n’oubliez pas de retirer ces informations une fois que vous avez fini avec le projet.

Regardons le premier bloc de code dans Form1.cs :

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

Vous pouvez voir comment cela utilise le nom d’utilisateur et le secret que vous fournissez et les passe dans la configuration pour chaque appel que nous effectuerons plus tard. Ceci est la façon dont les appels API sont autorisés.

Testez une requête GET :​

Assurons-nous que vous pouvez effectuer une requête GET simple, pour vérifier que votre Auth est bien configurée.

Le code suivant s’exécute lorsque vous cliquez sur le bouton Get Groups. Prenez le temps de remarquer où les informations de Configuration sont passées en utilisant makeConfig(). Exécutez le projet, entrez votre nom d’utilisateur et clé dans les zones si vous ne les avez pas mises dans la propriété Text, puis cliquez sur le bouton Get Groups.

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

Si c’est réussi, vous obtiendrez une liste JSON de vos groupes.

Sinon, vérifiez que votre valeur Authorization est correcte.

Ce code récupère tous les documents en attente de signature, un cas d’usage courant. Testez-le en examinant puis en exécutant le bouton Get Documents.

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

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

Les appels get_statuses() et get_status() sont des moyens plus rapides de récupérer des informations docs basiques.

Vous devriez commencer à comprendre comment fonctionne le SDK. Retournez au fichier Readme du package, vous verrez tous les objets API à essayer, ainsi que toutes leurs méthodes.

Testez une requête POST​

Ensuite, nous enverrons un HTML personnalisé pour signature en un seul appel API,
puis nous téléverserons un PDF et l’enverrons.

Envoyer un document HTML à faire signer :​

Voici un petit bout de HTML à des fins de démonstration, contenant un élément signature. Remplacez les valeurs de groupe, nom et 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;
    }
}

Comment savons-nous que c’est passé ? OpenAPI lance une exception pour les réponses hors 2XX. Vous voudrez mettre toutes vos requêtes dans un bloc try/catch.

Chaque fois que vous POSTEZ, vous voudrez probablement obtenir le nouvel ID d’objet. Il est dans l’en-tête Location de la réponse. Dans notre prochain exemple, nous voyons comment téléverser un PDF à envoyer aux signataires, et récupérer l’ID correspondant pour ce nouveau template.

Téléversez et envoyez un PDF​

Vous utiliserez très probablement des balises textuelles dans vos PDFs, pour définir où les personnes signeront ou rempliront des formulaires. L’utilisation du paramètre processTags=true indique au système de parcourir votre document et de créer des champs pour les informations et signatures à compléter par le destinataire. Un exemple basique de PDF avec balises est inclus à la racine du projet SDK.

Téléversons un PDF en utilisant la version 'with_http_info' de la requête POST pour obtenir 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;
        }
    }
}

Parce que nous avons passé process_tags à true, toutes les balises ont été traitées, donc votre PDF est prêt. Comme précédemment, nous avons besoin de l’ID du PDF pour pouvoir l’envoyer. Heureusement, nous l’avons conservé dans la zone de texte txtPdfLocation.

Le dernier extrait de code issu de Send with Template montre comment nous utilisons cet emplacement PDF pour envoyer un document préchargé à faire signer.

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

Commencez à coder​

Assurez-vous de consulter la documentation générée par OpenAPI pour les différents types d’appels et leurs options.

Quelques pièges courants sont :

Le nom de groupe doit correspondre exactement à un groupe que vous avez déjà dans votre organisation.

Votre requête sera refusée si vos identifiants sont incorrects, périmés ou verrouillés.

Bon codage !

Dernière mise à jour le

Export This Article

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