# Reportes del cliente

Los **reportes del cliente** permiten consultar información agregada sobre el uso de facturación
de tu cuenta en QRwey!. Estos endpoints son útiles para analizar patrones de consumo,
identificar RFCs recurrentes y evaluar la tarifa más conveniente.

## Top RFCs por transacciones

Obtiene los RFCs con mayor número de transacciones realizadas en tu cuenta.

### Endpoint

```
GET /v1/qrs/customers/reports/top-rfc
```

**Host (DEV):**

```
https://api-dev.qrwey.com
```

**Host (PROD):**

```
https://api.qrwey.com
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Query params

| Parámetro | Descripción |
|  --- | --- |
| `limit` | Número máximo de resultados (default: 10) |


### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/customers/reports/top-rfc?limit=5" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "topRfc": [
    {
      "taxId": "EKU9003173C9",
      "invoiceCount": 142
    },
    {
      "taxId": "FUNK671228PH6",
      "invoiceCount": 87
    }
  ]
}
```

### Campos de TopRfcResponse

| Campo | Descripción |
|  --- | --- |
| `topRfc` | Lista de RFCs ordenados por número de facturas |
| `topRfc[].taxId` | RFC del receptor |
| `topRfc[].invoiceCount` | Número total de facturas emitidas |


## Historial de consumo de facturas

Obtiene el historial paginado de consumo de facturas de tu cuenta.

### Endpoint

```
GET /v1/qrs/customers/reports/invoice-usage
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Query params

| Parámetro | Descripción |
|  --- | --- |
| `page` | Número de página (default: 0) |
| `size` | Elementos por página (default: 20) |
| `sort` | Campo y dirección de ordenamiento (ej. `createdAt,desc`) |


### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/customers/reports/invoice-usage?page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "content": [
    {
      "customerInvoiceUsageId": "ciu_4aca0361cfcd41c097663db44008fbb9",
      "customerId": "cus_8b3f0a61cfcd41c097663db44008fcc1",
      "month": "MARCH",
      "year": 2026,
      "budgetPlanName": "Plan Pro",
      "appliedBudgetPlan": { },
      "budgetBaseCost": 990.00,
      "budgetInvoices": 500,
      "generatedInvoices": 245,
      "rfcFullCount": 12,
      "rfcFullCost": 240.00,
      "rfcLightCount": 5,
      "rfcLightCost": 50.00,
      "extraCfdiCount": 0,
      "extraCfdiCost": 0.00,
      "totalCost": 1280.00
    }
  ],
  "totalElements": 12,
  "totalPages": 2,
  "number": 0,
  "size": 10
}
```

### Campos de CustomerInvoiceUsageResponse

| Campo | Descripción |
|  --- | --- |
| `customerInvoiceUsageId` | Identificador único del registro de consumo |
| `customerId` | Identificador del cliente |
| `month` | Mes del periodo de consumo (ej. `JANUARY`, `FEBRUARY`, etc.) |
| `year` | Anio del periodo de consumo |
| `budgetPlanName` | Nombre del plan de facturación aplicado |
| `appliedBudgetPlan` | Detalle del plan de facturación aplicado en el periodo |
| `budgetBaseCost` | Costo base del plan contratado |
| `budgetInvoices` | Número de facturas incluidas en el plan |
| `generatedInvoices` | Número de facturas generadas en el periodo |
| `rfcFullCount` | Número de RFCs con validación completa (CSF) |
| `rfcFullCost` | Costo total por validaciones completas de RFC |
| `rfcLightCount` | Número de RFCs con validación ligera |
| `rfcLightCost` | Costo total por validaciones ligeras de RFC |
| `extraCfdiCount` | Número de CFDIs adicionales (fuera del plan) |
| `extraCfdiCost` | Costo total por CFDIs adicionales |
| `totalCost` | Costo total del periodo |


## Tarifa óptima

Calcula la tarifa más conveniente para tu cuenta basándose en el histórico de consumo.

### Endpoint

```
GET /v1/qrs/customers/reports/optimal-tariff
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/customers/reports/optimal-tariff" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "budgetPlanId": "bp_4aca0361cfcd41c097663db44008fbb9",
  "name": "Plan Pro",
  "baseCost": 990.00,
  "fullRfcCount": 12,
  "fullRfcCost": 240.00,
  "lightRfcCount": 5,
  "lightRfcCost": 50.00,
  "extraStampsCount": 0,
  "extraStampsCost": 0.00,
  "totalCost": 1280.00,
  "invoiceCount": 245,
  "uniqueCost": 5.22
}
```

### Campos de OptimalTariffResponse

| Campo | Descripción |
|  --- | --- |
| `budgetPlanId` | Identificador del plan de facturación óptimo |
| `name` | Nombre del plan recomendado |
| `baseCost` | Costo base del plan |
| `fullRfcCount` | Número estimado de validaciones completas de RFC |
| `fullRfcCost` | Costo estimado por validaciones completas |
| `lightRfcCount` | Número estimado de validaciones ligeras de RFC |
| `lightRfcCost` | Costo estimado por validaciones ligeras |
| `extraStampsCount` | Número estimado de timbrados adicionales |
| `extraStampsCost` | Costo estimado por timbrados adicionales |
| `totalCost` | Costo total estimado con el plan óptimo |
| `invoiceCount` | Número de facturas consideradas en el cálculo |
| `uniqueCost` | Costo unitario por factura con el plan óptimo |


## Errores comunes

| Código | Motivo |
|  --- | --- |
| 401 | Token inválido o expirado |
| 403 | No tienes permisos para consultar reportes |


Consulta: [Manejo de errores](/guides/error-handling)

## Buenas prácticas

- Consulta el reporte de top RFCs para identificar clientes recurrentes y ofrecer mejor servicio
- Revisa periódicamente el historial de consumo para detectar tendencias
- Evalúa la tarifa óptima regularmente para asegurarte de estar en el plan más conveniente


## ¿Qué sigue?

- Consulta transacciones de un comercio: [Gestión de transacciones](/guides/transactions)
- Administra tus grupos: [Gestión de grupos](/guides/groups)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)