Lire un message

Ouvrir avec le SDK un message Secure Exchanges reçu, à partir de son lien : sujet, corps et fichiers joints.

Prérequis

Vos identifiants : voir Identifiants et environnements.
Le lien complet du message, avec tous ses paramètres.

Attention

Le lien est un secret. Il donne accès au message. Ne le journalisez pas, ne le placez pas dans une URL de votre application et ne le conservez pas plus longtemps que nécessaire.

Étapes

Analysez le lien avec GetSecureExchangesMessageFromLink.
Si le message est protégé, demandez le mot de passe ou le code d'ouverture à l'utilisateur. Le lien indique ce qu'il faut demander.
Appelez GetMessage, puis vérifiez le statut.
Pour les fichiers joints, voir Télécharger les fichiers reçus.

Exemple

SecureExchangesMessage msg = MessageHelper.GetSecureExchangesMessageFromLink(lien);

// Demandés à l'utilisateur, jamais écrits dans le code.
string motDePasse = msg.Password ? DemanderMotDePasse() : null;
string code = msg.Digit ? DemanderCodeOuverture() : null;

var args = new GetMessageArgs(endpoint, serial, apiUser, apiPassword, msg, password: motDePasse, digit: code);
GetMessageResponse response = MessageHelper.GetMessage(args);

if (response.Status == 200)
{
    // response.Subject, response.Message (HTML) et response.FilesMetaData
    Traiter(response);
}
else
{
    journal.LogWarning("Lecture refusée, statut {Status}", response.Status);
}

try:
    msg_params = MessageHelper.get_secure_exchanges_message_from_link(lien)
except ValueError:
    msg_params = None
if msg_params is None:
    raise LienInvalide()

# Demandés à l'utilisateur, jamais écrits dans le code.
mot_de_passe = demander_mot_de_passe() if msg_params.get("password") else None
code = demander_code_ouverture() if msg_params.get("digit") else None

response = MessageHelper.get_message(
    api_client=client, sems_client=sems_client,
    serial=serial, api_user=api_user, api_password=api_password,
    msg_params=msg_params, password=mot_de_passe, digit_code=code,
)

if response.status == 200 and response.message is not None:
    # response.subject, response.message (HTML) et response.secure_files
    traiter(response)
else:
    journal.warning("Lecture refusée, statut %s", response.status)

$msgParams = MessageHelper::getSecureExchangesMessageFromLink($lien);
if ($msgParams === null) {
    throw new LienInvalideException();
}

// Demandés à l'utilisateur, jamais écrits dans le code.
$motDePasse = ($msgParams['password'] ?? false) ? demanderMotDePasse() : null;
$code = ($msgParams['digit'] ?? false) ? demanderCodeOuverture() : null;

$response = MessageHelper::getMessage(
    apiClient: $client, semsClient: $sems,
    serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
    msgParams: $msgParams, password: $motDePasse, digitCode: $code,
);

if ($response->status === 200) {
    // $response->subject, $response->message (HTML) et $response->secureFiles
    traiter($response);
} else {
    $journal->warning('Lecture refusée, statut ' . $response->status);
}

La réponse

Contenu	Où le trouver
Sujet et corps (HTML)	Voir les commentaires de l'exemple.
Fichiers joints	`FilesMetaData` : à passer au téléchargement.
Ouvertures restantes	`RemainingOpenTime`
Expiration	`ExpireOn`

Les dates (ExpireOn) peuvent arriver sous forme de chaîne plutôt que de date : convertissez-les avant de les comparer.

Ouvertures et mot de passe

Situation	Effet
Chaque appel à `GetMessage`	Compte comme une ouverture, qu'il réussisse ou non.
Dernière ouverture permise	Le message est retourné, puis détruit. L'appel suivant reçoit le statut 404.
Mot de passe ou code d'ouverture erroné	Le serveur refuse la lecture avec le statut 404, le même que pour un message expiré ou supprimé : la réponse ne dit pas lequel des deux. La tentative compte comme une ouverture.

Ne relancez donc jamais une lecture automatiquement : redemandez le mot de passe ou le code à l'utilisateur, et limitez le nombre d'essais de votre côté. Dans les journaux, une lecture réussie apparaît comme récupérée (Retreive), et un message détruit comme Destroy.

Traiter le contenu déchiffré

Le sujet, le corps et les fichiers sont en clair dans votre application.

Journaux et console : n'y écrivez jamais le sujet, le corps ni le nom des fichiers.
Stockage : conservez-les chiffrés, limitez qui peut y accéder et supprimez-les dès qu'ils ne servent plus. Voir Chiffrement.
Affichage web : le corps est du HTML rédigé par l'expéditeur. Ne l'insérez jamais tel quel dans une page (innerHTML, @Html.Raw, echo) : nettoyez-le avec une liste blanche de balises, ou affichez-le dans une iframe isolée (sandbox, sans scripts).
Erreurs : le texte d'erreur retourné par le SDK peut contenir des détails techniques. Affichez un message générique et gardez le statut dans vos journaux.

Erreurs fréquentes

Symptôme	Cause probable	Solution
.NET : `FormatException` à l'analyse du lien	Lien tronqué ou modifié	Utilisez le lien complet, sans le retoucher.
Python : `ValueError` à l'analyse du lien	Même cause	Même solution ; interceptez l'exception, comme dans l'exemple.
PHP : `TypeError` dans `getMessage`	Le lien n'a pas pu être analysé (`null`)	Vérifiez le résultat avant l'appel, comme dans l'exemple.
Statut 404	Mot de passe ou code d'ouverture erroné, ou message expiré, supprimé ou dont les ouvertures sont épuisées	Vérifiez ce que le lien demande, puis redemandez la saisie à l'utilisateur, sans relancer automatiquement.
Python : statut 200 mais corps vide (`None`)	Le corps n'a pas pu être déchiffré	Traitez ce cas comme un échec, comme dans l'exemple.
.NET : `response.Body`, `file.FileName` ou `file.MimeType` introuvable	Noms des anciens guides	Utilisez `response.Message`, `file.RealFileName` et `file.FileType`.

Table of Contents