Generación de reporte sucursal

Introducción

La API de Reportes de Sucursales permite a los socios comerciales de Haulmer generar reportes detallados de transacciones presenciales procesadas a través de terminales de pago en sucursales específicas. Esta API proporciona datos de transacciones con filtros avanzados como localización, pos, tipo de transacción, entre otros, además de paginación para facilitar el análisis de ventas y operaciones.

El endpoint aborda…

  • Centralización de datos: Acceso unificado a información de transacciones de todos los POS por “zona” registrada.
  • Análisis temporal: Generación de reportes por rangos de fechas específicas.
  • Filtrado avanzado: Búsqueda por ubicación, número de serie, tipo de transacción, marca de tarjeta, etc.
  • Optimización de rendimiento: Sistema de caché para consultas frecuentes.

Esta pensando para casos de uso como…

  • Análisis de ventas diarias: Monitoreo de transacciones del día actual.
  • Reportes mensuales: Generación de reportes para análisis financiero.
  • Auditorías: Verificación de transacciones por terminal o zona en específico.
  • Análisis por filtro: Permitiendo ****identificar de patrones de uso.

URL base: https://integrations.payment.haulmer.com/

Autenticación: Todas las solicitudes a esta API requieren autenticación mediante una API Key enviado en el encabezado X-API-Key.

Formato de Datos: JSON.

Autenticación

Todas las solicitudes requieren autenticación mediante una clave API proporcionada por Haulmer (para conocer como obtenerlo, refiérase al siguiente enlace https://developers.tuu.cl/docs/generaci%C3%B3n-de-api-key-en-espacio-de-trabajo).

X-API-Key: YOUR_API_KEY_HERE

Endpoints

POST /BranchReport/branch-report

Genera un reporte de transacciones presenciales por zonas basado en los filtros especificados.

Parámetros de consulta (Query Parameters):

CampoTipoRequeridoDescripción
startDatestringFecha de inicio del reporte en formato YYYY-MM-DD
endDatestringFecha de termino del reporte en formato YYYY-MM-DD (no debe exceder los 30 días)
locationIdstringNoId de la ubicación específica
serialNumberstringNoNúmero de serie del terminal
typeTransactionstringNoTipo de transacción. Por ejemplo: DEBIT, CREDIT, PREPAID y/o CASH
cardBrandstringNoMarca de la tarjeta. Por ejemplo: VISA, MASTERCARD, AMEX y/o MAESTRO
installmentTypestringNoTipo de cuotas (aplica solo a tarjeta de crédito). Ejemplo: COMERCIO, TUU y/o BANCO
pageintNúmero de página. Mínimo 1
pageSizeintElementos por página. Como máximo 20
{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "locationId": "219",
  "serialNumber": "SN123456",
  "typeTransaction": "CREDIT",
  "cardBrand": "VISA",
  "installmentType": "COMERCIO",
  "page": 1,
  "pageSize": 20
}

Ejemplo de solicitud (cURL):

Básica por rango de fechas

curl -X POST "[https://integrations.payment.haulmer.com](https://integrations.payment.haulmer.com/)/BranchReport/branch-report" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "page": 1,
    "pageSize": 20
  }'

Avanzada con todos los filtros

curl -X POST "https://integrations.payment.haulmer.com/BranchReport/branch-report" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate":       "2025-05-01",
    "endDate":         "2025-05-30",
    "locationId":      "198",
    "serialNumber":    "PB1T238321015",
    "typeTransaction": "CREDIT, DEBIT",
    "cardBrand":       "VISA, MASTERCARD, AMEX",
    "installmentType": "BANCO, COMERCIO, TUU",
    "page":            1,
    "pageSize":        10
  }'

Respuesta exitosa (200 OK):

  • partnerId: Identificador interno de Haulmer del comercio.
  • taxId: Identificador tributario del comercio.
  • commerceName: Nombre legal del comercio.
  • locationId: Identificador interno de la ubicación del POS que se utilizó en la transacción.
  • address: Dirección de la ubicación del POS.
  • saleId: Identificador interno de la venta asociado a la transacción.
  • sequenceNumber: Identificador numérico serial de la transacción.
  • serialNumber: Numero serial del POS.
  • status: Estado de la transacción. Por ejemplo: Completed o Reversed.
  • transactionDateTime: Fecha y hora de la transacción.
  • transactionType: Tipo de medio de pago utilizado en la transacción.
  • documentType: Identificador numérico del tipo DTE emitido en la transacción.
  • cardBrand: Marca de la tarjeta utilizada en la transacción.
  • cardBin: Ocho primeros dígitos iniciales del número de identificación bancaria de la tarjeta utilizada.
  • cardOrigin: Origen de la tarjeta utiliza, sea nacional (Chile) o internacional.
  • cardIssuer: Identidad bancaria/comercial de la emisora de la tarjeta.
  • currencyCode: Divisa utilizada en el pago.
  • saleAmount: Monto de la venta.
  • tipAmount: Monto de la propina.
  • cashbackAmount: Vuelto del pago realizado.
  • totalAmount: Monto total cancelado.
  • installmentType: Tipo de cuotas utilizadas en la transacción. Pueden ser bancarias, comercio o TUU (producto interno de Haulmer).
  • installmentCount: Cantidad pagos parcializados (cuotas) de una transacción.
  • acquirerId: Identificador externo PaaS.
  • instance: Instancia interna en dónde se procesó la transacción.
  • code: Código del ítem ingresado (campo de venta por catálogo; producto interno de Haulmer).
  • name: Nombre del ítem ingresado (campo de venta por catálogo; producto interno de Haulmer).
  • quantity: Cantidad del ítem ingresado (campo de venta por catálogo; producto interno de Haulmer).
  • price: Precio del Ítem ingresado (campo de venta por catálogo; producto interno de Haulmer).
{
    "metadata": {
        "code": "BR-00",
        "message": "Success"
    },
    "data": {
        "commerce": {
            "partnerId": "10001",
            "taxId": "767955618",
            "commerceName": "Haulmerinco"
        },
        "transactions": [
            {
                "locationId": "12481",
                "address": "Pasaje falso 666, Curicó, Maule",
                "saleId": "39137",
                "sequenceNumber": "300016711098",
                "serialNumber": "PB30216R20801",
                "status": "completed",
                "transactionDateTime": "2025-05-02T10:31:19",
                "transactionType": "CREDIT",
                "documentType": 48,
                "cardBrand": "MASTERCARD",
                "cardBin": "55898489",
                "cardOrigin": "Internacional",
                "cardIssuer": "CMR",
                "currencyCode": "CLP",
                "saleAmount": 777,
                "tipAmount": 0,
                "cashbackAmount": 0,
                "totalAmount": 777,
                "installmentType": "Banco",
                "installmentCount": 0,
                "acquirerId": "111746200667117953",
                "instance": 1,
                "items": [
                    {
                        "code": null,
                        "name":"Nombre ítem 1",
                        "quantity": 1,
                        "price": 500
                    }
                ]
            }
        ]
    },
    "pagination": {
        "page": 1,
        "pageSize": 10,
        "totalItems": 9,
        "totalPages": 1
    }
}

Códigos de estados

Código internoMensajeDescripción
BR-00SuccessSolicitud procesada exitosamente
BR-01Error generating reportError interno al generar el reporte
BR-02Error validating requestError en la validación de parámetros de entrada
BR-03Invalid date format for start dateFormato de fecha de inicio inválido (debe ser YYYY-MM-DD)
BR-04Invalid date format for end dateFormato de fecha de fin inválido (debe ser YYYY-MM-DD)
BR-05Start date is requiredEl campo startDate es obligatorio
BR-06End date is requiredEl campo endDate es obligatorio
BR-07Invalid date range. Start date must be before end dateLa fecha de inicio debe ser anterior a la fecha de fin
BR-08Date range should not exceed 30 daysEl rango de fechas no puede exceder 60 días
BR-09End date is too oldLa fecha de fin es demasiado antigua (anterior a 2020-01-01)
BR-10End date cannot be in the futureLa fecha de fin no puede ser futura
BR-11Invalid page numberNúmero de página inválido (debe ser >= 1)
BR-13Oops, something went wrongUps, algo salió mal
BR-14Invalid local ID, special characters are not allowedID de ubicación contiene caracteres especiales no permitidos. Evite caracteres de control y espaciados, y caracteres restringidos CSV como: `< > & " ' ;\ / ? * : ( ) + = ! @ # $ % ^ ~
BR-15Invalid serial number, special characters are not allowedNúmero de serie contiene caracteres especiales no permitidos. Evite caracteres de control y espaciados, y caracteres restringidos CSV como: `< > & " ' ;\ / ? * : ( ) + = ! @ # $ % ^ ~
BR-16Invalid type transaction, special characters are not allowed or not supportedTipo de transacción inválido o no soportado. Valores soportados: DEBIT, CREDIT, PREPAID, CASH
BR-17Invalid card brand, special characters are not allowed or not supportedMarca de tarjeta inválida o no soportada. Valores soportados: MASTERCARD, VISA, AMEX, MAESTRO
BR-18No cached report foundNo se encontró reporte en caché (uso interno)
BR-19Failed to deserialize cached reportError al deserializar reporte desde caché (uso interno)
BR-20User not foundUsuario no encontrado
BR-21One or more POS entered do not belong to the account or are not authorizedUno o más terminales ingresados no pertenecen a la cuenta
BR-22One or more locations entered do not belong to the account or are not authorizedUna o más ubicaciones ingresadas no pertenecen a la cuenta
BR-23One or more devices do not correspond to the specified locationsUno o más dispositivos no corresponden a las ubicaciones especificadas
BR-24Page number is out of rangeNúmero de página fuera del rango válido
BR-25User is not in a PaaS planUsuario no tiene acceso al plan PaaS requerido
BR-26Invalid installment type, special characters are not allowed or not supportedTipo de cuotas inválido o no soportado
BR-27No data found for the selected filtersNo se encontraron datos para los filtros seleccionados
BR-28Card brands not allowed for cash-only transactionsPara consulta de transacciones de solo tipo CASH no se acepta filtro de marca por tarjeta
BR-29Installment types not allowed for cash-only transactionsPara consulta de transacciones de solo tipo CASH no se acepta filtro por tipo de cuota
BR-30Oops! The Branch Report service is disabledEl servicio se encuentra deshabilitado
BR-31Card brand filter is not allowed for dates before May 1, 2025Aquellas transacciones anteriores al 1 de mayo del 2025 no tiene permitido el filtro de marca de tarjeta

Mejores prácticas de uso

  1. Paginación: Usar tamaños de página entre 20-50 elementos.
  2. Filtros específicos: Aplicar filtros por ubicación o terminal cuando sea posible.
  3. Rangos cortos: Preferir rangos de 7-15 días para mejor rendimiento.