# Consulta de facturas

Estos endpoints permiten consultar las facturas (CFDIs) emitidas a través de QRwey!
con diferentes niveles de agrupación: por **integrador** (customer), por **emisor** (RFC)
o por **comercio**.

Todos los endpoints comparten los mismos filtros y devuelven el mismo formato de respuesta
paginada.

## Listar facturas por integrador

Devuelve todas las facturas emitidas por todos los comercios del customer autenticado.

### Endpoint

```
GET /v1/qrs/invoices/by-customer
```

**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 |
|  --- | --- |
| `folioUuid` | Filtrar por UUID fiscal (búsqueda parcial, opcional) |
| `search` | Buscar por RFC o razón social del emisor o receptor (opcional) |
| `invoiceStatus` | Filtrar por estatus: `GENERATED`, `CANCELLED`, `CANCEL_REQUESTED`, `CANCEL_IN_PROGRESS`, `ERROR` (opcional) |
| `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/invoices/by-customer?invoiceStatus=GENERATED&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

## Listar facturas por emisor

Devuelve las facturas emitidas por los comercios de un emisor (RFC) específico.

### Endpoint

```
GET /v1/qrs/invoices/by-issuer/{issuerId}
```

### Headers requeridos

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

### Path params

| Parámetro | Descripción |
|  --- | --- |
| `issuerId` | ID del emisor (invoice data) |


### Query params

Los mismos filtros que el endpoint por integrador: `folioUuid`, `search`, `invoiceStatus`, `page`, `size`, `sort`.

### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/invoices/by-issuer/inv_data_4aca0361cfcd41c097663db44008fbb9?page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

## Listar facturas por comercio

Devuelve las facturas emitidas por un comercio específico.

### Endpoint

```
GET /v1/qrs/invoices/by-merchant/{merchantId}
```

### Headers requeridos

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

### Path params

| Parámetro | Descripción |
|  --- | --- |
| `merchantId` | ID del comercio |


### Query params

Los mismos filtros que el endpoint por integrador: `folioUuid`, `search`, `invoiceStatus`, `page`, `size`, `sort`.

### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/invoices/by-merchant/mer_4aca0361cfcd41c097663db44008fbb9?invoiceStatus=GENERATED&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

## Respuesta

Todos los endpoints devuelven el mismo formato paginado con objetos `MerchantInvoice`:

```json
{
  "content": [
    {
      "folioUuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
      "invoiceId": "8f3a1c2d-9b4e-4a7f-91d6-2b8e7c5a1f3d",
      "issuerTaxId": "FUNK671228PH6",
      "issuerLegalName": "KARLA FUENTE NOLASCO",
      "receiverTaxId": "EKU9003173C9",
      "receiverLegalName": "ESCUELA KEMPER URGATE",
      "invoiceDate": "2026-03-19T14:30:00Z",
      "subtotal": 1000.00,
      "iva": 160.00,
      "total": 1160.00,
      "invoiceStatus": "GENERATED"
    }
  ],
  "totalElements": 25,
  "totalPages": 3,
  "number": 0,
  "size": 10
}
```

### Campos de MerchantInvoice

| Campo | Descripción |
|  --- | --- |
| `folioUuid` | UUID fiscal del CFDI |
| `invoiceId` | Identificador interno de la factura |
| `issuerTaxId` | RFC del emisor |
| `issuerLegalName` | Razón social del emisor |
| `receiverTaxId` | RFC del receptor (null si la factura no ha sido timbrada) |
| `receiverLegalName` | Razón social del receptor (null si la factura no ha sido timbrada) |
| `invoiceDate` | Fecha de timbrado |
| `subtotal` | Subtotal del CFDI |
| `iva` | IVA calculado |
| `total` | Total del CFDI |
| `invoiceStatus` | Estatus del CFDI: `GENERATED`, `CANCELLED`, `CANCEL_REQUESTED`, `CANCEL_IN_PROGRESS`, `ERROR` |


## Errores comunes

| Código | Motivo |
|  --- | --- |
| 401 | Token inválido o expirado |
| 404 | Emisor no encontrado |


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

## Buenas prácticas

- Usa los filtros `search` y `invoiceStatus` para localizar facturas rápidamente
- El filtro `folioUuid` permite búsqueda parcial, útil para buscar por fragmento del UUID
- Usa el campo `invoiceId` para obtener el detalle completo con el endpoint de [Detalle de CFDI](/guides/cfdi-detail)


## ¿Qué sigue?

- Obtener detalle completo: [Detalle de CFDI](/guides/cfdi-detail)
- Cancelar un CFDI: [Cancelar CFDI 4.0](/guides/cancel-cfdi)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)