Avis et paramètres de rappel

Savoir quand un message est ouvert, et rattacher un message à vos propres données.

Ce que le SDK propose

Besoin	Moyen
Être averti qu'un message est ouvert	`getNotify` : un courriel avise le titulaire du compte quand le message est ouvert.
Connaître l'état d'un message	Les journaux : ouvertures, téléchargements, signature.
Rattacher un message à vos données	`CallBackParameters` : des données qui accompagnent le message et que vous relisez avec lui.
Recevoir dans votre système les réponses aux enveloppes	SESAR : il reçoit une copie de chaque réponse, avec ses `CallBackParameters`. SESAR Webhook les transmet à vos systèmes : voir Classer les dépôts.

Le SDK ne fournit pas de point de réception pour des avis poussés vers votre service. Pour suivre vos messages automatiquement, interrogez les journaux à intervalle régulier, sur une période courte.

Paramètres de rappel

Joignez à l'envoi un identifiant interne, par exemple un numéro de dossier : vous le retrouvez à la lecture du message, ou avec la réponse à une enveloppe.

var args = new MutliRecipientArgs(
    endPointUri: endpoint, serial: serial, user: apiUser, psw: apiPassword,
    recipients: recipients, message: message, subject: subject,
    password: null, filesList: null,
    sendMode: SendMethodEnum.onlyEmail, getBackHtml: false,
    showSubject: true, getNotify: true, cultureID: "fr-CA",
    maximumOpenTime: 5, minutesExpiration: 10080)
{
    // Liste de paires Key / Value : le format recommandé
    CallBackParameters = JsonConvert.SerializeObject(new List<CallBackParameter>
    {
        new CallBackParameter("NoDossier", numeroDossier),
    }),
};

// À la lecture (voir Lire un message) :
string parametres = response.CallBackParameters;

from secure_exchanges_sdk.helpers.serialization_helper import SerializationHelper

answer = MessageHelper.multi_recipient_message(
    api_client=client, sems_client=sems_client,
    serial=serial, api_user=api_user, api_password=api_password,
    recipients=recipients, message=message, subject=subject,
    get_back_html=False, culture_id="fr-CA",
    # Liste de paires Key / Value : le format recommandé
    callback_parameters=SerializationHelper.serialize_to_json([{"Key": "NoDossier", "Value": numero_dossier}]),
)

# À la lecture (voir Lire un message) :
parametres = response.callback_parameters

$answer = MessageHelper::multiRecipientMessage(
    apiClient: $client, semsClient: $sems,
    serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
    recipients: $recipients, message: $message, subject: $subject,
    getBackHtml: false, cultureId: 'fr-CA',
    // Liste de paires Key / Value : le format recommandé
    callbackParameters: SerializationHelper::serializeToJson([['Key' => 'NoDossier', 'Value' => $numeroDossier]]),
);

// À la lecture (voir Lire un message) :
$parametres = $response->callbackParameters;

Point	Détail
Confidentialité	Ces données ne sont pas confidentielles : Secure Exchanges et quiconque lit le message avec le SDK peuvent les lire. N'y mettez qu'un identifiant interne, jamais de renseignement personnel ni de secret.
Format	Une chaîne libre. Utilisez de préférence une liste de paires `Key` / `Value`, comme dans l'exemple : voir Format des paramètres de rappel.
Lecture	Validez-les comme toute donnée externe : format attendu, dossier existant, et droit de l'utilisateur sur ce dossier.
Enveloppes et signature	Le même champ existe pour les enveloppes et pour un envoi de documents à signer.
.NET Framework	Le SDK embarque Newtonsoft.Json sans l'exposer : ajoutez le paquet NuGet `Newtonsoft.Json` à votre projet pour utiliser `JsonConvert`.
Avec SESAR	Les paramètres reviennent dans le manifeste de chaque dépôt : c'est le moyen le plus sûr de le ranger dans le bon dossier. Voir Classer les dépôts.

Format des paramètres de rappel

Le SDK accepte n'importe quelle chaîne. Utilisez de préférence une liste JSON de paires Key / Value, comme dans l'exemple : [{"Key":"NoDossier","Value":"A-1042"}]. C'est la forme qu'emploient les outils Secure Exchanges ; en .NET, la classe CallBackParameter la produit.

Comme noms (Key), utilisez les clés contextuelles de votre organisation : des noms de champ qu'un administrateur définit dans le portail (Organisation > Clés contextuelles), pour que tous vos envois emploient les mêmes noms. GetSerialInfo les retourne :

SDK	Propriété	Contenu
.NET	`ContextualKeys`	Liste de `ContextualKey` : `Key`, `CreatedDate`.
Python	`contextual_keys`	Liste de dictionnaires : `"Key"`, `"CreatedDate"`.
PHP	`contextualKeys`	Tableau de tableaux associatifs : `'Key'`, `'CreatedDate'`.

La liste est vide si votre organisation n'a défini aucune clé, et nulle si la licence n'appartient à aucune organisation. Une clé contextuelle n'est qu'un nom : ce n'est ni un secret, ni un droit d'accès.

Être avisé d'une ouverture

Avec getNotify à true, le titulaire du compte reçoit un courriel quand le message est ouvert. Pour un traitement automatique, préférez les journaux : le statut de chaque destinataire y est lisible par le SDK.

Pour les enveloppes, NotifyWhenRead avise la personne qui a répondu quand vous ouvrez sa réponse.

Erreurs fréquentes

Symptôme	Cause probable	Solution
.NET : `SerializationHelper.DeserializeFromJson` ou `CryptoHelper.DecryptStringFromB64` introuvable	Méthodes d'un ancien guide, qui n'existent pas	Utilisez `JsonConvert` pour le JSON, et `GetMessage` pour lire le message.
Aucun courriel d'avis	`getNotify` à false, ou message pas encore ouvert	Vérifiez l'option à l'envoi, puis l'état dans les journaux.

Et ensuite

Journaux
Cycle de vie d'un message
Classer les dépôts : ranger dans vos systèmes ce que reçoit SESAR