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 corrections à certains problèmes comme les champs nullables.

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 lorsqu'on vous le demande, et envoyez un email au Support pour obtenir une clé API. Vous devez montrer un niveau de compréhension sur l'utilisation de l’API REST, 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 la clé émise, elle sera disponible dans l’application web. Vous verrez que vous êtes en sandbox – ajoutez toutes les adresses emails vers lesquelles vous enverrez vos documents de test.

Votre clé API va dans l’en-tête "Authorization", et prend la forme : Apikey username:secret. Votre nom d’utilisateur et secret seront clairement indiqués dans l’application web.

Obtenez le SDK et les projets d’exemple​

Avec vos outils git préférés, clonez le dépôt du SDK C#.

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

Configurez le projet d’exemple :​

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

Pour gagner du temps, vous pouvez vouloir ajouter votre nom d’utilisateur, secret, nom du groupe, email cible, prénom et nom de famille comme propriétés Text pour txtUsername, txtSecretKey, etc. dans Form1. Sinon, vous devrez fournir ces informations lorsque vous exécuterez le projet Winform (assurez-vous que ce projet soit bien marqué comme projet de démarrage). Si vous les codez en dur, pensez à retirer ces informations une fois terminé avec le projet.

Regardons le premier bloc de code dans Form1.cs :

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

Vous pouvez voir comment on utilise ici le nom d’utilisateur et le secret que vous fournissez et les passe dans la configuration pour chaque appel que nous allons faire plus tard. C’est ainsi que les appels API sont autorisés.

Testez une requête GET :​

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

Le code suivant s’exécute quand vous cliquez sur le bouton Get Groups. Prenez un moment pour remarquer où l’information de Configuration est passée en utilisant makeConfig(). Lancez le projet, saisissez votre nom d’utilisateur et votre clé dans les champs si vous ne les avez pas codés dans les propriétés Text et 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 vous avez la bonne valeur pour Authorization.

Ce code récupère tous les documents en attente de signature, un cas d’usage courant. Testez-le en examinant puis en cliquant sur 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 pour interroger les informations basiques des documents.

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

Testez une requête POST​

Ensuite, nous allons envoyer un peu de HTML personnalisé à faire signer en un seul appel API, puis nous uploaderons un PDF et l’enverrons.

Envoyez un document HTML à signer :​

Voici un petit morceau de HTML à des fins de démonstration, contenant un élément signature. Remplacez les valeurs du 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 non 2XX. Vous voudrez placer toutes vos requêtes dans un bloc try/catch.

Chaque fois que vous faites un POST, vous voudrez probablement récupérer l’ID du nouvel objet. Il est dans l’en-tête Location de la réponse. Dans notre exemple suivant nous voyons comment uploader un PDF à envoyer aux signataires, et récupérer l’ID de ce nouveau template.

Uploadez et envoyez un PDF​

Vous utiliserez très probablement des text-tags dans vos PDFs, pour définir où les personnes signeront ou rempliront des formulaires. Le paramètre processTags=true indique au système de parcourir votre document pour créer des champs d’information et des signatures que le destinataire devra signer. Un exemple basique de PDF avec des tags est inclus à la racine du projet SDK.

Chargons 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 défini process_tags à true, tous les tags ont été traités et votre PDF est prêt à être utilisé. Comme avant, 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 de Send with Template montre comment nous utilisons ce chemin PDF pour envoyer un document préchargé à 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;
    }
}

Au travail !​

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

Quelques pièges courants :

Le nom du groupe doit correspondre exactement à un groupe que vous possédez déjà dans votre organisation.

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

Une erreur 401 sera renvoyée si vous êtes en sandbox et tentez d’envoyer un document à quelqu’un qui n’est pas dans votre liste d’emails sandbox.

Bon codage !

Dernière mise à jour le

Export This Article

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