Reporting
Reporting
Reporting vous permet de télécharger les rapports sur les transactions via l'API Reporting.
- Les rapports affichent les détails des transactions créées ou mises à jour pendant une période donnée. Vous pouvez préciser les champs devant renseigner le rapport et les en-têtes de colonne dans la sortie.
- Vous pouvez télécharger et stocker vos données de transaction au format CSV pour analyse. Par exemple, vous pouvez analyser les données à l'aide d'une application de veille économique ou d'un tableur.
Vous pouvez obtenir des rapports de commandes et de transactions de trois manières :
- En utilisant une intégration de l'API Reporting pour télécharger des rapports
- En utilisant un navigateur Web pour télécharger des rapports
- En utilisant les portails pour télécharger des rapports
Vous pouvez télécharger les transactions figurant dans la liste des résultats de la recherche sur le portail Administration du commerçant dans un format CSV (valeurs séparées par des virgules).
Conditions préalables
- Votre profil de commerçant sur Mastercard Gateway doit être activé pour le service Reporting.
- Vous devez générer un mot de passe pour accéder à l'API Reporting. Voir Génération d'un mot de passe pour Reporting.
Données de transaction dans un rapport
Reporting enregistre tous les événements associés à une transaction. Lorsque vous demandez un rapport de transaction, tous les événements associés à une transaction donnée pour la période que vous avez indiquée sont inclus dans le rapport. Cela comprend tous les événements de mise à jour associés à la transaction. Vous pouvez également filtrer les données selon les besoins de votre entreprise.
- Payer Authentication (Authentification du payeur)
- Authorization/Pay (Autorisation/Payer)
Le mécanisme des rapports est illustré ci-dessous. Une demande de rapport de transaction pour la période du 1er février 2012 au 29 février 2012 retourne Événement 1 et Événement 2. Ceux-ci sont associés à la même transaction. L’Événement 3, même s’il est associé à la transaction, s’est produit après la fin de la période donnée ; il ne sera donc pas inclus dans le rapport.
Téléchargement de rapports en utilisant une intégration de l'API Reporting
Reporting exige une demande http GET, comme celle indiquée ci-dessous.
GET /history/version/1/merchant/<merchant>/transaction?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>&columns=<columns>&columnHeaders=<columnheaders>
Où :
<merchant>
est votre ID de commerçant.<starttime>
et <endtime> indiquent la période à couvrir.<columns>
sont les champs à inclure dans le rapport, séparés par des virgules. Les noms respectent la casse.<columnheaders>
est la liste des en-têtes à inclure dans le rapport, séparés par des virgules.
L'heure de début est incluse (heure de la transaction >= heure de début) et l'heure de fin est exclue (heure de la transaction < heure de fin).
Les heures de début et de fin sont transmises comme paramètres au format ISO 8601 : yyyy-mm-ddThh:mm:ssZ
, où Z
indique que les heures sont UTC. Si l’heure n’est pas en UTC, un décalage de fuseau horaire doit être spécifié sous la forme +/-hh[:mm], par exemple, 12:31+10
(UTC + 10 heures), ou 12:31:30-06:30
(UTC moins 6 heures 30 minutes). Les valeurs d'heures qui apparaissent dans le rapport (s'il y a lieu) sont en UTC.
Une journée commence à l'heure 00:00. L'heure de fin du rapport (timeOfRecord.end) est exclue ; par conséquent, pour établir un rapport jusqu'à la fin d'une journée, utilisez le début de la journée suivante (00:00) comme heure de fin. De même, si vous souhaitez obtenir des données horaires, spécifiez une fenêtre entre le début d'une heure et le début de la suivante.
Fuseau horaire et format d’heure
Vous pouvez spécifier deux paramètres facultatifs dans la demande :
csv.timeZone=<+ or ->HH:MM
Si ce paramètre est spécifié, l’heure des enregistrements est émise dans le fuseau horaire indiqué, et sans indicateur de fuseau horaire. Notez que les signes + et - doivent être codés UTF-8. Par exemple, si vous définissez
csv.timeZone=%2B10:00
(c.-à-d.,+10.00
), les heures des événements apparaîtront dans le rapport sous la forme UTC+10 heures.Si ce paramètre est omis, la sortie est en UTC avec un « Z » ajouté pour indiquer le fuseau horaire UTC.
csv.timeFormat=<iso8601 or iso8601-T>
Si le paramètre est défini sous la forme
iso8601-T
, il utilise une espace au lieu d’un T comme séparateur date-heure.S’il est omis ou défini sous la forme
iso8601
, le séparateur date-heure est « T ».
Heure d’été
Nous vous recommandons d’ignorer l’heure d’été pour les téléchargements de rapports. Toutefois, si vous souhaitez que les téléchargements de rapports soient configurés en fonction de l'heure d'été, vous devez gérer cela en :
- modifiant le fuseau horaire que vous spécifiez ;
- tenant compte du fait que vous perdrez une heure d'enregistrements au début de l'heure d'été, et obtiendrez une heure d'enregistrements dupliqués à la fin de l'heure d'été.
Pour éviter les complications liées à l'heure d'été, utilisez les fuseaux horaires UTC pour spécifier votre fenêtre de temps.
Le paramètre columns (colonnes) spécifie les champs qui apparaissent dans le rapport. Les champs qu'il est possible de spécifier sont décrits dans l'opération Retrieve Transaction (Extraire la transaction) correspondant à la version de DirectAPI que vous prenez en charge. Notez que la version de l'API de rapports est différente de la version de DirectAPI. Vous trouverez les champs disponibles pour sélection à l'aide de la dernière version de DirectAPI ici.
order.item[n].detail
.Si vous traitez des transactions en utilisant plusieurs versions de l'API, vous pouvez spécifier des champs communs aux différentes versions ou appartenant exclusivement à une version particulière. Les données qui n’existent pas pour un enregistrement particulier apparaissent comme une valeur vide dans le fichier CSV. Toutefois, tout nom de champ doit être valide pour au moins une version de l’API.
Si vous indiquez vos propres en-têtes de colonne dans le paramètre columnHeaders, la liste des noms correspond à la liste des champs dans « columns ». Les paramètres &columnHeaders et &columns doivent avoir le même nombre de membres.
Si la demande ne comprend pas d'en-têtes (&columnHeaders est omis), les en-têtes de colonne sont les noms des champs. Si vous transmettez un paramètre header vide (&columnHeaders=), le fichier de sortie ne contiendra pas de ligne d'en-tête.
Lorsque vous avez déterminé les champs que vous voulez inclure dans votre demande, vous pouvez les envoyer à Mastercard Gateway. La demande est envoyée à la passerelle de paiement par la demande HTTPS GET. Mastercard Gateway attribue le codage UTF-8 pour la demande URL et prend en charge tous les caractères Unicode utiles. Vous devez respecter les règles de codage URL (voir RFC 3986).
Par défaut, le type de contenu du téléchargement est un fichier CSV avec codage ISO8859-1. Vous pouvez spécifier l'un des codages suivants en utilisant le type MIME approprié dans l'en-tête Content-Type :
- ASCII
- UTF-8
- Big5
- GB18030
- Shift-JIS
- KOI8-R
- EUC-JP
- EUC-KR
- ISO8859-1
Par exemple, pour télécharger en UTF-8, spécifiez "Accept-Charset : UTF-8".
L’ID de commerçant figure dans l’URL. L’authentification par mot de passe s’effectue via une authentification HTTP de base. Le mot de passe est le mot de passe Reporting du profil du commerçant configuré dans Administration du commerçant (remarque : il est différent du mot de passe DirectAPI). Voir Génération d'un mot de passe pour Reporting.
Le nom d'utilisateur d'authentification de base est « merchant.default ».
Exemple de script Bash
Les exemples de scripts Bash utilisent curl pour télécharger des rapports (voir http://curl.haxx.se/). Curl s'attend à ce que le mot de passe soit défini dans le fichier .netrc. Celui-ci doit être créé dans le répertoire de base de l'utilisateur. Vous devez ajouter la ligne suivante au fichier .netrc (en remplaçant <password> par votre mot de passe) :
machine ap-gateway.mastercard.com login merchant.default password <password>
Exemple Windows PowerShell
Le mot de passe api est stocké sous forme cryptée dans le fichier reportingPassword de votre dossier de base ($HOME). Pour générer le fichier reportingPassword, exécutez le script setpassword.ps1 inclus dans le pack de téléchargement.
Pour plus d'informations sur la manière de définir des informations d'identification, voir ici.
Si vous ne soumettez pas un mot de passe avec votre demande ou votre script de téléchargement, vous serez invité (si votre client/navigateur https le prend en charge) à en indiquer un lors de l'exécution de l'appel.
Pour automatiser les téléchargements, votre système peut envoyer une série d’appels de téléchargement en utilisant un langage de script déclenché par un processus d’horloge (par exemple cron sous Linux ou Tâches planifiées sous Windows). Les produits de transfert de fichiers gérés permettent également cela.
Vous pouvez choisir la fréquence à laquelle vous téléchargez. Avec un intervalle de 10 minutes, vous disposerez de données en quasi-temps réel, mais un intervalle quotidien peut s'avérer plus efficace. Les téléchargements doivent être suffisamment fréquents pour éviter que les fichiers ne deviennent trop volumineux ou trop décalés – les deux problèmes prennent toute leur importance en cas d'échec d'un téléchargement et de nécessité de le corriger rapidement.
Idéalement, vous devez configurer l'heure de début (timeOfRecord.start) de chaque appel pour qu'elle corresponde à l'heure de fin (timeOfRecord.end) de l'appel précédent réussi. De la sorte, vous obtiendrez tous les enregistrements exactement une seule fois. Utilisez le code de statut HTTP pour vérifier si le dernier appel a échoué. En cas d’échec, le script devrait attendre quelques minutes et réessayer. Un délai de quelques minutes s’applique pour Mastercard Gateway entre le traitement et le téléchargement d'une transaction. Si vous essayez de télécharger des enregistrements de cette période, Mastercard Gateway rejette la demande à l’aide d’une réponse DATA_AVAILABLE_AFTER et la dernière heure de fin permise.
Les exemples de scripts suivants sont inclus dans l’ensemble :
- basicreportexample.sh / basicreportexample.ps1 - Script simple configuré via des paramètres de ligne de commande qui télécharge un rapport compris dans une période spécifiée.
- downloadreport.sh / downloadreport.ps1 - Script conçu pour s'exécuter automatiquement à partir d'un ordonnanceur et qui télécharge les nouveaux événements de transaction survenus depuis sa dernière exécution.
- setpassword.ps1 - Script Windows PowerShell qui demande un mot de passe et le crypte dans le fichier reportingPassword. Il utilise une fonctionnalité de cryptage uniquement disponible dans Windows.
Avec l'exemple de script Bash, le script suppose que vous avez configuré votre mot de passe Reporting dans le fichier .netrc.
En réponse à une demande GET valide et authentifiée, Reporting fournit un fichier CSV contenant tous les enregistrements de transaction DirectAPI, filtrés selon tous les champs que vous avez spécifiés dans la demande et qui ont été créés ou mis à jour pendant la période définie par les dates de début et de fin. Les enregistrements sont triés dans l'ordre croissant, de la transaction la plus ancienne à la plus récente.
Les numéros de carte sont masqués dans le rapport.
Exemple de rapport de transactions :
time,order id,transaction id,card number,card expiry month,card expiry year,amount,currency,type,acquirer,acquirerCode 2012-05-14T06:23:10.859Z,11336976611,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T01:25:19.694Z,11337131511,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T06:33:31.709Z,11337150032,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T22:15:53.276Z,11337206569,1,345678xxxxx4564,5,13,75.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T00:22:14.516Z,11337214154,1,345678xxxxx4564,5,13,72.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T01:41:17.447Z,11337218888,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T01:41:43.533Z,11337218921,1,345678xxxxx4564,5,13,78.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-21T11:15:00.093Z,11337598863,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-21T12:29:52.954Z,11337603409,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-22T01:51:09.996Z,11337651486,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000
Si la demande n'est pas valide, ou si l'ID de commerçant et le mot de passe que vous avez soumis ne sont pas valides ou ne sont pas autorisés à accéder à l'API de rapports, vous obtenez un message d'erreur détaillé.
Si vous avez soumis deux demandes et que la date/heure de début de la première demande est la date/heure de fin de la deuxième demande, aucun enregistrement de transaction ne manquera ou ne sera dupliqué. S'il n'y a aucun enregistrement jusqu'à la date/heure de fin, un message d'erreur est retourné, indiquant la dernière date/heure de fin possible.
S'il n'existe aucun enregistrement pour la période de rapport que vous avez spécifiée, un fichier CSV contenant les en-têtes et aucune ligne d'entrée vous sera retourné.
Téléchargement de rapports en utilisant un navigateur Web
Vous pouvez demander des rapports directement à l’aide d’un navigateur Web. Les rapports peuvent être configurés dans l'URL fournie dans la demande.
Créez une URL à partir du modèle ci-dessous :
https://YOUR_GATEWAY_SERVER/history/version/1/merchant/
YOUR_MERCHANT_ID/transaction?REPORT_CONTENTS_AND_FORMAT
REPORT_CONTENTS_AND_FORMAT
example:columns=merchant,order.id,transaction.id, transaction.amount,transaction.amount& columnHeaders=Merchant,OrderID,TransactionID,Currency,Amount
&timeOfRecord.end=2015-01-24T18:43:54
&timeOfRecord.start=2015-01-12T18:38:40
Ceci extrait un rapport contenant un commerçant, un ID de commande, un ID de transaction, la devise de transaction et le montant de la transaction pour des transactions comprises entre le 15 janvier 2015 à 18:43:54h et le 24 janvier 2015 à 18:38:40h. Les en-têtes de colonne affichent « Commerçant », « ID de commande », « ID de transaction », « Devise » et « Montant ».
Collez l'URL dans votre navigateur. Vous serez invité à saisir le mot de passe. Le mot de passe est le mot de passe Reporting du profil du commerçant configuré dans Administration du commerçant (remarque : il est différent du mot de passe DirectAPI). Voir Génération d'un mot de passe pour Reporting. Comme nom d'utilisateur, entrez merchant.default.
Génération d'un mot de passe pour Reporting
Reporting requiert une demande d'authentification par mot de passe adressée à Mastercard Gateway. Vous pouvez générer le mot de passe dans Administration du commerçant.
- Accédez à Admin > Reporting Paramètres d'intégration de l'API > Modifier.
- Cliquez sur Générer nouveau.
- Cochez la case Activer l'accès à l'intégration de l'API Reporting par mot de passe.
- Copiez le mot de passe dans le presse-papier et/ou dans un fichier texte. Vous en aurez besoin ultérieurement.
- Cliquez sur Soumettre.
Le mot de passe généré par le système est une valeur de 16 octets générée de manière aléatoire et codée sous forme de chaîne hexadécimale. Bien que sa longueur et sa qualité soient suffisantes pour résister à la détection par force brute, il doit être sécurisé de la même manière que les mots de passe utilisateur et les autres données sensibles.
Vous devez toujours avoir au moins un mot de passe généré et activé, mais vous pouvez en avoir jusqu'à deux configurés. Par mesure de sécurité, vous devez modifier le mot de passe périodiquement. Pour ce faire, générez un nouveau mot de passe et mettez à jour le script de téléchargement du rapport. Les deux mots de passe fonctionneront pendant ce changement.