Table of Contents

Journaux

Suivre un message envoyé : ouvertures, téléchargements, signatures. Vous pouvez consulter le journal d'un message précis, ou ceux de tous les messages d'une période.

Prérequis

Le journal d'un message

GetLog attend un seul identifiant : le numéro de suivi (TrackingID) ou l'identifiant du message (MessageID). Avec les deux, ou aucun, il retourne le statut 400.

var args = new GetLogArgs(endpoint, serial, apiUser, apiPassword)
{
    TrackingID = trackingId   // response.RecipientsAnswer[i].Answer.TrackingID
};

GetLogResponse response = LogsHelper.GetLog(args);

if (response != null && response.Status == 200 && response.Log != null)
{
    MessageLog log = response.Log;
    // log.OpenStatus, log.OpenTime, log.IsSignProcessCompleted...
}

Les journaux d'une période

GetLogs retourne les journaux de tous les messages envoyés entre deux dates (From, To).

DateTime fin = DateTime.UtcNow;   // en UTC : voir Fuseau horaire
var args = new GetLogsArgs(endpoint, serial, apiUser, apiPassword, fin.AddDays(-7), fin);

GetLogsResponse response = LogsHelper.GetLogs(args);

if (response.Status == 200)
{
    foreach (MessageLog log in response.Logs)
        Traiter(log);
}

La période ne peut pas dépasser 6 mois par appel : au-delà, le serveur retourne le statut 400. Gardez-la courte de toute façon : la réponse n'est pas paginée et peut devenir très volumineuse.

Fuseau horaire

Votre compte a un fuseau horaire : l'heure de l'Est, sauf si vous l'avez changé. Le serveur lit les dates de la période dans ce fuseau et y exprime les dates des journaux. Une exception : si la date de début arrive en UTC, la période est lue en UTC et les dates des journaux sont en UTC.

SDK Dates à passer Dates des journaux
.NET En UTC (DateTime.UtcNow) UTC
Python Avec ou sans fuseau : le SDK les envoie en UTC. Sans fuseau, une date est l'heure locale de la machine UTC
PHP Tout DateTime : le SDK l'envoie en UTC UTC
Attention

En .NET, une date DateTime.Now part avec son décalage horaire : le serveur la ramène d'abord à sa propre heure, puis la lit dans le fuseau de votre compte, et la période peut être décalée de l'écart entre les deux. Passez des dates UTC.

Contenu d'un journal

En Python et en PHP, chaque journal est un dictionnaire (tableau associatif) dont les clés sont les noms ci-dessous, tels quels. Les dates sont des chaînes au format ISO 8601, et les statuts des nombres.

Champ Contenu
OpenStatus Statut du message : voir le tableau suivant.
OpenTime Nombre d'ouvertures.
CreatedDate, LastUpdate Date d'envoi, date de la dernière activité.
Recipient Destinataires, séparés par des virgules.
FromEmailAddress Adresse de l'expéditeur.
Subject Sujet du message.
MsgType 1 : message ; 2 : réponse.
TrackingId Numéro de suivi.
LogFiles Fichiers joints : FileName, OpenStatus, OpenTime (nombre de téléchargements), FileSize, IsFileToSign.
Activities Historique : Date, Status, RemoteIP (adresse IP à l'origine de l'activité), Reference.
IsContainsSignsFiles Le message contient des fichiers à signer.
IsSignProcessCompleted La signature est terminée.
Valeur Statut Sens
0 NotRead Pas encore lu.
1 Read Lu.
2 Retreive Récupéré.
3 Destroy Détruit par mesure de sécurité.
4 Try Tentative d'ouverture.
5 ShowInMailbox Courriel affiché dans une boîte de réception.
6 Error Erreur sur le message.
7 InitiateTheAction Action de l'expéditeur (envoi, dépôt d'un fichier).
8 Processing En cours d'envoi ou de traitement.
9 Failed Envoi en échec.
10 Cancelled Destinataire annulé : il n'a plus à ouvrir ni à signer.

À savoir

  • Autre utilisateur. UserLogSerial donne les journaux d'un autre utilisateur de votre organisation ; laissez-le vide pour les vôtres. Vos propres journaux ne demandent aucune permission ; ceux d'un autre utilisateur exigent la permission ViewLogs ou ViewAdminLogs, sinon le statut 403.
  • Renseignements personnels. Un journal contient des adresses courriel, le sujet et des adresses IP. Ne le recopiez pas dans vos journaux techniques, limitez qui peut le consulter et prévoyez sa durée de conservation.
  • Erreurs. En .NET, le texte d'erreur de LogsHelper.GetLogs peut contenir une trace technique complète : ne l'affichez jamais à un utilisateur.

GetLog peut retourner null quand l'échange de clés échoue : testez-le avant de lire le statut, comme dans l'exemple.

Passez les identifiants sous forme de uuid.UUID : une chaîne fait échouer l'appel sans lever d'exception.

Erreurs fréquentes

Symptôme Cause probable Solution
Statut 400 (GetLog) Les deux identifiants fournis, ou aucun Passez le numéro de suivi ou l'identifiant du message.
Statut 0 (GetLog) ou 500 (GetLogs) Erreur interceptée par le SDK : identifiant mal formé, réseau Vérifiez le type des identifiants et la connexion.
Statut 400 (GetLogs) Période de plus de 6 mois Découpez la période.
Statut 403 Journaux d'un autre utilisateur, sans la permission Demandez ViewLogs ou ViewAdminLogs à un administrateur de votre organisation.
Journaux manquants en début ou en fin de période .NET : dates passées avec DateTime.Now Passez des dates UTC : voir Fuseau horaire.
Réponse très lente ou délai dépassé Période trop longue Découpez la période.
Python : AttributeError sur log.open_status Les journaux sont des dictionnaires Lisez log["OpenStatus"].
Les champs MessageStatus, OpenCount, SentDate sont introuvables Noms d'un ancien guide Utilisez les champs du tableau ci-dessus.

Et ensuite