Reporting

Reporting le permite descargar los reportes de transacción mediante la API de Reporting.

  • Los reportes muestran detalles de las transacciones creadas o actualizadas en un período de tiempo determinado. Puede especificar los campos para completar el reporte, y los encabezados de columna en el resultado.
  • Puede descargar y almacenar sus datos de transacciones en formato CSV para su análisis. Por ejemplo, los datos se pueden analizar mediante una aplicación de inteligencia comercial o aplicación de hoja de cálculo.

Puede obtener reportes de pedidos y transacciones de tres formas distintas:

Prerrequisitos

  • Su perfil del negocio en Mastercard Payment Gateway debe estar habilitado para el servicio de Reporting.
  • Debe generar una contraseña para acceder a la API de Reporting. Consulte Generación de contraseña para Reporting.

Datos de transacciones en un reporte

Reporting registra todos los eventos asociados con una transacción. Cuando solicita un reporte de transacción, todos los eventos asociados con una transacción determinada dentro del período especificado se insertan en el reporte. Esto incluye todos los eventos actualizados asociados con la transacción. También tiene la flexibilidad para filtrar datos según los requisitos de su negocio.

La siguiente imagen muestra el mecanismo de reportería. Un reporte de transacción solicitado para el período entre el 1-feb-2012 y el 29-feb-2012 devuelve el Evento 1 y el Evento 2; ambos están asociados con la misma transacción. El Evento 3, aunque está asociado con la transacción, se llevó a cabo después del término del período especificado, así que no se incluirá en el reporte.

Reportería de datos de transacción

Descargar reportes mediante una integración de la API de Reporting.

Cree la solicitud de Reporting

Reporting requiere una solicitud http GET, como la que se muestra a continuación.

GET /history/version/1/merchant/<merchant>/transaction?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>&columns=<columns>&columnHeaders=<columnheaders>

Donde:

  • <merchant> es su ID de negocio.
  • <starttime> y <endtime> indican el período que debe abarcar.
  • <columns> son los campos que se deben incluir en el reporte, separados por comas. Los nombres distinguen entre mayúsculas y minúsculas.
  • <columnheaders> es la lista de encabezados de columnas que se deben incluir en el reporte, separados por comas.
Horas

La hora de inicio es inclusiva (hora de transacción >= hora de inicio) y la hora de término es exclusiva (hora de transacción < hora de término).

Las horas de inicio y término se proporcionan como parámetros en formato ISO 8601: yyyy-mm-ddThh:mm:ssZ, donde Z indica que la hora es UTC. Si la hora no es UTC, se debe especificar una compensación de hora como +/-hh[:mm], por ejemplo, 12:31+10 (UTC + 10 horas), o 12:31:30-06:30 (UTC menos 6 horas 30 minutos). Los valores de tiempo que aparecen en el reporte (si corresponde) están en UTC.

El primer instante del día ocurre a las 00:00. La hora de término del reporte (timeOfRecord.end) es exclusiva, de forma que para generar reportes al final de un día, use el primer instante del siguiente día (00:00) como la hora de término. De igual forma, si desea datos por hora, especifique una ventana como el inicio de una hora y el inicio de la siguiente.

Zona horaria y formato de hora

Puede especificar dos parámetros opcionales en la solicitud:

  • csv.timeZone=<+ or ->HH:MM

    Si se especifica, el tiempo de los registros se genera en la zona horaria indicada y sin un indicador de zona horaria. Tenga en cuenta que los signos + y - deben estar codificados con UTF-8. Por ejemplo, si establece csv.timeZone=%2B10:00 (o sea, +10.00), las horas de los eventos aparecerán en el reporte como UTC+10 horas.

    Si se omite, el resultado es UTC con una "Z" anexada para indicar la zona horaria UTC.

  • csv.timeFormat=<iso8601 or iso8601-T>

    Si se especifica iso8601-T, el resultado usa un espacio en lugar de T como el separador de fecha-hora.

    Si se omite, o se especifica como iso8601, el separador de fecha-hora es "T".

Horario de verano

Recomendamos que ignore el horario de verano para descargas de reportes. Sin embargo, si desea visualizar las descargas de reportes con horario de verano, debe hacerlo de la siguiente forma:

  • modificando la zona horaria que especifica
  • registrando el hecho que perderá una hora de registros al inicio del horario de verano, y obtendrá una hora de registros duplicados al final del horario de verano.

Para evitar complicaciones debido al horario de verano, use la zona horaria UTC para especificar la visualización de hora.

Columnas

El parámetro de columnas especifica los campos que aparecen en el reporte. Los campos que se pueden especificar se describen en la operación Retrieve Transaction para la versión de API que admite. Tenga en cuenta que la versión de la API de reportes es distinta de la versión de API. Los campos disponibles para la selección mediante la última versión de API se pueden encontrar aquí.

La API de reportes solo es compatible con los campos disponibles en API versión 14 y posteriores. No se pueden recuperar, descargar ni almacenar datos de campos de matriz; por ejemplo, order.item[n].detail.

Si procesa transacciones mediante múltiples versiones de API, puede especificar campos comunes entre distintas versiones o únicos para una versión en particular. Los datos que no existen para un registro en particular se mostrarán como un valor vacío en el CSV. Sin embargo, cualquier nombre de campo puede ser válido para al menos una versión de API.

Encabezados de columnas

Si proporciona sus propios encabezados de columnas en el parámetro de encabezado de columna, la lista de nombres corresponde a la lista de campos en la lista "columnas". "Encabezados de columnas" y "columnas" deben tener el mismo número de miembros.

Si no se incluyen encabezados en la solicitud (&se omite encabezados de columnas), los encabezados de columnas serán los nombres de campo. Si se aprueba el parámetro de encabezado vacío (&encabezados de columnas=), el archivo de salida no contendrá filas de encabezado.

Envíe la solicitud de Reporting

Luego de determinar los campos que desea incluir en la solicitud, puede enviarlos a Mastercard Payment Gateway. La solicitud se envía al motor de pagos mediante una solicitud HTTPS GET. Mastercard Payment Gateway supone una codificación UTF-8 para la solicitud URL y admite todos los caracteres Unicode útiles. Debe respetar las reglas de codificación de URL (consulte RFC 3986).

Encabezados HTTP

De forma predeterminada, el tipo de contenido de descarga es CSV con codificación ISO8859-1. Puede especificar cualquiera de las siguientes opciones mediante el tipo mime adecuado en el encabezado de tipo de contenido:

  • ASCII
  • UTF-8
  • Big5
  • GB18030
  • Shift-JIS
  • KOI8-R
  • EUC-JP
  • EUC-KR
  • ISO8859-1

Por ejemplo, para descargar en UTF-8, especifique "Accept-Charset : UTF-8".

Autenticación de las solicitudes

El ID de negocio está en la URL. La autenticación con contraseña ocurre mediante autenticación HTTP básica. La contraseña es la contraseña de Reporting del perfil del negocio configurada en Administración de negocios (nota: no es igual que la contraseña de API). Consulte Generación de contraseña para Reporting.

El nombre de usuario de autenticación básico es 'merchant.default'.

Ejemplo de script de Bash

Los ejemplos de script de Bash utilizan curl para descargar reportes (consulte http://curl.haxx.se/). Curl espera que la contraseña se configure en el archivo .netrc. Esto se crea en el directorio principal del usuario. Debe agregar la siguiente línea al archive .netrc; <contraseña> se reemplaza con su contraseña:

machine evopaymentsmexico.gateway.mastercard.com login merchant.default password <password>		
	  

Ejemplo de Windows PowerShell

La contraseña de API se almacena cifrada en el archivo reportingPassword de la carpeta de inicio ($HOME). Para generar el archivo reportingPassword, ejecute el script setpassword.ps1 incluido en el paquete de descarga.

Para obtener más información sobre cómo configurar credenciales, mire aquí.

Si no envía una contraseña con su solicitud o script de descarga, se le solicitará (si su cliente/explorador http lo admite) que proporcione una contraseña cuando se realice la llamada.

Descargar scripts de muestra

Sincronización de solicitudes

Para automatizar las descargas, el sistema puede emitir una serie de llamadas de descarga mediante un lenguaje de script desencadenado por un temporizador (por ejemplo, cron en Linux o Tareas programadas en Windows). Los productos Transferencia de archivos administrados también pueden realizar esto. 

Usted puede elegir la frecuencia con que descarga. Intervalos de diez minutos mantendrán sus datos cerca de tiempo real, pero es posible que intervalos diarios sean más eficientes. Las descargas deben tener la frecuencia suficiente para evitar que los archivos sean demasiado grandes o que queden obsoletos; ambos problemas aumentan la importancia de una descarga fallida y la urgencia de su solución.

Idealmente, usted establece la hora de inicio (timeOfRecord.start) de cada llamada para que sea la hora de término (timeOfRecord.end) de la llamada exitosa anterior. Esto garantiza que obtenga todos los registros exactamente una vez. Use el código de estado HTTP para verificar si la última llamada falló. En error, el script debe esperar unos pocos minutos y volver a intentar. Mastercard Payment Gateway tiene unos cuantos minutos de retraso desde el momento que procesa una transacción hasta el momento en que está disponible para descarga. Si intenta descargar registros desde dicho período, Mastercard Payment Gateway rechaza la solicitud con una respuesta DATA_AVAILABLE_AFTER y la hora de término más tardía permitida.

Scripts de muestra

El paquete con scripts de muestra incluye los siguientes scripts:

  • basicreportexample.sh / basicreportexample.ps1: script de muestra configurado por los parámetros de la línea de comandos; descarga un reporte entre un rango de tiempo especificado.
  • downloadreport.sh / downloadreport.ps1: script configurado para ejecutarse sin supervisión desde un programador; descarga los nuevos eventos de transacción desde la última vez de su ejecución.
  • setpassword.ps1: script de Windows PowerShell que solicita una contraseña y la cifra en el archivo reportingPassword. Utiliza una característica de cifrado disponible solo para Windows.

Con el ejemplo de script de Bash, el script supone que ha configurado la contraseña de Reporting en el archivo .netrc.

Descargar scripts de muestra

Procese la respuesta de Reporting
Éxito

En respuesta a una solicitud GET válida autenticada, Reporting proporciona un archivo CSV que contiene todos los registros de transacciones de API, filtrados por todos los campos que especificó en la solicitud, que se han creado o actualizado dentro del plazo definido por la hora de inicio y hora de término. Los registros se ordenan ascendentemente desde la transacción más antigua a la más reciente.

Los números de tarjeta se enmascaran en el reporte.

Reporting genera un registro de transacción cuando cambia el estado de la transacción. Por ejemplo, si se evalúa el riesgo de una transacción de autorización y luego se liquida, el reporte de transacción mostrará los registros para los tres eventos: autorización, respuesta de riesgos y respuesta de liquidación.

A continuación se muestra un ejemplo de reporte de transacción:

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
Falla

Si la solicitud no es válida, o si el ID de negocio y la contraseña que envió no son válidas o no tienen autorización para acceder a la API de reportería, se genera un mensaje de error con detalles.

Si envía dos solicitudes y la fecha/hora de término de la primera solicitud corresponde a la fecha/hora de inicio de la segunda solicitud, no se omiten ni duplican los registros de transacción. Si hay registros hasta la fecha/hora de término, se genera un mensaje de error que indica la última fecha/hora posible.

Si no existen reportes para el periodo que especificó, se genera un archivo CSV con el encabezado y sin líneas de entrada.

Descargar reportes mediante un explorador web

Puede solicitar reportes directamente mediante un explorador web. Los reportes se pueden configurar en la URL que se proporcionó en la solicitud.

Configuración de la URL para reportería

Cree una URL a partir de la plantilla a continuación:

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

Esto recupera un reporte que contiene el negocio, el ID de pedido, el ID de transacción, la moneda de la transacción y el monto de la transacción para transacciones entre el 15 de enero de 2015 a las 18:43:54h y el 24 de enero de 2015 a las 18:38:40h. Los encabezados de la columna mostrarán "Merchant", "OrderID", "TransactionID", "Currency" y "Amount".

Para obtener más información sobre las opciones de reportería disponibles, consulte Referencia de API de Retrieve Transaction.

Pegue la URL en el explorador. Se le pedirá que ingrese la contraseña. La contraseña es la contraseña de Reporting del perfil del negocio configurada en Administración de negocios (nota: no es igual que la contraseña de API). Consulte Generación de contraseña para Reporting. Para el nombre de usuario, ingrese merchant.default.

Generar una contraseña para Reporting

Para Reporting se requiere una solicitud autenticada con contraseña a Mastercard Payment Gateway. Puede generar la contraseña en Administración de negocios.

El operador debe tener el privilegio "Puede configurar ajustes de integración de la API de reportería" para generar la contraseña.
  1. Navegue a Admin > Ajustes de integración de la API de Reporting > Editar.
  2. Haga clic en Generar nueva.
  3. Seleccione el cuadro Habilitar el acceso a la integración de la API de Reporting a través de una contraseña.
  4. Copie la contraseña en el portapapeles y/o en un archivo de texto. La necesitará más adelante.
  5. Haga clic en Enviar.

La contraseña generada por el sistema es de 16 bytes, valor generado aleatoriamente y codificado como una cadena hexadecimal. Aunque tiene la longitud y la calidad suficientes para resistir una adivinación forzada, debe protegerse de la misma manera que las contraseñas de usuario y otros datos confidenciales.

Siempre debe tener al menos una contraseña generada y habilitada, pero puede tener hasta dos contraseñas configuradas. Por seguridad, debe cambiar la contraseña de manera periódica. Para ello, genere una nueva contraseña y actualice el script de descarga de reportes. Las dos contraseñas funcionarán durante este cambio.

Derechos de autor © 2020 Mastercard