Table of Contents

Enveloppes

Demander des documents ou une réponse à quelqu'un de façon sécurisée. Le SDK crée une enveloppe : un lien vers un formulaire de réponse chiffré, propre à chaque destinataire.

Prérequis

Vos identifiants : voir Identifiants et environnements.

Une personne

GetEnveloppe retourne l'adresse de l'enveloppe. C'est votre application qui la transmet à la personne.

var args = new GetEnveloppeArgs(endpoint, serial, apiUser, apiPassword,
    subject: "Pièces justificatives",       // en clair dans le lien de l'enveloppe
    destination: "client@example.com",      // expéditeur de la réponse : adresse valide
    cultureID: "fr-CA")
{
    MaximumReplyOpenTime = 3,                // sinon une seule ouverture en .NET
    ReplyExpirationHours = 72,
    AuthorizedExtensions = new[] { ".pdf", ".jpg" },
};

GetEnveloppeResponse response = MessageHelper.GetEnveloppe(args);

if (response != null && response.StatusCode == 200)
{
    Uri lien = response.Url;   // à transmettre à la personne ; ne le journalisez pas
}

Plusieurs personnes

GetEnvelopes crée une enveloppe par personne. Un numéro de téléphone active une vérification par code SMS avant l'accès au formulaire.

var personnes = new List<Recipient>   // SecureExchangesSDK.SecureExchanges.Recipient
{
    new Recipient { Email = "client@example.com", Phone = "+15145550123" },
    new Recipient { Email = "conjoint@example.com" },
};

var args = new GetEnvelopesArgs(endpoint, serial, apiUser, apiPassword,
    "Pièces justificatives", personnes, "fr-CA")
{
    MaximumReplyOpenTime = 3,
    ReplyExpirationHours = 72,
};

GetEnvelopesResponse response = MessageHelper.GetEnvelopes(args);

foreach (GetEnveloppeResponse enveloppe in response.Answers)
{
    if (enveloppe.StatusCode == 200)
        Transmettre(enveloppe.Recipient, enveloppe.Url);
    else
        journal.LogWarning("Enveloppe refusée, statut {Status}", enveloppe.StatusCode);
}

Passez chaque personne sous forme de dictionnaire (tableau associatif) à clés Email et Phone, et non d'objet RecipientInfo : en Python, la personne serait omise de la réponse ; en PHP, l'appel échouerait.

Options

Option Défaut Rôle
MaximumReplyOpenTime 3 en Python et PHP ; 1 en .NET Nombre de fois où vous pourrez ouvrir la réponse, de 1 à 99.
ReplyExpirationHours 24 Durée de validité de l'enveloppe, en heures, dans la limite de conservation des licences.
AuthorizedExtensions Tous les types Types de fichiers acceptés, par exemple .pdf.
NotifyWhenRead true Avertit la personne qui a répondu quand vous ouvrez sa réponse.
ReplyOptions Aucune NoEditor masque l'éditeur de texte : la réponse doit alors contenir au moins un fichier. Password permet à la personne de protéger sa réponse par un mot de passe. NoSign l'empêche de demander la signature des fichiers qu'elle joint.
CallBackParameters Aucun Données rattachées à la réponse, par exemple un numéro de dossier. Elles ne sont conservées que si votre organisation utilise SESAR : elles accompagnent alors la copie de chaque réponse que reçoit SESAR. Sans SESAR, elles sont ignorées. Format : voir Format des paramètres de rappel.
ReplyToAPI false Obsolète et sans effet : le serveur l'ignore. Ne l'utilisez pas.

En .NET, aucun constructeur ne donne de valeur à MaximumReplyOpenTime ni à ReplyExpirationHours : sans réglage, la réponse ne pourra être ouverte qu'une fois et l'enveloppe reste valide 24 heures. Fixez-les pour retrouver le comportement de Python et de PHP.

En PHP, replyOptions attend un tableau : passez $options->toArray() si vous utilisez la classe SeReplyOptions.

Attention

Types de fichiers. Les extensions invalides sont retirées de la liste, et une liste vide revient à tout accepter. Une faute de frappe dans chaque extension lève donc la restriction sans erreur. Écrivez les extensions en minuscules, avec le point (.pdf), surtout en .NET, qui ne l'ajoute pas, et vérifiez votre liste par un test.

À savoir

  • Le lien est personnel. Il donne accès au formulaire : transmettez-le à la seule personne concernée et ne le journalisez pas. Ajoutez un téléphone pour exiger en plus un code SMS.
  • Téléphone. Aucun SDK ne valide le numéro des enveloppes : validez-le vous-même avec IsValidPhoneNumberAndCanReceiveSMS, au format international.
  • Sujet et destination. Le sujet figure en clair dans le lien de l'enveloppe. La destination devient l'expéditeur de la réponse : chaque adresse doit être valide, séparée des autres par ;. N'y mettez pas plus de renseignements personnels que nécessaire.
  • La réponse vous parvient comme un message Secure Exchanges, à l'adresse du titulaire de la licence qui a créé l'enveloppe. Si votre organisation utilise SESAR, il en reçoit aussi une copie.
  • CallBackParameters. N'y mettez que des identifiants internes, jamais de renseignements personnels en clair.
  • Statut. Vérifiez StatusCode pour chaque enveloppe. Le champ de message d'erreur n'est jamais rempli pour les enveloppes.

Erreurs fréquentes

Symptôme Cause probable Solution
.NET : NullReferenceException après MessageHelper.GetEnveloppe La méthode a retourné null : identifiants refusés ou environnement erroné Testez null, comme dans l'exemple, puis vérifiez vos identifiants.
Statut 500 à la création de l'enveloppe Adresse de destination invalide Vérifiez chaque adresse ; séparez-les par ;.
La restriction de types n'a aucun effet Extensions invalides ou sans le point Écrivez .pdf, pas pdf ni *.pdf.
Python : une personne manque dans la réponse Personne passée sous forme d'objet Passez un dictionnaire {"Email": ...}.
PHP : erreur fatale dans getEnvelopes Personne passée sous forme d'objet Passez un tableau ['Email' => ...].
PHP : TypeError sur replyOptions Objet SeReplyOptions passé tel quel Passez ->toArray().

Et ensuite