Generación de reportes

Introducción

La API de Reportes está diseñada para facilitar la integración entre sistemas externos y la plataforma, permitiendo generar y recuperar reportes de transacciones de nuestros clientes.

Propósito

Esta API está dirigida a desarrolladores e integradores que buscan automatizar la generación y consulta de reportes de transacciones, proporcionando acceso a datos detallados que pueden ser utilizados para análisis y conciliación de cuentas.

Público objetivo

La API está destinada principalmente a desarrolladores de software que necesitan acceso directo a la información de transacciones realizadas por sus dispositivos POS para la generación de reportes.

⚠️

Para generar reportes debe solicitar una API Key válida en su espacio de trabajo. En caso de problemas, contáctese con soporte.

Diagrama alto nivel

¿Cómo generar un reporte?

Envía una solicitud POST al endpoint para generar un reporte de transacciones. Este reporte se basa en filtros específicos, como el rango de fechas y el número de serie del terminal.

POST /Report/get-report

Ejemplo de uso

curl -X POST "https://integrations.payment.haulmer.com/Report/get-report" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: YOUR_API_KEY" \
     -d '{
           "Filters": {
             "StartDate": "2024-01-01",
             "EndDate": "2024-01-31",
             "SerialNumber": "PN74233A30842"
           },
           "page": 1,
           "pageSize": 10
         }'

Parámetros de entrada

Headers

• X-API-Key: ApiKey
• Content-Type: application/json

Body Request

El cuerpo de la solicitud debe contener los siguientes campos:

{
  "Filters": {
    "StartDate": "2024-01-01",
    "EndDate": "2024-01-31",
    "SerialNumber": "PN74233A30842"
  },
  "page": 1,
  "pageSize": 10
}

☝️

Si desea conocer los POS asociados a su comercio, debe hacer uso del endpoint GET /SerialNumbersDevice/get-serial-numbers-device/

Datos Solicitados

Parámetros de salida

Respuesta exitosa

• 200 OK:

  JSON

  {
      "code": "200",
      "message": "Report generated successfully.",
      "content": {
          "commerce": {
              "partnerId": "123",
              "commerceName": "Boxbox"
          },
          "reports": [
              {
                  "saleId": "21688",
                  "sequenceNumber": "N/A",
                  "posSerialNumber": "PN74233A30842",
                  "status": "Completed",
                  "amount": 600.00,
                  "currency": "CLP",
                  "typeTransaction": "Cash",
                  "paymentDataTime": "2024-04-10T09:16:18.123",
                  "extraData": {
                      "items": [
                          {
                              "code": null,
                              "quantity": 1.00,
                              "name": "Item Manual",
                              "price": 600
                          }
                      ],
                      "amountCommission": 0,
                      "amountWithoutCommission": 600.00
                  },
                  "reconciliations": [
                      {
                           "paymentDate": "",
                           "installmentNumber": 0,
                           "amount": 0,
                           "reconciliationId": "No reconciliation"
                      }
                  ],
              },
              {
                  "saleId": "21689",
                  "sequenceNumber": "000000040449",
  	                "posSerialNumber": "PN74233A30842",
                  "status": "completed",
                  "amount": 100.00,
                  "currency": "CLP",
                  "typeTransaction": "CREDIT",
                  "paymentDataTime": "2024-04-10T16:55:52.733",
                  "extraData": {
                      "items": [
                          {
                              "code": "",
                              "quantity": 1.00,
                              "name": "Item Manual",
                              "price": 100
                          }
                      ],
                      "amountCommission": 2.00,
                      "amountWithoutCommission": 98.00
                  },
                "reconciliations": [
                      {
                           "paymentDate": "2024-05-07",
                           "installmentNumber": 1,
                           "amount": 300,
                           "reconciliationId": "3777"
                      },
                  		{
                           "paymentDate": "2024-06-07",
                           "installmentNumber": 2,
                           "amount": 300,
                           "reconciliationId": "Not yet available"
                      }
                ]
             }
          ],
          "totalItems": 174,
          "totalPages": 18,
          "page": 1
      }
  }

  Descripción detallada de los campos retornados

  Campo	Tipo	Descripción
  Commerce	object	Información del comercio asociado al reporte.
  Reports	array	Lista de reportes generados basados en los filtros.
  TotalItems	int	Total de registros encontrados que coinciden con los filtros.
  TotalPages	int	Total de páginas disponibles según el pageSize.
  Page	int	Número de la página actual.

  Campo Commerce

  Campo	Tipo	Descripción
  PartnerId	string	Identificador del comercio asociado.
  CommerceName	string	Nombre del comercio.

  Campo Report

  Campo	Tipo	Descripción
  SaleId	string	Identificador de la venta.
  SequenceNumber	string	Número de secuencia asociado a la transacción.
  PosSerialNumber	string	Número de serie del punto de venta (POS).
  Status	string	Estado de la transacción (p.ej., completed).
  Amount	decimal	Monto de la transacción.
  Currency	string	Moneda de la transacción.
  TypeTransaction	string	Tipo de transacción (p.ej., CREDIT, DEBIT o CASH).
  PaymentDataTime	DateTime	Fecha y hora del pago.
  ExtraData	ExtraData	Datos adicionales sobre la transacción.
  Reconciliations	Reconciliation	Información respecto a la reconciliación de la trx.

  Campo ExtraData

  Campo	Tipo	Descripción
  Items	List<Item>	Lista de ítems asociados a la transacción.
  AmountCommission	decimal	Comisión + IVA aplicado sobre la comisión.
  AmountWithoutCommission	decimal	Monto de la transacción sin incluir comisiones.

  Campo Item

  Campo	Tipo	Descripción
  Code	string	Código del ítem.
  Quantity	decimal	Cantidad del ítem.
  Name	string	Nombre del ítem.
  Price	decimal	Precio unitario del ítem.

  Campo Reconciliation

  Campo	Tipo	Descripción
  PaymentDate	string	Posible fecha de pago de la cuota.
  InstallmentNumber	int	Número de la cuota.
  Amount	double	Monto de la cuota.
  ReconciliationId	int	Identificador de la reconciliación.

  
  

Errores Comunes

• 401 Unauthorized: Credenciales inválidas.
• 400 Bad Request: Errores en los filtros proporcionados.
• 404 Not Found: No existen datos relacionados con la consulta.
• 500 Internal server error: Error interno del servidor.

Formato de Respuesta de Error

Cuando se encuentre un error, se retornará un JSON con la estructura estándar de error:

{
  "code": "400",
  "message": "StartDate must be a valid calendar date."
}

Tabla de errores conocidos