Exemples complets

Scenarios complets d'utilisation du SDK bases sur la documentation officielle.

Scenario 1 : Envoi d'un message securise avec fichiers

using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.SecureExchanges;
using System;
using System.Collections.Generic;

// Identifiants SDK
Guid serial = new Guid("VOTRE-SERIAL-GUID");
Guid APIuser = new Guid("VOTRE-API-USER-GUID");
Guid APIpassword = new Guid("VOTRE-API-PASSWORD-GUID");
Uri endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

// Creer la liste de destinataires
List<RecipientInfo> recipientList = new List<RecipientInfo>();
recipientList.Add(new RecipientInfo() { Email = "destinataire@exemple.com" });

// Contenu du message
string message = "Mon message <strong>HTML</strong>";
string subject = "Mon sujet";
string password = null;

// Fichiers (approche binaire)
List<FileArgs> binaryFiles = new List<FileArgs>();

// Options d'envoi
var sendMethod = SendMethodEnum.onlyEmail;
bool sendByMyOwnSMTPServer = false;
bool showSubject = true;
bool getNotify = true;
string culture = "fr-CA";
int maxOpeningTime = 5;
int expirationMinutes = 30;

// Creer les arguments du message
var arg = new MutliRecipientArgs(
    endpoint, serial, APIuser, APIpassword, recipientList,
    message, subject, password, binaryFiles,
    sendMethod, sendByMyOwnSMTPServer, showSubject,
    getNotify, culture, maxOpeningTime, expirationMinutes
);

// Ajouter des fichiers par chemin
var filesPathList = new List<string>();
filesPathList.Add(@"c:\temp\document.pdf");
arg.FilesPath = filesPathList;

// Envoyer le message
var messageAnswer = MessageHelper.MultiRecipientMessage(arg);

if (messageAnswer.Status == 200)
{
    Console.WriteLine("Message envoye avec succes");
    foreach (var recipientAnswer in messageAnswer.RecipientsAnswer)
    {
        Console.WriteLine($"Statut: {recipientAnswer.Answer.Status}");
        Console.WriteLine($"URL: {recipientAnswer.Answer.URL}");
        // HtmlMsg contient le HTML complet en marque blanche pour l'envoi personnalise
        Console.WriteLine($"HTML: {recipientAnswer.Answer.HtmlMsg}");
    }
}
else
{
    Console.WriteLine(messageAnswer.Data);
}

Scenario 2 : Signature de contrat a deux parties (Processus sequentiel)

Cet exemple montre comment envoyer un contrat PDF a deux signataires. Le processus est sequentiel : seul le premier signataire recoit son URL immediatement, le second sera notifie apres que le premier ait complete.

using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.Models.JSON;
using SecureExchangesSDK.Models.Transport;
using SecureExchangesSDK.SecureExchanges;
using Newtonsoft.Json;
using System;
using System.Collections.Generic;

// Identifiants SDK
Guid serial = new Guid("VOTRE-SERIAL-GUID");
Guid APIuser = new Guid("VOTRE-API-USER-GUID");
Guid APIpassword = new Guid("VOTRE-API-PASSWORD-GUID");
Uri endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

// Creer deux destinataires (signataires)
List<RecipientInfo> recipientList = new List<RecipientInfo>();
recipientList.Add(new RecipientInfo() { Email = "signataire1@exemple.com" });
recipientList.Add(new RecipientInfo() { Email = "signataire2@exemple.com" });

// Contenu du message
string message = "Veuillez signer ce contrat.";
string subject = "Contrat necessitant votre signature";

// Creer les arguments du message
var arg = new MutliRecipientArgs(
    endpoint, serial, APIuser, APIpassword, recipientList,
    message, subject, null, null,
    SendMethodEnum.onlyEmail, false, true,
    true, "fr-CA", 5, 10080  // 7 jours d'expiration
);

// Chemin du fichier PDF
var filePath = @"c:\temp\contrat.pdf";
arg.FilesPath = new List<string> { filePath };

// Obtenir le hash SHA512 du fichier (requis pour le suivi des signatures)
string SHA512 = CryptoHelper.GetSHA512OfFile(filePath);

// Creer la liste des fichiers necessitant une signature
List<SignFilesRequired> signFiles = new List<SignFilesRequired>();
signFiles.Add(new SignFilesRequired()
{
    SHA512 = SHA512,
    DoNotAppendCertificateToFile = false
});

// Creer le dictionnaire de correspondance destinataire-zones
var recipientIndex = new Dictionary<RecipientInfo, List<FileZoneDefinition>>();

// Utiliser ZoneBuilder pour creer les zones de signature
using (var zoneBuilder = new ZoneBuilder(filePath, isPki: false))
{
    // Definir les zones de signature pour le Signataire 1
    var signer1Zones = new SignZoneDetails[]
    {
        zoneBuilder.CreateFieldSignZone(1, "signature_signataire1", 50, 650, 200, 50),
        zoneBuilder.CreateFieldDateSignZone(1, "date_signataire1", 260, 660, 100, 25, 12)
    };

    // Associer les zones au signataire 1
    recipientIndex.Add(recipientList[0], new List<FileZoneDefinition>()
    {
        new FileZoneDefinition
        {
            UniqueName = SHA512,
            ZonesDef = new SignZoneDefinition { Zones = signer1Zones }
        }
    });

    // Definir les zones de signature pour le Signataire 2
    var signer2Zones = new SignZoneDetails[]
    {
        zoneBuilder.CreateFieldSignZone(1, "signature_signataire2", 50, 550, 200, 50),
        zoneBuilder.CreateFieldDateSignZone(1, "date_signataire2", 260, 560, 100, 25, 12)
    };

    // Associer les zones au signataire 2
    recipientIndex.Add(recipientList[1], new List<FileZoneDefinition>()
    {
        new FileZoneDefinition
        {
            UniqueName = SHA512,
            ZonesDef = new SignZoneDefinition { Zones = signer2Zones }
        }
    });
}

// Configurer les options de signature
arg.FileToSign = signFiles;
arg.OwnerDontNeedToSign = true;
arg.SignRecipientsZoneDef = SignHelper.ConvertRecipientIndexToList(recipientIndex);

// CallBackParameters : Parametres personnalises qui persistent tout au long du processus.
// Essentiels pour l'integration SESAR - ils peuvent etre recuperes pour classer les documents signes.
arg.CallBackParameters = JsonConvert.SerializeObject(new List<CallBackParameter>
{
    new CallBackParameter("ClientId", "CLI-12345"),
    new CallBackParameter("NumeroDossier", "DOS-2024-001"),
    new CallBackParameter("TypeDocument", "Contrat")
});

// Envoyer le message
var messageAnswer = MessageHelper.MultiRecipientMessage(arg);

// Traiter la reponse
// IMPORTANT : Seul le premier signataire est traite immediatement.
// Le second signataire sera notifie automatiquement apres que le premier ait signe.
if (messageAnswer.Status == 200)
{
    Console.WriteLine("Contrat envoye pour signature");

    // Informations du premier signataire
    var firstSignerAnswer = messageAnswer.RecipientsAnswer[0].Answer;
    Console.WriteLine($"URL Signataire 1: {firstSignerAnswer.URL}");
    Console.WriteLine($"Code Signataire 1: {firstSignerAnswer.DefaultOpeningCode}");

    // HtmlMsg contient le HTML complet en marque blanche pour l'envoi personnalise
    // Utilisez ceci pour envoyer des courriels depuis votre propre serveur SMTP
    Console.WriteLine($"HTML marque blanche disponible: {!string.IsNullOrEmpty(firstSignerAnswer.HtmlMsg)}");
}
else
{
    Console.WriteLine(messageAnswer.Data);
}

Comprendre le processus sequentiel

  1. Requete initiale : Lorsque vous appelez MultiRecipientMessage, seul le premier signataire est active
  2. Premier signataire : Recoit son URL/courriel immediatement et peut signer le document
  3. Progression automatique : Apres que le premier signataire complete, le systeme notifie automatiquement le second
  4. Courriels en marque blanche : Utilisez Answer.HtmlMsg pour envoyer des courriels depuis votre propre serveur SMTP

CallBackParameters et integration SESAR

La propriete CallBackParameters est essentielle lors de l'integration avec SESAR (Secure Exchanges Storage And Retrieval). Ces parametres :

  • Persistent tout au long du processus : De l'envoi initial jusqu'a la completion de toutes les signatures
  • Sont chiffres sur les serveurs Secure Exchanges : Securises mais recuperables par votre systeme
  • Permettent la classification des documents : SESAR peut recuperer ces parametres pour classer automatiquement les documents signes
// Definir les parametres de callback pour votre contexte d'affaires
var callbackParams = new List<CallBackParameter>
{
    new CallBackParameter("ClientId", "CLI-12345"),
    new CallBackParameter("NumeroDossier", "DOS-2024-001"),
    new CallBackParameter("TypeDocument", "Contrat"),
    new CallBackParameter("Departement", "Ventes")
};

// Serialiser et assigner aux arguments du message
arg.CallBackParameters = JsonConvert.SerializeObject(callbackParams);

Lorsque le processus de signature est termine, SESAR recoit ces parametres et peut les utiliser pour :

  • Classer automatiquement le document signe dans le bon dossier client
  • Mettre a jour votre systeme d'affaires avec le statut de signature
  • Declencher des flux de travail en aval selon le type de document

Scenario 3 : Signature complete avec tous les types de zones

Cet exemple demontre tous les types de zones de signature disponibles.

var filePath = @"c:\temp\document.pdf";
string SHA512 = CryptoHelper.GetSHA512OfFile(filePath);

// Creer des zones avec tous les types disponibles
var zones = new List<SignZoneDetails>();

using (var zoneBuilder = new ZoneBuilder(filePath, isPki: false))
{
    // Champ texte
    zones.Add(zoneBuilder.CreateFieldTextZone(1, "nomComplet", 10, 700, 200, 30, "Entrez votre nom", 14, true));

    // Champ nombre
    zones.Add(zoneBuilder.CreateFieldNumberZone(1, "montant", 10, 650, 100, 30, 0, 14, true));

    // Selecteur de date (l'utilisateur choisit la date)
    zones.Add(zoneBuilder.CreateFieldDateZone(1, "dateContrat", 10, 600, 150, 30, 12, true));

    // Date de signature (remplie automatiquement avec l'horodatage de la signature)
    zones.Add(zoneBuilder.CreateFieldDateSignZone(1, "dateSignature", 10, 550, 150, 30, 12));

    // Zone de signature
    zones.Add(zoneBuilder.CreateFieldSignZone(1, "signature", 10, 450, 200, 60));

    // Zone d'initiales
    zones.Add(zoneBuilder.CreateFieldInitialZone(1, "initiales", 10, 400, 60, 30));

    // Cases a cocher
    zones.Add(zoneBuilder.CreateFieldCheckBoxZone(1, "accepteConditions", 10, 350, false, true));
    zones.Add(zoneBuilder.CreateFieldCheckBoxZone(1, "infolettre", 10, 320, true, false));

    // Boutons radio (meme groupId pour exclusion mutuelle)
    zones.Add(zoneBuilder.CreateFieldRadioZone(1, "Cheque", 10, 280, "modePaiement", false));
    zones.Add(zoneBuilder.CreateFieldRadioZone(1, "Virement", 40, 280, "modePaiement", true));
}

Scenario 4 : Signature PKI avec certification PDF

Cet exemple montre le processus complet de signature PKI avec certification du document PDF.

using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.Models.Transport;
using SecureExchangesSDK.SecureExchanges;
using SecureExchangesSignatureSDK.Helpers;
using SecureExchangesSignatureSDK.Models;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;

// Identifiants SDK
Uri endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");
Guid serial = new Guid("VOTRE-SERIAL-GUID");
Guid apiUser = new Guid("VOTRE-API-USER-GUID");
Guid apiPassword = new Guid("VOTRE-API-PASSWORD-GUID");

// 1. Charger le fichier PDF a signer
string pdfPath = @"c:\temp\contrat.pdf";
string pdfName = Path.GetFileName(pdfPath);
byte[] pdfBytes = File.ReadAllBytes(pdfPath);
string sha512 = CryptoHelper.GetSHA512HashOfBytes(pdfBytes);

// 2. Creer les zones de signature avec ZoneBuilder (mode PKI)
SignZoneDetails[] zones;
using (var zoneBuilder = new ZoneBuilder(pdfPath, isPki: true))
{
    zones = new SignZoneDetails[]
    {
        zoneBuilder.CreateFieldSignZone(1, "signature1", 100, 650, 200, 50),
        zoneBuilder.CreateFieldDateSignZone(1, "date1", 100, 600, 100, 25, 12)
    };
}

// 3. Associer les zones au destinataire
var recipient = new RecipientInfo { Email = "signataire@exemple.com" };
var recipientIndex = new Dictionary<RecipientInfo, List<FileZoneDefinition>>
{
    {
        recipient,
        new List<FileZoneDefinition>
        {
            new FileZoneDefinition
            {
                UniqueName = sha512,
                ZonesDef = new SignZoneDefinition { Zones = zones }
            }
        }
    }
};

var recipients = new List<RecipientInfo> { recipient };

// 4. Obtenir le token de certification
var certificationTokenArgs = new GetCertificationTokenSDKArgs(
    endpoint,
    serial,
    apiUser,
    apiPassword,
    sha512,
    CertificationTokenType.CertifyDocument,
    "fr-CA"
);

var certificationTokenResponse = SignHelper.GetCertificationToken(certificationTokenArgs);

// 5. Certifier le PDF avec PkiFileHelper
var certifyPdfArgs = new CertifyPdfArgs
{
    File = new FileArgs(pdfBytes, pdfName, FileHelper.GetMimeType(pdfName)),
    RecipientZoneDefinitions = SignHelper.ConvertRecipientIndexToList(recipientIndex),
    Recipients = recipients.Select(r => r.Email).ToList(),
    CertifyData = certificationTokenResponse.CertificationData,
    DetectExistingFields = false
};

CertifiedPdfContainer certifiedPdf;
using (var pkiHelper = new PkiFileHelper())
{
    try
    {
        // Le helper peut etre reutilise pour plusieurs PDFs
        certifiedPdf = await pkiHelper.CertifyPkiPdf(certifyPdfArgs);
    }
    catch (Exception ex)
    {
        throw new Exception($"Echec de la certification PDF: {ex.Message}");
    }
}

// 6. Configurer et envoyer le message
var args = new MutliRecipientArgs(
    endpoint,
    serial,
    apiUser,
    apiPassword,
    recipients,
    "Veuillez signer ce contrat",
    "Contrat a signer",
    null,
    null,
    SendMethodEnum.onlyEmail,
    false,
    true,
    true,
    "fr-CA",
    5,
    10080  // 7 jours
)
{
    OwnerDontNeedToSign = true,
    CertifiedPdfs = new List<CertifiedPdfContainer> { certifiedPdf }
};

// 7. Envoyer le message
var response = MessageHelper.MultiRecipientMessage(args);

if (response.Status == 200)
{
    Console.WriteLine("Document PKI envoye pour signature");
    var signerAnswer = response.RecipientsAnswer[0].Answer;
    Console.WriteLine($"URL: {signerAnswer.URL}");
    Console.WriteLine($"Code: {signerAnswer.DefaultOpeningCode}");
}
else
{
    Console.WriteLine($"Erreur: {response.Data}");
}

Etapes du processus PKI

  1. Charger le PDF : Lire le fichier et calculer son hash SHA512
  2. Creer les zones : Utiliser ZoneBuilder avec isPki: true
  3. Obtenir le token : Appeler SignHelper.GetCertificationToken() pour obtenir les donnees de certification
  4. Certifier le PDF : Utiliser PkiFileHelper.CertifyPkiPdf() pour preparer le document
  5. Envoyer : Passer le CertifiedPdfContainer dans MutliRecipientArgs.CertifiedPdfs

Voir aussi