# Listar facturas

> `GET https://api.cfdi.express/v1/invoices` — Lista facturas con filtros por emisor, tipo, estatus, método de pago, UUID y rango de fechas. Paginación por cursor.

URL de esta página: https://cfdi.express/docs/api/listar-facturas
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)

Las notas de crédito viven en la misma colección: fíltralas con `kind=credit_note`.

### Query string

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | integer | no | Elementos por página. Entre 1 y 100. Default 10. |
| `starting_after` | string | no | Id de la última factura de la página anterior (cursor). |
| `merchantId` | string | no | Filtra por emisor. |
| `kind` | string | no | nominal, global o credit_note. |
| `status` | string | no | stamping, stamped, stamp_failed, cancel_pending o cancelled. |
| `uuid` | string | no | Busca por folio fiscal (UUID) del SAT. |
| `metodoPago` | string | no | PUE o PPD. |
| `createdFrom` | string | no | Fecha ISO 8601 mínima de creación. |
| `createdTo` | string | no | Fecha ISO 8601 máxima de creación. |

## Ejemplos

### cURL

```bash
curl -G https://api.cfdi.express/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "status=stamped" \
  --data-urlencode "metodoPago=PPD" \
  --data-urlencode "createdFrom=2026-08-01T00:00:00Z" \
  --data-urlencode "limit=20"
```

### Node.js — paginación

```javascript
const all = [];
let cursor;

do {
  const url = new URL("https://api.cfdi.express/v1/invoices");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("starting_after", cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.CFDI_API_KEY}` },
  }).then((r) => r.json());

  all.push(...page.data);
  cursor = page.has_more ? page.data.at(-1).id : undefined;
} while (cursor);
```

## Respuesta

### 200 OK

```json
{
  "object": "list",
  "data": [
    {
      "id": "inv7k3q9x2m4v1t8p6d0n5cb",
      "object": "invoice",
      "livemode": false,
      "status": "stamped",
      "kind": "nominal",
      "uuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "serie": "A",
      "folio": 128,
      "folioText": "#1001",
      "metodoPago": "PPD",
      "formaPago": "99",
      "usoCfdi": "G03",
      "currency": "MXN",
      "subtotal": 3163.79,
      "discount": 0,
      "total": 3670.00,
      "saldoPendiente": 1670.00,
      "receiver": {
        "rfc": "XIA190128J61",
        "name": "XENON INDUSTRIAL ARTICLES",
        "zip": "01160",
        "regimenFiscal": "601"
      },
      "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
      "files": { "status": "ready" },
      "cancellation": null,
      "stampedAt": "2026-08-18T17:42:10.512Z",
      "createdAt": "2026-08-18T17:42:08.907Z"
    }
  ],
  "has_more": true
}
```

## Errores

| Status | code | Cuándo aparece |
|---|---|---|
| 401 | `unauthorized` | Falta el header Authorization o la llave es inválida. |
| 429 | `rate_limited` | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |

## Relacionados

- [GET /v1/invoices/{id}](https://cfdi.express/docs/api/obtener-factura) — Obtener factura
- [POST /v1/invoices](https://cfdi.express/docs/api/timbrar-factura) — Timbrar factura

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express