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):
Campo | Tipo | Requerido | Descripción |
---|---|---|---|
startDate | string | Sí | Fecha de inicio del reporte en formato YYYY-MM-DD |
endDate | string | Sí | Fecha de termino del reporte en formato YYYY-MM-DD (no debe exceder los 30 días) |
locationId | string | No | Id de la ubicación específica |
serialNumber | string | No | Número de serie del terminal |
typeTransaction | string | No | Tipo de transacción. Por ejemplo: DEBIT, CREDIT, PREPAID y/o CASH |
cardBrand | string | No | Marca de la tarjeta. Por ejemplo: VISA, MASTERCARD, AMEX y/o MAESTRO |
installmentType | string | No | Tipo de cuotas (aplica solo a tarjeta de crédito). Ejemplo: COMERCIO, TUU y/o BANCO |
page | int | Sí | Número de página. Mínimo 1 |
pageSize | int | Sí | Elementos 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 interno | Mensaje | Descripción | |
---|---|---|---|
BR-00 | Success | Solicitud procesada exitosamente | |
BR-01 | Error generating report | Error interno al generar el reporte | |
BR-02 | Error validating request | Error en la validación de parámetros de entrada | |
BR-03 | Invalid date format for start date | Formato de fecha de inicio inválido (debe ser YYYY-MM-DD) | |
BR-04 | Invalid date format for end date | Formato de fecha de fin inválido (debe ser YYYY-MM-DD) | |
BR-05 | Start date is required | El campo startDate es obligatorio | |
BR-06 | End date is required | El campo endDate es obligatorio | |
BR-07 | Invalid date range. Start date must be before end date | La fecha de inicio debe ser anterior a la fecha de fin | |
BR-08 | Date range should not exceed 30 days | El rango de fechas no puede exceder 60 días | |
BR-09 | End date is too old | La fecha de fin es demasiado antigua (anterior a 2020-01-01) | |
BR-10 | End date cannot be in the future | La fecha de fin no puede ser futura | |
BR-11 | Invalid page number | Número de página inválido (debe ser >= 1) | |
BR-13 | Oops, something went wrong | Ups, algo salió mal | |
BR-14 | Invalid local ID, special characters are not allowed | ID de ubicación contiene caracteres especiales no permitidos. Evite caracteres de control y espaciados, y caracteres restringidos CSV como: `< > & " ' ; | \ / ? * : ( ) + = ! @ # $ % ^ ~ |
BR-15 | Invalid serial number, special characters are not allowed | Número de serie contiene caracteres especiales no permitidos. Evite caracteres de control y espaciados, y caracteres restringidos CSV como: `< > & " ' ; | \ / ? * : ( ) + = ! @ # $ % ^ ~ |
BR-16 | Invalid type transaction, special characters are not allowed or not supported | Tipo de transacción inválido o no soportado. Valores soportados: DEBIT, CREDIT, PREPAID, CASH | |
BR-17 | Invalid card brand, special characters are not allowed or not supported | Marca de tarjeta inválida o no soportada. Valores soportados: MASTERCARD, VISA, AMEX, MAESTRO | |
BR-18 | No cached report found | No se encontró reporte en caché (uso interno) | |
BR-19 | Failed to deserialize cached report | Error al deserializar reporte desde caché (uso interno) | |
BR-20 | User not found | Usuario no encontrado | |
BR-21 | One or more POS entered do not belong to the account or are not authorized | Uno o más terminales ingresados no pertenecen a la cuenta | |
BR-22 | One or more locations entered do not belong to the account or are not authorized | Una o más ubicaciones ingresadas no pertenecen a la cuenta | |
BR-23 | One or more devices do not correspond to the specified locations | Uno o más dispositivos no corresponden a las ubicaciones especificadas | |
BR-24 | Page number is out of range | Número de página fuera del rango válido | |
BR-25 | User is not in a PaaS plan | Usuario no tiene acceso al plan PaaS requerido | |
BR-26 | Invalid installment type, special characters are not allowed or not supported | Tipo de cuotas inválido o no soportado | |
BR-27 | No data found for the selected filters | No se encontraron datos para los filtros seleccionados | |
BR-28 | Card brands not allowed for cash-only transactions | Para consulta de transacciones de solo tipo CASH no se acepta filtro de marca por tarjeta | |
BR-29 | Installment types not allowed for cash-only transactions | Para consulta de transacciones de solo tipo CASH no se acepta filtro por tipo de cuota | |
BR-30 | Oops! The Branch Report service is disabled | El servicio se encuentra deshabilitado | |
BR-31 | Card brand filter is not allowed for dates before May 1, 2025 | Aquellas transacciones anteriores al 1 de mayo del 2025 no tiene permitido el filtro de marca de tarjeta |
Mejores prácticas de uso
- Paginación: Usar tamaños de página entre 20-50 elementos.
- Filtros específicos: Aplicar filtros por ubicación o terminal cuando sea posible.
- Rangos cortos: Preferir rangos de 7-15 días para mejor rendimiento.
Updated 4 days ago