Guide de demarrage

Ce guide vous accompagne dans l'installation et la configuration du Secure Exchanges SDK.

Prerequis

Visual Studio 2019+ ou Visual Studio Code avec extension C#
.NET Framework 4.7.2+ ou .NET 8.0+ (voir la table des packages ci-dessous)
Licence Secure Exchanges avec acces API
Connexion Internet pour communiquer avec les serveurs Secure Exchanges

Installation

Choisissez le package qui correspond à votre framework cible :

Framework cible	SDK principal	SDK Signature (optionnel)
.NET Framework 4.7.2+ (Windows uniquement)	`SecureExchanges`	`SecureExchanges.Signature`
.NET 8+ (Windows + Linux)	`SecureExchanges.NetCore`	`SecureExchanges.Signature.NetCore`

Note

La variante .NetCore est requise pour un déploiement sur Linux (par exemple Azure Functions en container Linux). Pour les spécificités du SDK Signature, voir Certification PDF.

.NET Framework

Install-Package SecureExchanges

.NET 8+ / .NET Core

Install-Package SecureExchanges.NetCore

Via .NET CLI

# .NET Framework
dotnet add package SecureExchanges

# .NET 8+ / .NET Core
dotnet add package SecureExchanges.NetCore

Via PackageReference

<!-- .NET Framework -->
<PackageReference Include="SecureExchanges" Version="*" />

<!-- .NET 8+ / .NET Core -->
<PackageReference Include="SecureExchanges.NetCore" Version="*" />

Obtention des identifiants API

Etape 1 : Connexion au portail

Accedez au portail Secure Exchanges
Connectez-vous avec un compte administrateur ou le compte API

Etape 2 : Acces a la gestion des utilisateurs

Cliquez sur Compte dans le menu
Selectionnez Options > Gestion des utilisateurs

Etape 3 : Attribution de la licence API

Localisez l'utilisateur qui utilisera l'API
Cliquez sur l'icone Gerer les licences
Attribuez une licence API a cet utilisateur
Cliquez sur Sauvegarder

Etape 4 : Generation des cles

Cliquez sur l'icone Cle API (a cote de l'utilisateur)
Un message securise contenant vos identifiants sera envoye
Un mot de passe vous sera fourni pour ouvrir ce message

Important

Le message contenant vos cles expire apres 15 minutes. Ouvrez-le rapidement et conservez vos identifiants en lieu sur.

Vos identifiants

Vous recevrez trois valeurs :

Identifiant	Description
Serial	Numero de serie de votre licence (GUID)
API User	Identifiant utilisateur API (GUID)
API Password	Mot de passe API (GUID)

Configuration de base

Configuration minimale

using System;
using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;

public class SecureExchangesConfig
{
    // Vos identifiants API
    public static Guid Serial = new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");
    public static Guid ApiUser = new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");
    public static Guid ApiPassword = new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");

    // Endpoint (production ou preview pour les tests)
    public static Uri Endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");
}

Configuration via App.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="SecureExchanges:Serial" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />
    <add key="SecureExchanges:ApiUser" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />
    <add key="SecureExchanges:ApiPassword" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />
    <add key="SecureExchanges:Endpoint" value="https://www.secure-exchanges.com/_api/0217/0217.asmx" />
  </appSettings>
</configuration>

using System.Configuration;

public class SecureExchangesConfig
{
    public static Guid Serial => new Guid(ConfigurationManager.AppSettings["SecureExchanges:Serial"]);
    public static Guid ApiUser => new Guid(ConfigurationManager.AppSettings["SecureExchanges:ApiUser"]);
    public static Guid ApiPassword => new Guid(ConfigurationManager.AppSettings["SecureExchanges:ApiPassword"]);
    public static Uri Endpoint => new Uri(ConfigurationManager.AppSettings["SecureExchanges:Endpoint"]);
}

Warning

Ne stockez jamais vos identifiants API en clair dans le code source. Utilisez des variables d'environnement ou un gestionnaire de secrets.

Premier test : Verification de la licence

using SecureExchangesSDK.Helpers;

// Verifier que la licence est valide
bool isValid = LicenceHelper.IsLicenceIsValid(
    SecureExchangesConfig.Endpoint,
    SecureExchangesConfig.Serial,
    SecureExchangesConfig.ApiUser,
    SecureExchangesConfig.ApiPassword
);

if (isValid)
{
    Console.WriteLine("Licence valide ! Configuration correcte.");
}
else
{
    Console.WriteLine("Licence invalide. Verifiez vos identifiants.");
}

Envoi de votre premier message

Version rapide

using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.SecureExchanges;

// Destinataire
var recipients = new List<RecipientInfo>
{
    new RecipientInfo { Email = "destinataire@example.com" }
};

// Endpoint
Uri endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

// Envoyer
var args = new MutliRecipientArgs(
    endpoint, Serial, ApiUser, ApiPassword,
    recipients, "Mon message securise", "Sujet",
    null, null, SendMethodEnum.onlyEmail,
    false, true, true, "fr-CA", 5, 1440
);

var response = MessageHelper.MultiRecipientMessage(args);
Console.WriteLine(response.Status == 200 ? "Envoye!" : response.Data);

Version complete avec gestion d'erreurs

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

public class MessageService
{
    private readonly Guid _serial;
    private readonly Guid _apiUser;
    private readonly Guid _apiPassword;
    private readonly Uri _endpoint;

    private static readonly Uri DefaultEndpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

    public MessageService(Guid serial, Guid apiUser, Guid apiPassword, Uri endpoint = null)
    {
        _serial = serial;
        _apiUser = apiUser;
        _apiPassword = apiPassword;
        _endpoint = endpoint ?? DefaultEndpoint;
    }

    /// <summary>
    /// Envoie un message securise a un destinataire
    /// </summary>
    /// <param name="recipientEmail">Email du destinataire</param>
    /// <param name="subject">Sujet du message</param>
    /// <param name="htmlBody">Corps du message (HTML autorise)</param>
    /// <param name="password">Mot de passe optionnel pour proteger le message</param>
    /// <returns>URL du message si succes, null sinon</returns>
    public string SendSecureMessage(
        string recipientEmail,
        string subject,
        string htmlBody,
        string password = null)
    {
        try
        {
            // Validation des parametres
            if (string.IsNullOrWhiteSpace(recipientEmail))
                throw new ArgumentException("L'email du destinataire est requis");
            if (string.IsNullOrWhiteSpace(subject))
                throw new ArgumentException("Le sujet est requis");
            if (string.IsNullOrWhiteSpace(htmlBody))
                throw new ArgumentException("Le corps du message est requis");

            // Creation de la liste des destinataires
            var recipients = new List<RecipientInfo>
            {
                new RecipientInfo { Email = recipientEmail }
            };

            // Configuration des arguments
            var args = new MutliRecipientArgs(
                _endpoint,
                _serial,
                _apiUser,
                _apiPassword,
                recipients,
                htmlBody,
                subject,
                password,
                filesList: null,
                SendMethodEnum.onlyEmail,
                sendByMyOwnSMTPServer: false,
                showSubject: true,
                getNotify: true,
                culture: "fr-CA",
                maxOpeningTime: 5,        // 5 ouvertures maximum
                expirationMinutes: 1440   // 24 heures
            );

            // Envoi du message
            MultiRecipientAnswer response = MessageHelper.MultiRecipientMessage(args);

            // Verification du resultat
            if (response.Status == 200)
            {
                var recipientAnswer = response.RecipientsAnswer[0].Answer;
                Console.WriteLine($"Message envoye avec succes!");
                Console.WriteLine($"URL: {recipientAnswer.URL}");
                Console.WriteLine($"Code d'ouverture: {recipientAnswer.DefaultOpeningCode}");
                return recipientAnswer.URL;
            }
            else
            {
                Console.WriteLine($"Erreur lors de l'envoi: {response.Data}");
                Console.WriteLine($"Code de statut: {response.Status}");
                return null;
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Exception: {ex.Message}");
            return null;
        }
    }
}

// Utilisation
class Program
{
    static void Main(string[] args)
    {
        var service = new MessageService(
            SecureExchangesConfig.Serial,
            SecureExchangesConfig.ApiUser,
            SecureExchangesConfig.ApiPassword
        );

        string messageUrl = service.SendSecureMessage(
            "destinataire@example.com",
            "Information confidentielle",
            "<h1>Bonjour</h1><p>Voici votre document confidentiel.</p>"
        );

        if (messageUrl != null)
        {
            Console.WriteLine($"Message accessible a: {messageUrl}");
        }
    }
}

Environnements disponibles

Environnement	Endpoint	Usage
Production	`https://www.secure-exchanges.com/_api/0217/0217.asmx`	Applications en production
Preview	`https://preview.secure-exchanges.com/_api/0217/0217.asmx`	Tests et validation

Configuration pour l'environnement Preview

// Pour utiliser l'environnement de test
Uri endpoint = new Uri("https://preview.secure-exchanges.com/_api/0217/0217.asmx");

// Configuration supplementaire pour Preview
SettingsHelper.CustomFileHandler = "https://preview.secure-exchanges.com/Handler/ReadFileTob64.ashx";
SettingsHelper.CustomSEMSEndpoint = "https://previewsems.secure-exchanges.com/SEMS_api.asmx";